openai-agents

用途

OpenAI Agents SDK 用于构建 AI 应用，涵盖文本智能体、实时语音智能体、多智能体工作流、工具调用、护栏以及人在回路（human-in-the-loop）模式。该技能适合使用 JavaScript/TypeScript 的开发者，帮助快速搭建并避免常见错误。

主要能力

智能体（Agents）：由指令与工具组成的 LLM。示例：const agent = new Agent({ name: 'Assistant', tools: [myTool], model: 'gpt-5-mini' });
工具（Tools）：使用 Zod 模式定义的函数。示例：const weatherTool = tool({ name: 'get_weather', parameters: z.object({ city: z.string() }), execute: async ({ city }) => \Weather in ${city}: sunny` });`
交接（Handoffs）：多智能体委派。示例：const triageAgent = Agent.create({ handoffs: [specialist1, specialist2] });
护栏（Guardrails）：输入/输出校验。示例：const agent = new Agent({ inputGuardrails: [detector], outputGuardrails: [filter] });
结构化输出：类型安全响应。示例：const agent = new Agent({ outputType: z.object({ sentiment: z.enum(['positive', 'negative']) }) });
文本智能体：基础调用 const result = await run(agent, 'What is 2+2?')；流式输出通过 run(agent, 'Tell me a story', { stream: true }) 并遍历事件。
多智能体交接：可定义 billingAgent、techAgent 与 triageAgent，通过 handoffDescription 描述职责。
Agent-as-Tool 上下文隔离：使用 agent.asTool() 时，子智能体不共享父对话历史（有意设计以简化调试）。可通过工具参数传递上下文。
护栏：输入护栏在處理前校验，输出护栏过滤响应（PII 检测、内容安全）。
人在回路：工具可设置 requiresApproval: true，通过 result.interruption?.type === 'tool_approval' 循环处理批准或拒绝。流式 HITL 需显式检查中断。
实时语音智能体：使用 RealtimeAgent 与 RealtimeSession，支持 voice（alloy、echo、fable、onyx、nova、shimmer）与模型 gpt-5-realtime，传输方式支持 webrtc。注意：切勿将 OPENAI_API_KEY 发送到浏览器，应在服务端生成临时会话令牌。语音交接时 voice/model 必须一致。
框架集成：Cloudflare Workers（实验性）、Next.js。Cloudflare Workers 限制：无语音智能体、30 秒 CPU 限制、128MB 内存、追踪需手动设置（设置 OTEL_SDK_DISABLED=true 或调用 startTracingExportLoop()）。

使用方式

快速开始：

npm install @openai/agents zod@4  # v0.4.0+ 需要 Zod 4（破坏性变更）
npm install @openai/agents-realtime  # 语音智能体
export OPENAI_API_KEY="your-key"

破坏性变更（v0.4.0）：不再支持 Zod 3，需升级到 zod@4。

运行时：Node.js 22+、Deno、Bun、Cloudflare Workers（实验性）。

适用场景

构建文本对话智能体与多智能体协作流程
需要工具调用、结构化输出与类型校验的应用
需要输入/输出安全护栏与人在回路审批的场景
实时语音交互应用（浏览器端需使用临时令牌）
在 Cloudflare Workers 或 Next.js 中集成智能体

限制

实时视频流不支持：尽管有摄像头示例，实时视频流并非原生支持，模型可能不会主动基于视频事件说话。
Cloudflare Workers 不支持语音智能体，且有 30 秒 CPU 限制与 128MB 内存限制。
不适用于：简单 OpenAI API 调用（应使用 openai-api 技能）、仅使用非 OpenAI 模型、大规模生产语音（可考虑 LiveKit Agents）。

错误处理（预防 11+ 错误）

Zod 模式类型错误：工具参数类型错误时，建议内联定义模式。v0.4.1 起工具调用参数中的无效 JSON 已能优雅处理。
MCP 追踪错误：出现 "No existing trace found" 时，调用 initializeTracing()。
MaxTurnsExceededError：智能体无限循环时，增加 maxTurns 或改进指令。
ToolCallError：工具执行失败时，使用指数退避重试。
模式不匹配：输出不符合 outputType 时，使用更强模型或添加校验指令。
推理努力默认值变更（v0.4.0）：gpt-5.1/5.2 默认推理努力从 "low" 改为 "none"，如需请显式设置。
推理内容泄漏到 JSON 输出：response_reasoning 字段意外出现时，从输出中过滤。

编排模式

基于 LLM：智能体自主决定路由（自适应，令牌消耗更高）
基于代码：显式控制流与条件判断（可预测，成本更低）
并行：Promise.all([run(agent1, text), run(agent2, text)])

调试

设置 process.env.DEBUG = '@openai/agents:*'; 启用详细日志，并检查 result.usage.totalTokens、result.history.length、result.currentAgent?.name。

生产检查清单

将 OPENAI_API_KEY 设为环境密钥
为所有智能体调用实现错误处理
为安全关键应用添加护栏
启用追踪以便调试
设置合理的 maxTurns 防止成本失控
尽可能使用 gpt-5-mini 以节省成本
实现速率限制
记录令牌使用量以监控成本
彻底测试交接流程
切勿将 API 密钥暴露给浏览器（使用会话令牌）

令牌效率

预计节省约 60%：多智能体设置从约 12k 降至约 5k（58%），语音智能体从约 10k 降至约 4k（60%），错误调试从约 8k 降至约 3k（63%）。已记录 11 个问题，实现 100% 错误预防。

模板索引

文本智能体（8 个）：agent-basic.ts、agent-handoffs.ts、agent-structured-output.ts、agent-streaming.ts、agent-guardrails-input.ts、agent-guardrails-output.ts、agent-human-approval.ts、agent-parallel.ts。

实时智能体（3 个）：realtime-agent-basic.ts、realtime-session-browser.tsx、realtime-handoffs.ts。

框架集成（4 个）：worker-text-agent.ts、worker-agent-hono.ts、api-agent-route.ts、api-realtime-route.ts。

工具（2 个）：error-handling.ts、tracing-setup.ts。

参考文档

agent-patterns.md、common-errors.md、realtime-transports.md、cloudflare-integration.md、official-links.md。

官方资源

文档：https://openai.github.io/openai-agents-js/ GitHub：https://github.com/openai/openai-agents-js npm：https://www.npmjs.com/package/@openai/agents Issues：https://github.com/openai/openai-agents-js/issues 版本：SDK v0.4.1，最后验证：2026-01-21。