名称: openai-agents 描述: OpenAI Agents SDK for JavaScript/TypeScript（文本 + 语音代理）。用于多代理工作流、工具、护卫栏，或遇到Zod错误、MCP失败、无限循环、工具调用问题。

关键词: OpenAI Agents SDK, @openai/agents, @openai/agents-realtime, openai agents javascript, openai agents typescript, 文本代理, 语音代理, 实时代理, 多代理工作流, 代理交接, 代理工具, zod schemas agents, 结构化输出代理, 代理流式处理, 代理护卫栏, 输入护卫栏, 输出护卫栏, 人类在环, cloudflare workers agents, nextjs openai agents, react openai agents, hono agents, 代理调试, Zod schema type error, MCP tracing failure, agent infinite loop, tool call failures, schema mismatch agents 许可证: MIT 元数据: 包: - “@openai/agents@0.3.3” - “@openai/agents-realtime@0.3.3” - “zod@^3.24.1” 框架: [“Cloudflare Workers”, “Next.js”, “React”, “Node.js”, “Hono”] 最后验证: “2025-11-21” 生产测试: true 令牌节省: “~60%” 错误预防: 9

OpenAI Agents SDK 技能

使用OpenAI Agents SDK（JavaScript/TypeScript）构建AI应用程序的完整技能，涵盖文本代理、实时语音代理、多代理工作流和生产部署模式。

快速开始

安装

bun add @openai/agents zod@3
bun add @openai/agents-realtime  # 用于语音代理

设置环境变量：

export OPENAI_API_KEY="your-api-key"

基本文本代理

import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are helpful.',
  tools: [tool({
    name: 'get_weather',
    parameters: z.object({ city: z.string() }),
    execute: async ({ city }) => `Weather in ${city}: sunny`,
  })],
  model: 'gpt-4o-mini',
});

const result = await run(agent, 'What is the weather in SF?');

语音代理和多代理

// 语音代理
const voiceAgent = new RealtimeAgent({
  voice: 'alloy',
  model: 'gpt-4o-realtime-preview',
});

// 浏览器会话
const session = new RealtimeSession(voiceAgent, {
  apiKey: sessionApiKey, // 从后端获取！
  transport: 'webrtc',
});

// 多代理交接
const triageAgent = Agent.create({
  handoffs: [billingAgent, techAgent],
});

17个模板：templates/目录包含所有模式的生产就绪示例。

前3大关键错误

1. Zod模式类型错误

错误：工具参数的类型错误，即使结构兼容。

解决方法：内联定义模式。

// ❌ 可能导致类型错误
parameters: mySchema

// ✅ 可靠工作
parameters: z.object({ field: z.string() })

来源：GitHub #188

2. MCP追踪错误

错误：使用MCP服务器时出现“未找到现有追踪”。

解决方法：

import { initializeTracing } from '@openai/agents/tracing';
await initializeTracing();

来源：GitHub #580

3. MaxTurnsExceededError

错误：代理无限循环。

解决方案：增加maxTurns或改进指令：

const result = await run(agent, input, {
  maxTurns: 20,
});

// 或改进指令
instructions: `使用工具后，提供最终答案。
不要无休止地循环。`

所有9个错误：加载references/common-errors.md获取完整的错误目录和解决方法。

何时加载参考文件

在开发代理特定方面时加载参考文件：

代理模式（`references/agent-patterns.md`）

加载当：

设计多代理编排策略
选择基于LLM与基于代码的编排
实现并行代理执行
创建代理作为工具的模式
需要理解何时使用哪种编排模式

常见错误（`references/common-errors.md`）

加载当：

调试超出前3个错误的代理问题
实现全面的错误处理
遇到：GuardrailExecutionError, ToolCallError, 模式不匹配, Ollama集成, webSearchTool失败, Agent Builder导出错误
构建生产错误恢复模式

实时传输（`references/realtime-transports.md`）

加载当：

为语音代理选择WebRTC vs WebSocket
优化语音代理延迟
调试语音连接问题
理解语音的网络/防火墙要求
实现自定义音频源/汇

Cloudflare集成（`references/cloudflare-integration.md`）

加载当：

将代理部署到Cloudflare Workers
理解Workers限制（CPU, 内存, 无语音）
在Workers中实现流式处理
调试Workers特定问题
优化Workers性能和成本

官方链接（`references/official-links.md`）

加载当：

需要官方文档链接
寻找示例或社区资源
检查最新SDK版本
查找定价信息
需要迁移指南

核心概念总结

代理：配备指令和工具的LLM。

工具：具有Zod模式的函数，代理可以自动调用。

交接：多代理委托，代理将任务路由给专家。

护卫栏：输入/输出验证以确保安全（内容过滤, PII检测）。

结构化输出：使用Zod模式进行类型安全的响应。

流式处理：实时事件流式处理以逐步响应。

人类在环：需要特定工具执行的批准（requiresApproval: true）。

详细示例，请参见templates/text-agents/和templates/realtime-agents/中的模板。

文本代理快速参考

// 基本
const result = await run(agent, 'Your question');

// 流式处理
const stream = await run(agent, input, { stream: true });

// 结构化输出
const agent = new Agent({
  outputType: z.object({ sentiment: z.enum([...]), confidence: z.number() }),
});

模板：templates/text-agents/（8个模板）

实时语音代理快速参考

const voiceAgent = new RealtimeAgent({
  voice: 'alloy', // alloy, echo, fable, onyx, nova, shimmer
  model: 'gpt-4o-realtime-preview',
});

const session = new RealtimeSession(voiceAgent, {
  apiKey: sessionApiKey,
  transport: 'webrtc', // 或 'websocket'
});

语音交接约束：交接期间不能更改语音/模型。

模板：templates/realtime-agents/（3个模板） | 详情：references/realtime-transports.md

框架集成快速参考

Cloudflare Workers（实验性）

export default {
  async fetch(request: Request, env: Env) {
    const { message } = await request.json();
    process.env.OPENAI_API_KEY = env.OPENAI_API_KEY;

    const agent = new Agent({
      name: 'Assistant',
      instructions: 'Be helpful and concise',
      model: 'gpt-4o-mini',
    });

    const result = await run(agent, message, { maxTurns: 5 });

    return new Response(JSON.stringify({
      response: result.finalOutput,
      tokens: result.usage.totalTokens,
    }));
  },
};

限制：无实时语音, CPU时间限制（30秒最大）, 内存约束（128MB）。

模板：templates/cloudflare-workers/（2个模板）

详情：加载references/cloudflare-integration.md获取完整的Workers指南。

Next.js应用路由器

// app/api/agent/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { Agent, run } from '@openai/agents';

export async function POST(request: NextRequest) {
  const { message } = await request.json();
  const agent = new Agent({ /* ... */ });
  const result = await run(agent, message);
  return NextResponse.json({ response: result.finalOutput });
}

模板：templates/nextjs/（2个模板）

护卫栏和人类在环

// 输入/输出护卫栏
const agent = new Agent({
  inputGuardrails: [homeworkDetectorGuardrail],
  outputGuardrails: [piiFilterGuardrail],
});

// 人类批准
const tool = tool({
  requiresApproval: true,
  execute: async ({ amount }) => `Refunded $${amount}`,
});

// 处理批准循环
while (result.interruption?.type === 'tool_approval') {
  result = (await promptUser(result.interruption))
    ? await result.state.approve(result.interruption)
    : await result.state.reject(result.interruption);
}

模板：templates/text-agents/agent-guardrails-*.ts, agent-human-approval.ts

编排模式总结

基于LLM的：代理自主决定路由。用于自适应工作流。

基于代码的：显式控制流。用于可预测、确定性的工作流。

并行：并发运行多个代理。用于独立任务。

代理作为工具：将代理包装为工具以供管理器LLM使用。用于专家委托。

详情：加载references/agent-patterns.md获取带示例的全面编排策略。

模板：templates/text-agents/agent-parallel.ts

调试和追踪

process.env.DEBUG = '@openai/agents:*';

const result = await run(agent, input);
console.log('Tokens:', result.usage.totalTokens, 'Turns:', result.history.length);

模板：templates/shared/tracing-setup.ts

生产清单

[ ] 将OPENAI_API_KEY设置为环境密钥
[ ] 为所有代理调用实现错误处理
[ ] 为安全关键应用添加护卫栏
[ ] 设置合理的maxTurns以防止失控成本
[ ] 在可能的情况下使用gpt-4o-mini以提高成本效率
[ ] 实现速率限制
[ ] 记录令牌使用以监控成本
[ ] 全面测试交接流
[ ] 从不向浏览器暴露API密钥（使用会话令牌）
[ ] 启用追踪/可观察性以进行调试

何时使用此技能

✅ 使用当：

构建多代理工作流
创建语音AI应用
实现工具调用模式
需要输入/输出验证（护卫栏）
需要人类批准门控
编排复杂AI任务
部署到Cloudflare Workers或Next.js

❌ 不使用当：

简单OpenAI API调用（使用openai-api技能代替）
非OpenAI模型专用
大规模生产语音（考虑LiveKit代理）

令牌效率

估计节省：~60%

任务	无技能	有技能	节省
多代理设置	~12k 令牌	~5k 令牌	58%
语音代理	~10k 令牌	~4k 令牌	60%
错误调试	~8k 令牌	~3k 令牌	63%
平均	~10k	~4k	~60%

错误预防：9个记录的错误 = 100%错误预防

模板索引

文本代理（8）：

agent-basic.ts - 带工具的简单代理
agent-handoffs.ts - 多代理分类
agent-structured-output.ts - Zod模式
agent-streaming.ts - 实时事件
agent-guardrails-input.ts - 输入验证
agent-guardrails-output.ts - 输出过滤
agent-human-approval.ts - HITL模式
agent-parallel.ts - 并发执行

实时代理（3）： 9. realtime-agent-basic.ts - 语音设置 10. realtime-session-browser.tsx - React客户端 11. realtime-handoffs.ts - 语音委托

框架集成（4）： 12. worker-text-agent.ts - Cloudflare Workers 13. worker-agent-hono.ts - Hono框架 14. api-agent-route.ts - Next.js API 15. api-realtime-route.ts - Next.js语音

实用工具（2）： 16. error-handling.ts - 全面错误处理 17. tracing-setup.ts - 调试

参考

agent-patterns.md - 编排策略（LLM vs 代码, 并行, 代理作为工具）
common-errors.md - 所有9个错误带解决方法和来源
realtime-transports.md - WebRTC vs WebSocket比较, 延迟, 调试
cloudflare-integration.md - Workers设置, 限制, 性能, 成本
official-links.md - 文档, GitHub, npm, 社区资源

官方资源

文档: https://openai.github.io/openai-agents-js/
GitHub: https://github.com/openai/openai-agents-js
npm: https://www.npmjs.com/package/@openai/agents
问题: https://github.com/openai/openai-agents-js/issues

版本: SDK v0.3.3 最后验证: 2025-11-21 技能作者: Claude技能维护者 生产测试: 是

OpenAI Agents SDK 技能

快速开始

安装

基本文本代理

语音代理和多代理

前3大关键错误

1. Zod模式类型错误

2. MCP追踪错误

3. MaxTurnsExceededError

何时加载参考文件

代理模式（references/agent-patterns.md）

常见错误（references/common-errors.md）

实时传输（references/realtime-transports.md）

Cloudflare集成（references/cloudflare-integration.md）

官方链接（references/official-links.md）

核心概念总结

文本代理快速参考

实时语音代理快速参考

框架集成快速参考

Cloudflare Workers（实验性）

Next.js应用路由器

护卫栏和人类在环

编排模式总结

调试和追踪

生产清单

何时使用此技能

令牌效率

模板索引

参考

官方资源

代理模式（`references/agent-patterns.md`）

常见错误（`references/common-errors.md`）

实时传输（`references/realtime-transports.md`）

Cloudflare集成（`references/cloudflare-integration.md`）

官方链接（`references/official-links.md`）