OpenAI Agents SDK

OpenAI Agents SDK 是 OpenAI 在 2025 年 3 月随 Responses API（响应 API）一起发布的开源 Agent 编排 SDK，用来把模型、工具、handoff、guardrails、tracing、沙箱执行和长时任务 harness 组织成可运行的单 Agent 或多 Agent 工作流。

它继承并产品化了 OpenAI 早期实验项目 Swarm 的一部分思路，但定位更接近生产编排层：Responses API 负责模型调用与内置工具，Agents SDK 负责把多个 Agent、业务函数工具和控制逻辑组合起来。OpenAI 的 Agents SDK 指南进一步把边界说得更直白：当应用想自己拥有循环时用 Responses API；当应用希望 SDK 运行循环时用 Agents SDK。

核心构件

构件	作用
Agents	配置具体 Agent 的模型、指令和可用工具
Tools	把业务函数、Web search 等能力暴露给 Agent 调用
Handoffs	在多个专职 Agent 之间转移控制权
Guardrails	对输入、输出或动作做安全与质量检查
Tracing & Observability	记录执行 trace，便于调试、评估和优化
Sandbox execution	在受控工作区里运行 shell、读写文件、安装依赖和执行代码
Manifest	描述 Agent 工作区挂载、输出目录和外部存储来源的 SDK 抽象

这组构件对应 Agentic System Patterns（智能体设计模式）里的 routing、orchestrator-workers、decentralized handoff 和 evaluator-optimizer 等模式。SDK 本身不是“让模型自动变聪明”的魔法层，而是把 Harness Engineering（驾驭工程）中反复出现的编排原语固化成 API。

2026：面向长时任务的 harness 与沙箱

OpenAI 2026 年 4 月 15 日的更新把 Agents SDK 从“编排 Agent 与工具”进一步推进到“提供模型原生 harness + 原生沙箱执行”。官方文章明确把新能力定位在文件、命令、代码编辑和长视野任务：开发者可以给 Agent 一个受控 workspace、明确 instructions 和可用工具，让它在文件系统与 shell 中完成多步工作。

这次更新的关键不是多了一个工具，而是把 Codex式软件 Agent 常见原语放进 SDK harness：可配置 memory、沙箱感知编排、文件系统工具、Model Context Protocol（模型上下文协议）、Agent Skills、AGENTS.md、shell、apply_patch 等。换句话说，SDK 正在把 coding-agent harness 里的“工作台能力”抽象成应用开发者可复用的基础设施。

沙箱侧，SDK 支持开发者自带沙箱，也支持 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 等提供商。Manifest 抽象用于描述工作区：本地目录如何挂载、输出写到哪里、数据如何从 AWS S3、Google Cloud Storage、Azure Blob Storage、Cloudflare R2 等存储进入沙箱。它的设计目的不是让模型自由摸索文件系统，而是给模型一个可预测的任务环境：输入在哪里、输出写哪里、长期任务如何组织中间文件。

flowchart LR
    U["用户目标 / 应用请求"] --> H["Agents SDK harness\nagent loop / memory / tools"]
    H --> M["模型"]
    H --> T["MCP / Skills / shell / apply_patch"]
    H --> S["受控 sandbox\n文件系统 / 依赖 / 命令执行"]
    S --> O["输出目录 / 外部存储"]

这也改变了 SDK 与 Agent Sandbox（Agent 沙箱）的关系：沙箱不再只是应用自己外接的执行层，而成为 SDK 运行配置中的一等对象。开发者仍需负责敏感数据边界、审批、日志和合规，但不必从零拼装“Agent 如何安全读写文件与运行命令”的基础设施。

与 Responses API 的关系

Responses API 是底层模型与工具调用接口；OpenAI Agents SDK 是上层编排库。一个简单应用可以直接调用 Responses API；当系统需要多个 Agent、handoff、统一 trace 或可复用 guardrail 时，再引入 SDK。

OpenAI 发布文明确说明，Agents SDK 可与 Responses API 和 Chat Completions API 一起使用，也可以接入提供 Chat Completions 风格端点的其他模型提供商。这意味着 SDK 的抽象边界在“编排与 harness”，而不完全绑定单一模型端点。

在工具使用上，SDK 不改变 OpenAI API Tools（OpenAI API 工具）的基本语义，而是把接线位置从单次请求移动到 Agent 定义和工作流设计里：可以把托管工具、函数工具或 MCP 工具挂到某个 specialist agent 上，也可以把一个 specialist agent 暴露成 manager agent 可调用的工具。Shell、apply patch、computer use 等执行 harness 仍需要运行时提供权限、沙箱和审计边界。

官方指南给出的选型可以压缩成一句话：Responses API 暴露 response 和工具调用原语；Agents SDK 暴露 agent run。 前者适合应用自己写工具路由、循环、分支和状态管理；后者适合让 SDK 管理重复工具调用、handoff 后的 Agent 切换、sessions、tracing、guardrails 和可恢复审批流程。

SDK runner 的语义也因此不同于一次 API 调用：它会执行工具循环，在 handoff 后切换到新的 Agent，并在 run 完成或因审批暂停时停止。对客服、退款、内部运营这类事务型工作流来说，这比直接手写 while loop 更贴近产品代码；对单次检索、生成带引用答案或高度自定义的模型功能来说，Responses API 往往更轻。

阅读路径

OpenAI 的 Agents SDK 文档把学习路径按能力拆开，而不是只给一个总教程：

目标	优先阅读
跑通第一个代码式 Agent 应用	Quickstart
定义单个 specialist 的职责边界	Agent definitions
理解运行时循环、streaming 和 continuation strategy	Running agents
设计多 Agent 责任边界	Orchestration and handoffs
增加校验、审批和人工复核	Guardrails and human review
让应用逻辑消费 run 结果和可恢复状态	Results and state
排查和改进运行质量	Integrations and observability、eval workflows

这个阅读顺序本身透露了 SDK 的设计重心：先把一个 Agent 的契约写清楚，再逐步加入运行时状态、多 Agent 编排、guardrail、trace 和 eval。它不是 prompt 模板集合，而是 Agent 应用的代码组织方式。

Trace grading 与 workflow eval

Agents SDK 里的 tracing 不只是排错工具，也是 Evals（评估）的入口。OpenAI 的 Agent workflow eval 指南建议：代码式 SDK 工作流应先通过 Integrations and observability 产出高信号 trace，再在 dashboard 里对代表性 trace 创建 grader，检查工具选择、handoff、指令遵守和安全策略是否符合预期。

当 trace grading 已经让团队知道“好 run”应该满足哪些条件后，再把这些条件迁移到 dataset 和 eval run，用于比较 prompt、路由逻辑、工具表面、guardrail 或模型版本的变化。也就是说，SDK 的可观测性和评估不是两套系统：trace 捕捉真实执行过程，grader 把行为判断结构化，dataset/eval run 把这种判断变成长期回归。

OpenAI Cookbook 的 agent improvement loop 示例进一步把 tracing 放进完整改进飞轮：Agents SDK 生成 trace，人类和 LLM 对 trace 提供反馈，反馈生成 Promptfoo eval，HALO 结合 trace、反馈、eval gate 与 harness config 输出 Codex handoff。这里 SDK 的职责不是自动优化自己，而是提供可复用、可审计的行为证据。

适用场景

客服自动化：分诊 Agent 根据意图 handoff 给退款、订单或技术支持 Agent
多步骤研究：研究 Agent 结合 Web search、File search 与业务工具收集证据
内容生成：不同 Agent 分别承担草稿、审校、合规检查
代码审查：实现 Agent 与 Review Agent 分离，降低自我偏好偏差
销售拓展：研究账号、生成线索、更新 CRM 等步骤由不同工具和 Agent 协作

并行 Agent 编排

OpenAI Cookbook 的 Parallel Agents with the OpenAI Agents SDK 展示了两条并行路径：一种是在应用代码中用 asyncio.gather 同时运行多个 Runner.run，再把输出交给 MetaAgent；另一种是把 specialist agent 用 as_tool() 暴露给 MetaAgent，并开启 parallel_tool_calls=True，让 planner 动态决定调用哪些 agent 工具。

前者更像显式工作流图，适合延迟敏感、流程固定、需要自定义 fan-out/fan-in 的场景；后者更像 Manager pattern，写法方便，但会引入额外规划调用、工具对象上下文和更高延迟。这个取舍说明：Agents SDK 支持并行运行多个 specialist agent 并汇总结果，但并行不是默认目标。先确认子任务彼此独立、输出协议稳定、并行节省的 wall-clock latency 能抵消额外 token 和调度成本，再把它引入生产链路。

与 Claude Agent SDK 的差异

Claude Agent SDK和 OpenAI Agents SDK 都把工具循环、状态和编排封装进库，但默认重心不同。OpenAI Agents SDK 起初更像 Responses API 之上的应用编排层，强调 Agent definitions、handoff、guardrails、tracing 和业务函数工具；2026 年沙箱更新后，它开始吸收更多 Codex 式文件系统、shell、代码编辑与长时任务能力。Claude Agent SDK 则更像 Claude Code 的库化形态，默认就带文件读写、Bash、代码搜索、编辑、Hook、权限、session、MCP 和 subagent 等软件工程 Agent 能力。

因此，前者更适合从业务流程和多 Agent handoff 设计产品代码；后者更适合把 Claude Code 风格的代码库操作、文件系统自动化和内部工具调用嵌入自己的基础设施。两者都要求开发者认真处理沙箱、审批、审计、成本和评估，SDK 只减少重复 harness 代码，不替代生产治理。