← Harness
OpenAI Agents SDK
OpenAI
Python
开源
MIT
编程底座
通用harness
guardrails
MCP
human-in-the-loop
sandbox
partial
lifecycle: active
核验 2026-09-30
「primitives-only 的多agent harness」 —— 官方自述 lightweight yet powerful： 只给agent loop 的原语，不替你决定 filesystem / 规划 / 记忆怎么做。
适合与不适合
适合：要薄 harness + 要内建 guardrails/human-in-the-loop + 要 MCP 一等支持 + Python 栈。 不适合：要开箱即用的长任务工作区（用 Deep Agents 或走 SandboxAgent 路线）；TypeScript 生态（用 openai-agents-js）。
固定坐标系
8 个维度，与同赛道其他对象逐项可比。
- 模型与开放条件
- 官方自述 provider-agnostic，README 首段原文： 「It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs.」 实现路径有两层证据：核心依赖是
openai>=3.0.0；可选依赖里有litellm（openai-agents[litellm]）与any-llm（openai-agents[any-llm]，要求 Python ≥3.11）。 换 provider 的实际改动量本站未核验（文档说 provider-agnostic，但没给「零改动」的量化承诺）。 - 运行位置
- 你自己运营进程 —— 它是库不是服务。README 的四种运行方式全部是本地代码调用 （
Runner.run_sync/RealtimeRunner.run/VoicePipeline.run/ sandbox client）。 唯一例外是 SandboxAgent 的 hosted sandbox client —— 官方提到可以用托管沙箱， 但那依赖 OpenAI 侧的容器服务，不是「整个 agent 托管」。 - 本地文件
- 本地文件能力明确存在但不在默认 agent 里。官方为「需要检查文件、跑命令、打补丁、 或在长任务间保留工作区状态」的场景单独提供了
SandboxAgent： README 原文说 SandboxAgent 是 preconfigured to work with a container to perform work over long time horizons，且 default_manifest 里可以声明GitRepo(repo=..., ref=...)。 沙箱客户端分平台：UnixLocalSandboxClient（macOS / Linux）； Windows 须用DockerSandboxClient（需openai-agents[docker]extra）或 hosted sandbox client。 这条是本站选型时的实用信息：Windows 用户不能直接用本地 Unix 沙箱路径。 - 关机后的任务
- 自托管 = 关了就停。 README 没有托管执行选项（Realtime 是长连接但进程仍在自己手里）。 断点续跑有官方支撑：Sessions 章节写明「Automatic conversation history management across agent runs」，配合 SQLite（SQLAlchemy 依赖）与 Redis（
openai-agents[redis]）后端。 SandboxAgent 的 default_manifest 也面向「preserve workspace state across longer tasks」。 - 工具与扩展
- 工具面是官方列出的四类：functions、MCP、hosted tools，以及 agents as tools （把别的 agent 当工具调，与 handoffs 并列为核心委派机制）。 MCP 是核心依赖而非可选：
mcp=1.19.0,3在dependencies里（不是 optional-dependencies）—— 这说明 MCP 接入是SDK 的一等能力。 Guardrails 可配置：官方列「Configurable safety checks for input and output validation」， 分 input 与 output 两个方向。 - 上下文与记忆
- 官方原文只有 Sessions：Automatic conversation history management across agent runs。 可选后端有 Redis（
openai-agents[redis]）与 SQLAlchemy（SQLAlchemy + asyncpg 依赖）。 注意与本站主张的分野：Sessions 管的是会话历史， 本站的「状态 ≠ 上下文」主张里，把大工具输出落盘这类手段在本 SDK 属用户自建 （SandboxAgent 的沙箱工作区可以承担这个角色，但官方没有把它宣传成 context 管理层）。 - 权限与限制
- 内建 Guardrails（输入 + 输出双向校验）+ Human in the loop（跨多次运行引入人工） —— 这是本站目前见到的权限面最完整的内建方案： 「Configurable safety checks for input and output validation」与 「Built-in mechanisms for involving humans across agent runs」。 与 Deep Agents 的「trust the LLM，边界责任交给你」形成鲜明对照。 具体边界强度本次未核验（guardrail 能否拦住文件/网络访问类型的越权，文档未在README 展开）。
- 适合什么任务
- 适合：想要「薄 harness」—— 只要 agent loop 原语，filesystem / 规划 / 记忆都想自己挑； 需要 guardrails 与 human-in-the-loop 是内建的；需要 MCP 一等支持；团队是 Python 栈。 不适合：想要开箱即用的长任务工作区（用 Deep Agents 或该 SDK 的 SandboxAgent 路线）； 追求 TypeScript 生态（该用 openai-agents-js）。
头号误解
- 以为「provider-agnostic」= 换provider 零改动 —— 文档给了 100+ 的承诺但没给量化保证，本站标记为未核验
- 以为 SandboxAgent 在 Windows 上开箱可用 —— 本地路径只有
UnixLocalSandboxClient（macOS/Linux），Windows 要走 Docker 或 hosted - 以为 Guardrails 能当权限护栏用 —— 它是输入/输出校验，不是沙箱边界；两者能解决的风险类型不同
- 以为这是 OpenAI 闭源 SDK 的「官方壳」 —— 它本身是 MIT 开源框架，官方明确「committed to continuing to build the Agents SDK as an open source framework」
价格
| 月度入口 | 库本身免费（MIT） |
|---|---|
| 额度说明 | 框架免费 ≠ 运行免费。 库是 MIT 开源的，但： （1）默认需要 OPENAI_API_KEY，模型推理费用自理； （2）官方示例全部以 OpenAI 模型为主； （3）Traces 默认上报到 OpenAI 的后端（可用 trace 相关开关禁用）。 |
不同币种不做折算。优惠、地区、税费与登录后报价可能变化，购买前请到官方页面确认。
未知项清单
- 100+ provider 各自的能力对齐度矩阵
- guardrail 与沙箱边界的职责划分边界
- hosted sandbox client 的定价、可用区域、配额
- Sessions 后端在多进程/多机下的并发写语义
- litellm / any-llm extra 的实际依赖体积与升级冲突
证据来源
判断可回到以下一手源复核。本站核验日 2026-09-30，内容更新日 2026-09-30。
| 类型 | 名称 | 链接 |
|---|---|---|
| repo | OpenAI Agents SDK · 仓库（Python） | https://github.com/openai/openai-agents-python |
| docs | 官方文档首页 | https://openai.github.io/openai-agents-python/ |
| docs | Sandbox agents（官方专章） | https://openai.github.io/openai-agents-python/sandbox_agents |
| docs | Guardrails（官方专章） | https://openai.github.io/openai-agents-python/guardrails/ |
| docs | Human in the loop（官方专章） | https://openai.github.io/openai-agents-python/human_in_the_loop/ |
| docs | Sessions（官方专章） | https://openai.github.io/openai-agents-python/sessions/ |
| docs | Sandbox clients（平台差异与 hosted client） | https://openai.github.io/openai-agents-python/sandbox/clients/ |
| repo | Agents SDK JS/TS（独立仓，MIT，3,882★，核验 2026-09-30） | https://github.com/openai/openai-agents-js |
| changelog | Releases（0.22.3 @ 2026-09-17） | https://github.com/openai/openai-agents-python/releases |
实测记录
本站尚未完成实测。测试协议见 tasks/_protocol.md。 实测建议（按 harness 赛道五维度定制到这个 SDK 的重点）： | # | 测什么 | 为什么值得测 | |:--:|---|---| | 1 | 最小 hello agent 要几个文件、多少行 | 官方称 lightweight，要验证「薄」到什么程度 | | 2 | Guardrails 能不能拦住「读文件」类越权 | 官方定位是 input/output 校验，与文件访问权限不是一回事 | | 3 | SandboxAgent 在 Windows 上的最小可用路径 | 官方示例是 Unix，Windows 要另走 Docker | | 4 | 换成 litellm / any-llm 接本地模型要改多少 | 官方说 provider-agnostic，验证真实改动量 | | 5 | Sessions 断掉进程后恢复状态是否完整 | 这是本站最关心的「可靠长期运行」 |
相关条目
- Deep Agents本站最值得对照的一对：Deep Agents 是 batteries-included（含 filesystem + 子代理 + 上下文管理），本 SDK 是 primitives-only。同一决策树的两个分支。
- Claude Agent SDK同为「编程底座」档，且同样出自模型厂商。OpenAI 侧走 primitives-only + guardrails 内建，Anthropic 侧的主场是 Claude Code。
- LangGraphLangGraph 是 graph runtime，OpenAI Agents SDK 是 agent harness —— 可组合（把图当工具/子代理），但层级不同。
本页由 ai-agent-guide 数据层生成（CC BY 4.0）。
方法论与坐标系定义见仓库内 METHODOLOGY.md。