OpenAI Agents SDK

OpenAI Agents SDK 是 OpenAI 官方推出的 Python 和 TypeScript 框架，用于构建生产级的多智能体应用程序。该框架于 2025 年 3 月 15 日发布，取代了 OpenAI 早期的实验性编排原型 Swarm，并作为免费的 MIT 许可库在 PyPI 和 npm 上发布。该 SDK 与 OpenAI 的 Responses API 协同工作，为开发者提供了一种结构化的方式来定义智能体、连接工具、在智能体之间交接工作，并在任何内容触达用户之前验证其输入和输出。

其核心原语被刻意设计得非常精简：智能体（被赋予指令和工具的 LLM）、交接（基于意图从一个智能体路由到另一个智能体）、护栏（可以中止或重定向执行的输入和输出验证）以及追踪（用于调试和监控的内置工作流可视化）。除此之外，该 SDK 还支持 Model Context Protocol (MCP) 服务器集成、持久化会话管理、human-in-the-loop（人机协同）审批网关、通过 Realtime API 结合 gpt-realtime-1.5 实现的语音智能体，以及（截至 2026 年 4 月更新）能够在隔离的容器环境中执行代码、检查文件和运行命令的 Sandbox 智能体。

2026 年 5 月的 OpenAI Agents SDK 现状

Python SDK 目前版本为 v0.15.1（2026 年 5 月 2 日发布），自发布以来共进行了 92 次版本更新，并在 GitHub 上获得了 25,800+ 颗星。TypeScript 版本于 2025 年 6 月加入，并在 2026 年 4 月达到了 v0.8.5。两者均采用 MIT 许可，并可与 OpenAI 的 Responses API 以及任何兼容 Chat Completions 的端点配合使用，这意味着开发者可以通过 LiteLLM 或类似适配器路由到非 OpenAI 模型。

在 Python 中创建一个极简的智能体只需四行代码。智能体的定义包括名称、一组指令以及可选的工具列表。Runner.run_sync() 调用负责处理完整的智能体循环：调用模型、处理工具调用、管理交接并返回最终输出。追踪系统会自动记录每一步，并将其呈现在与 OpenAI 平台绑定的可视化仪表板中。

2026 年 4 月的 Sandbox 智能体更新引入了基于容器的执行：智能体现在可以检查文件、运行 shell 命令、应用代码补丁、安装包，并在较长的任务中保持工作区状态。此功能目前仅在 Python SDK 中可用，TypeScript 支持已列入计划，但尚未确定具体时间表。同次更新还预览了“子智能体（subagents）”（在主智能体下进行并行任务分解）和“代码模式（code mode）”，在撰写本文时，这两项功能仍在路线图中。

对 MCP 服务器的支持意味着任何通过 Model Context Protocol 暴露的工具都可以像函数工具一样连接到 SDK，这使得 Agents SDK 能够无需自定义集成工作即可访问不断增长的 MCP 生态系统。OpenAI 提供的托管工具（包括网络搜索、文件搜索和代码解释器）原生可用，但会将智能体数据绑定到 OpenAI 的平台存储中。

Agents SDK 与 LangGraph 及 Anthropic Claude Agent SDK 的对比定位

对于构建复杂工作流的团队来说，LangGraph 是架构上最接近的替代方案。它使用有向图模型：智能体是节点，条件边控制状态转换，并且该框架支持循环工作流、通过内置检查点实现的真正时间旅行调试，以及 LangSmith 可观测性层。LangGraph 完全与模型无关；从 GPT-4o 切换到 Claude 3.5 或 Gemini 1.5 Pro 不需要对图进行任何结构性更改。OpenAI Agents SDK 的交接模型更简单、实现速度更快，但 LangGraph 的图原语在具有许多条件路径的工作流中提供了对分支逻辑和错误恢复的更精确控制。这种权衡是真实存在的：LangGraph 的学习曲线明显更陡峭，团队普遍反映其文档对初学者不够友好。

Anthropic 的 Claude Agent SDK 位于竞争谱系的另一端。与 OpenAI Agents SDK 一样，它是一个由官方供应商维护的框架，围绕工具使用链和子智能体构建，并通过 MCP 服务器处理状态管理。其安全优先的设计将扩展思考直接嵌入到智能体循环中，并专门针对 Claude 模型进行了优化。这意味着锁定动态是对称的：OpenAI SDK 将您绑定到 OpenAI 的托管工具和 Responses API；而 Claude Agent SDK 将您绑定到 Anthropic 的模型家族。对于已经投入某个生态系统的团队来说，相应的 SDK 是自然的选择。对于需要在编排层保持供应商中立的团队来说，两者都不是完美的答案，此时 LangGraph 或 Agno 会变得更具吸引力。

与 CrewAI 相比，OpenAI Agents SDK 放弃了 CrewAI 基于角色的 DSL（该 DSL 可以在几乎不需要框架知识的情况下，用大约 20 行代码运行一个多智能体团队），换取了更底层、更显式的 API。CrewAI 具有内置的记忆模块；而 Agents SDK 则没有。然而，CrewAI 的人机协同仅在任务结束时触发，而 Agents SDK 支持工作流中途的审批网关。对于将其与 AutoGen 进行比较的团队来说，关键区别在于 AutoGen 以对话式智能体拓扑和灵活的智能体网络为中心，而 Agents SDK 对交接模型有强烈的倾向性，并期望您在其原语内工作，而不是组合您自己的原语。

“如果您的团队已经在使用 OpenAI，并且需要清晰的智能体间交接，那么 OpenAI Agents SDK 是最具倾向性的框架，这也是一种优势：决策更少，实现更快，而且追踪/护栏原语可以节省数周的自定义开发时间。” - mem0.ai 博客评论，2025 年 12 月

智能体循环的实际应用场景

标准工作流：定义智能体、分配工具、连接交接、添加护栏、运行。追踪是自动的。使用 Sandbox 原语的代码审查智能体接收拉取请求的差异（diff），启动容器，运行测试，应用补丁，并返回结构化输出。构建客户支持管道的开发者描述了一个路由智能体，它对用户意图进行分类，并将其交接给计费、技术或退货专家，每个专家都有自己的指令和工具，所有这些都可以在 OpenAI 仪表板的单一追踪中看到。这些不是理想化的用例，而是 SDK 团队记录的生产模式。

隐藏的成本模式是开发者在首次实际部署后反复指出的一个问题。智能体的每一轮交互都会将完整的对话上下文重新发送给模型。一个 5 步的工作流消耗的 Token 并不是单次调用的 5 倍；根据上下文长度，它可能会消耗 3-4 倍甚至更多。运行大量智能体工作流的团队需要提前对这种成本进行建模。估计每次审查成本为 $0.075-$0.14 的代码审查管道，在每天数千次审查的规模下，成本将变得不容忽视。

使用 RealtimeAgent 原语的语音智能体工作流运行在 gpt-realtime-1.5 上，具有自动打断检测、上下文管理和护栏功能。2025 年 6 月发布的 TypeScript SDK 包含了 RealtimeAgent 功能，开发者可以在客户端或服务器端部署语音智能体。在 2025 年 6 月的更新中，社区论坛上的开发者立即报告了音频质量下降、背景音频流中出现静电噪音以及函数调用延迟增加的问题，尽管这些问题与核心的交接和护栏功能无关。

“这是迄今为止最令人兴奋的更新！实时对话和人机协同功能彻底改变了局面。” - 开发者，OpenAI 社区论坛，2025 年 6 月 3 日

在各种评论中，记忆功能的缺失是一个共识。该 SDK 通过其会话管理干净利落地处理短期上下文，但持久化记忆、检索层和个性化需要外部基础设施。构建需要跨会话记住用户的智能体的团队，必须接入自己的向量存储，或者在 SDK 之外使用像 Letta 这样的工具进行记忆管理。这与其说是设计上的缺陷，不如说是刻意的范围选择：SDK 负责编排，而不是数据层。然而，这确实意味着对于有状态的应用程序来说，“快速投入生产”的说法需要打个星号。

OpenAI Agents SDK 为谁而建

该 SDK 是特定用户群体的理想起点：已经在使用 OpenAI 的 API、熟悉 Python，并且正在构建以清晰的智能体间委托为核心挑战的工作流的团队。客户支持自动化、多步研究管道、代码审查智能体和内容生成工作流都非常契合 SDK 的原语集。内置的追踪和护栏在这里提供了真正的价值：原本需要从头开始构建这些功能的团队可以节省大量的工程时间。

希望在生产环境中尝试语音智能体或 Realtime API 工作流的开发者，可以在 Agents SDK 中找到框架级别的归宿，目前没有任何其他主流框架能在官方支持层面上与之媲美。RealtimeAgent 原语结合 MCP 工具集成，为语音优先的智能体应用程序奠定了可靠的基础。

对于刚开始使用智能体框架且已经为 OpenAI API 访问付费的团队来说，这是一个低阻力的切入点。其快速入门指南确实非常精简。在各种评论中，其文档质量始终被评价为清晰且组织良好。该框架的强倾向性（通常被视为一种风险）对于那些不想在发布第一个智能体之前做出 15 个架构决策的团队来说，反而是一种优势。

对于那些在 DSPy 之上进行提示词优化，或在 LangChain 之上构建更广泛的思维链工具的开发者来说，Agents SDK 可以补充而不是取代这些工具。它不是一个全栈 AI 平台；它是一个编排层，假定您将对数据、记忆和模型评估层做出自己的选择。

OpenAI Agents SDK 不是什么

在托管工具层，它并非与模型无关。推理层可以指向任何兼容 Chat Completions 的端点，但一旦您使用 File Search、Vector Stores、Code Interpreter 或 Threads，您的数据就会驻留在 OpenAI 的平台中，且没有标准的导出路径。AgnoAGI 创始人 Ashpreet Bedi 指出，“Responses API 的设计初衷就是为了防止开发者通过更改 base_url 来切换供应商。”这是一个真实的架构限制，而不是假设的风险。

它不是一个基于图的工作流引擎。构建具有复杂条件循环、并行分支、任意点审批网关以及基于检查点重放的工作流的团队需要 LangGraph。Agents SDK 的交接模型是顺序且显式的。您可以使用 asyncio 构建并行执行，但没有针对它的框架级抽象，并且计划中的子智能体（subagents）功能也没有确认的发布日期。

目前，它还不是以 TypeScript 为主的团队的完整解决方案。Python 和 TypeScript SDK 是并行维护的，但 Python 版本始终率先获得主要功能。截至 2026 年 5 月，Sandbox 智能体、新的 harness 架构、代码模式和子智能体都仅限 Python 使用，TypeScript 的对齐被列为“计划在未来版本中发布”，没有具体的时间表。如今在 Agents SDK 上构建 TypeScript 优先的生产智能体管道意味着要接受功能滞后。

它不是一个记忆或检索框架。需要智能体记住用户、从知识库中检索或随着时间的推移个性化响应的团队，将需要构建或集成一个外部层。SDK 对您如何解决这个问题不持任何立场。