openai-agents-js

当 AI 开始"组队开会"：OpenAI Agents SDK 如何让多个智能体协同工作

想象一下这样一个场景：用户发来一条复杂的需求——"帮我分析这家公司最近的融资情况，包括新闻、竞品对比，以及给出一个投资建议"。传统的 AI 助手会直接给你一段话，但有了 OpenAI Agents SDK，这件事变成了一个微型"AI 团队会议"：一个 Agent 负责查新闻，一个负责竞品调研，一个负责综合分析，最终由"主持人" Agent 汇总输出给用户。

这就是 OpenAI Agents SDK 正在做的事——让多个 AI Agent 像真实团队一样分工协作。

图1：OpenAI Agents SDK 的追踪与编排界面，展示多 Agent 协同的工作流

从"单打独斗"到"团队协作"的范式转变

2024 年 10 月，OpenAI 开源了 Python 版的 Swarm 框架，在开发者社区引发了关于"多 Agent 协作"的广泛讨论。Swarm 演示了 Agent 之间的 Handoff（交接）机制如何实现，但彼时的 Swarm 定位是"教学演示"，并非生产级工具。

2025 年，OpenAI 将这个思路产品化，正式推出 Agents SDK。与 Swarm 不同，Agents SDK 是真正为生产环境设计的多 Agent 框架——它在保持轻量级（整个核心包仅约 300KB）的同时，提供了完整的工具系统、状态管理、追踪调试和安全护栏。

技术架构：像一个精密的交响乐团

OpenAI Agents SDK 的架构设计非常清晰。核心是 Agent（智能体）模型，每个 Agent 包含四大要素：Instructions（系统指令）、Tools（工具能力）、Guardrails（输入输出护栏）和 Handoffs（Agent 间交接）。

整个 SDK 是一个 monorepo 结构，包含 5 个子包：

• @openai/agents-core：核心框架，包含 Agent 模型、Runner、Sessions
• @openai/agents-openai：OpenAI 模型适配层，支持 GPT-4o、o1、o3 等
• @openai/agents-realtime：实时语音 Agent 支持，基于 WebSocket
• @openai/agents-extensions：扩展包，支持 MCP 协议、E2B 代码执行沙箱等
• @openai/agents：统一入口包，组合上述所有模块

开发者在使用时只需要安装 @openai/agents 这一个包，SDK 会自动引入所有依赖。

Sandbox Agent 是这个框架最具特色的功能之一。传统的 AI Agent 只能调用函数，而 Sandbox Agent 内置了完整的文件系统和工作区——它可以读取代码文件、运行 shell 命令、应用补丁（patch），甚至在不同任务之间保持工作区状态。这对于"帮我重构这个项目"这类需要文件操作的任务来说，是质的飞跃。

核心功能：从"能用"到"好用"

多 Agent 协作是整个框架的灵魂。通过 Handoff 机制，一个 Agent 可以将任务委托给另一个更专业的 Agent，同时保留完整的上下文信息。例如，一个"主客服 Agent"收到用户的技术问题时，可以立即 Handoff 给"技术支持 Agent"，后者拥有更专业的工具和指令集。

Tools 系统也值得关注。SDK 不仅支持传统的 Function Calling（函数工具），还支持 MCP（Model Context Protocol）协议——这意味着可以连接外部工具服务器，如文件系统、数据库、API。同时，Agent 本身也可以作为工具被其他 Agent 调用，形成了"用 Agent 打造工具，再用工具赋能 Agent"的递归结构。

**Guardrails（护栏）**提供了一层安全验证。可以在输入进入 Agent 之前和输出返回用户之前插入自定义检查逻辑，防止有害内容或格式错误。这在面向用户的场景中尤为重要。

**Tracing（追踪）**是开发体验的亮点。SDK 内置了完整的工作流追踪能力，每次 Agent 交互都会记录完整的调用链、工具使用、Token 消耗等信息，配合 OpenAI 的追踪界面，可以像调试传统程序一样调试 Agent 工作流。

上手体验：门槛很低，但上限很高

对于普通开发者，OpenAI Agents SDK 的入门门槛出奇的低。只需要 Node.js 22+ 和一行命令：

npm install @openai/agents zod

然后就可以编写第一个 Agent 了：

import { run, agent } from '@openai/agents';

const myAgent = agent({
  model: 'gpt-4o',
  instructions: '你是一个有帮助的助手',
});

const result = await run(myAgent, '你好，介绍一下你自己');
console.log(result.finalOutput);

但如果深入挖掘，框架提供了足够的扩展空间。MCP 协议支持让 Agent 可以连接几乎任何外部系统；Sandbox Agent 支持自定义镜像和启动参数；Tracing API 可以对接自定义的监控后端。这使得框架既适合快速原型验证，也能支撑复杂的企业级应用。

多运行时支持是另一个亮点。除了 Node.js，SDK 还支持 Deno、Bun，甚至实验性地支持 Cloudflare Workers。这种灵活性在同类型框架中较为少见。

局限与争议

需要指出的是，作为一个相对年轻的项目，OpenAI Agents SDK 仍在快速迭代中。以下几点值得注意：

对 OpenAI API 的强依赖。尽管文档声称"provider-agnostic"（模型无关），但核心功能（如 Tracing、Realtime Agent）深度依赖 OpenAI 的服务端能力。如果你想用本地模型或其他云服务商的能力，框架的支持并不完整。

生产就绪的疑虑。项目虽然提供了完整的文档和示例，但缺少企业级特性，如限流、熔断、持久化状态存储、多租户隔离等。对于大规模部署，开发者可能需要在 SDK 之上做大量额外工作。

Node.js 版本要求较高。明确要求 Node.js 22+，这对于一些仍在使用 Node.js 18/20 的团队来说可能是个障碍。

行业意义：轻量级 Agent 框架的标杆

OpenAI Agents SDK 的出现，代表了 AI Agent 框架的一种新思路——不做大而全的"AI 操作系统"，而是提供足够好用但不过度设计的基础设施。

从数据来看，这个策略是成功的：GitHub 上超过 3100 颗星、796 个 Fork、每月数十次提交，吸引了大量开发者参与生态建设。社区中涌现了各种垂直领域的使用案例，从金融研究 Agent 到客服系统，从代码审查工具到语音助手。

更重要的是，OpenAI 明确表示将 Agents SDK 定位为开源框架，鼓励社区在其基础上扩展。这种开放态度，与 OpenAI 过去相对封闭的形象形成了有趣的对比，也为整个 AI Agent 开源生态注入了新的活力。

如果你正在构建需要多个 AI 模块协同工作的应用，OpenAI Agents SDK 值得认真评估——它的学习曲线平缓、功能完整、社区活跃，是目前 TypeScript/JavaScript 生态中最接近生产可用的多 Agent 框架之一。