openai-agents

OpenAI Agents SDK 技能

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

---

快速入门

安装

bun add @openai/agents zod@3
bun add @openai/agents-realtime  # For voice agents

设置环境变量：

export OPENAI_API_KEY="your-api-key"

基础文本 Agent

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?');

语音 Agent 与多 Agent

// Voice agent
const voiceAgent = new RealtimeAgent({
  voice: 'alloy',
  model: 'gpt-4o-realtime-preview',
});

// Browser session
const session = new RealtimeSession(voiceAgent, {
  apiKey: sessionApiKey, // From backend!
  transport: 'webrtc',
});

// Multi-agent handoffs
const triageAgent = Agent.create({
  handoffs: [billingAgent, techAgent],
});

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

---

最重要的 3 个错误

1. Zod 架构类型错误

错误：即使结构兼容，工具参数也会出现类型错误。

解决方法：在行内定义架构。

// ❌ Can cause type errors
parameters: mySchema

// ✅ Works reliably
parameters: z.object({ field: z.string() })

来源：GitHub #188

2. MCP 跟踪错误

错误：使用 MCP 服务时出现“No existing trace found”。

解决方法：

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

来源：GitHub #580

3. MaxTurnsExceededError

错误：Agent 无限循环。

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

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

// Or improve instructions
instructions: `After using tools, provide a final answer.
Do not loop endlessly.`

全部 9 个错误：加载 references/common-errors.md，查看包含解决方法的完整错误目录。

---

何时加载参考资料

在处理 Agent 开发的特定方面时，加载相应的参考文件：

Agent 模式（references/agent-patterns.md）

在以下情况下加载：

• 设计多 Agent 编排策略
• 在基于 LLM 和基于代码的编排之间进行选择
• 实现并行 Agent 执行
• 创建 Agent 作为工具的模式
• 需要了解何时使用哪种编排模式

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

在以下情况下加载：

• 调试上述最重要的 3 个错误之外的 Agent 问题
• 实现全面的错误处理
• 遇到：GuardrailExecutionError、ToolCallError、架构不匹配、Ollama 集成、webSearchTool 故障、Agent Builder 导出错误
• 构建生产环境错误恢复模式

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

在以下情况下加载：

• 为语音 Agent 选择 WebRTC 或 WebSocket
• 优化语音 Agent 延迟
• 调试语音连接问题
• 了解语音功能的网络／防火墙要求
• 实现自定义音频源／接收器

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

在以下情况下加载：

• 将 Agent 部署到 Cloudflare Workers
• 了解 Workers 的限制（CPU、内存、不支持语音）
• 在 Workers 中实现流式传输
• 调试 Workers 特有问题
• 优化 Workers 的性能和成本

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

在以下情况下加载：

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

---

核心概念摘要

Agent：配备指令和工具的大模型。

工具：带有 Zod 架构、可由 Agent 自动调用的函数。

交接：多 Agent 委派，由 Agent 将任务分配给专业 Agent。

防护措施：用于安全防护的输入／输出验证（内容过滤、PII 检测）。

结构化输出：使用 Zod 架构生成类型安全的响应。

流式传输：用于渐进式响应的实时事件流。

人在回路中：要求特定工具执行经过批准（requiresApproval: true）。

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

---

文本 Agent 快速参考

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

// Streaming
const stream = await run(agent, input, { stream: true });

// Structured output
const agent = new Agent({
  outputType: z.object({ sentiment: z.enum([...]), confidence: z.number() }),
});

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

---

实时语音 Agent 快速参考

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', // or '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 Router

// 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 个模板）

---

防护措施与人工介入

// Input/output guardrails
const agent = new Agent({
  inputGuardrails: [homeworkDetectorGuardrail],
  outputGuardrails: [piiFilterGuardrail],
});

// Human approval
const tool = tool({
  requiresApproval: true,
  execute: async ({ amount }) => `Refunded $${amount}`,
});

// Handle approval loop
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：由 Agent 自主决定路由。适用于自适应工作流。

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

并行：同时运行多个 Agent。适用于相互独立的任务。

将 Agent 用作工具：将 Agent 封装为工具，供管理器 LLM 使用。适用于委派给专用 Agent。

详情：加载 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 设置为环境密钥
• 为所有 Agent 调用实现错误处理
• 为安全关键型应用添加防护措施
• 设置合理的 maxTurns，防止成本失控
• 尽可能使用 gpt-4o-mini，以提高成本效益
• 实现速率限制
• 记录令牌用量以监控成本
• 全面测试交接流程
• 切勿向浏览器暴露 API 密钥（使用会话令牌）
• 启用追踪／可观测性以便调试

---

何时使用此技能

✅ 适用场景：

• 构建多 Agent 工作流
• 创建语音 AI 应用
• 实现工具调用模式
• 需要输入／输出验证（防护措施）
• 需要人工审批关卡
• 编排复杂 AI 任务
• 部署到 Cloudflare Workers 或 Next.js

❌ 不适用场景：

• 简单的 OpenAI API 调用（请改用 openai-api 技能）
• 仅使用非 OpenAI 模型
• 大规模生产级语音服务（可考虑 LiveKit Agents）

---

令牌效率

预计节省：约 60%

任务	不使用技能	使用技能	节省
多 Agent 配置	~12k 个令牌	~5k 个令牌	58%
语音 Agent	~10k 个令牌	~4k 个令牌	60%
错误调试	~8k 个令牌	~3k 个令牌	63%
平均值	~10k 个令牌	~4k 个令牌	~60%

避免的错误：已记录的 9 个问题 = 100% 错误预防

---

模板索引

文本 Agent（8 个）：

1. agent-basic.ts - 使用工具的简单 Agent
2. agent-handoffs.ts - 多 Agent 分诊
3. agent-structured-output.ts - Zod 模式
4. agent-streaming.ts - 实时事件
5. agent-guardrails-input.ts - 输入验证
6. agent-guardrails-output.ts - 输出过滤
7. agent-human-approval.ts - HITL 模式
8. agent-parallel.ts - 并发执行

实时 Agent（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 - 调试

---

参考资料

1. agent-patterns.md - 编排策略（基于 LLM 与基于代码、并行、将 Agent 用作工具）
2. common-errors.md - 全部 9 个错误及其解决方法和来源
3. realtime-transports.md - WebRTC 与 WebSocket 对比、延迟、调试
4. cloudflare-integration.md - Workers 配置、限制、性能、成本
5. official-links.md - 文档、GitHub、npm、社区资源

---

Official Resources

• Docs: 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

---

Version: SDK v0.3.3 Last Verified: 2025-11-21 Skill Author: Claude Skills Maintainers Production Tested: Yes