OpenAI Agents SDK实战：构建多智能体协作系统的核心概念与最佳实践

1. 从零到一理解 OpenAI Agents SDK 的核心价值如果你正在用 JavaScript 或 TypeScript 捣鼓 AI 应用尤其是想让多个 AI 智能体Agent协同工作那么 OpenAI 官方推出的这个 Agents SDK 绝对值得你花时间研究。它不是又一个臃肿的“全家桶”框架而是一个设计精巧、理念现代的“工具箱”。我花了几周时间用它重构了一个内部的知识库问答系统感触最深的就是它的“轻量”与“强大”并不矛盾。轻量在于它的 API 设计非常直观上手门槛低强大在于它内置了多智能体协作、工具调用、会话管理、实时语音等生产级应用所需的核心能力而且最关键的是它不绑定 OpenAI 一家设计上是 provider-agnostic供应商无关的。简单来说这个 SDK 帮你解决了构建复杂 AI 工作流时最头疼的几个问题如何让不同的 AI 角色比如一个负责检索一个负责总结一个负责格式化高效地接力完成任务如何安全、可控地让 AI 使用外部工具比如查数据库、发邮件如何在整个对话过程中保持上下文连贯以及如何清晰地追踪和调试这一系列复杂的 AI 调用链它把这些能力封装成了清晰的抽象概念比如Agent、Tool、Handoff、Session让你可以像搭积木一样构建应用而不是从零开始处理各种异步调用、错误处理和状态管理。2. 核心概念深度拆解不只是 API更是设计范式官方文档列出了八个核心概念但在我看来它们可以归纳为四个层次智能体层、协作层、控制层和运维层。理解这个层次能帮你更好地设计自己的应用架构。2.1 智能体层你的 AI 员工Agent是这个 SDK 的基石。你可以把它理解为一个配备了特定技能包和岗位说明的 AI 员工。创建一个 Agent 不仅仅是设置一个 LLM 模型更是定义它的角色、能力和行为边界。import { Agent } from openai/agents; const researchAgent new Agent({ name: 研究员, instructions: 你是一名严谨的行业研究员。你的任务是针对用户提出的问题从提供的资料或已知信息中找出相关、准确的事实和数据。回答时请引用来源并区分事实与观点。如果信息不足请明确说明。, model: gpt-4o, // 可以指定模型 temperature: 0.1, // 低随机性确保回答稳定 });这里有几个关键点instructions这是 Agent 的“灵魂”。写得好坏直接决定 Agent 的表现。我的经验是指令要具体、可操作并包含负面示例比如“不要凭空捏造信息”。model虽然 SDK 支持多供应商但当前与 OpenAI API 集成最紧密。你可以为不同复杂度的任务选择不同模型以平衡成本与效果。配置继承你可以创建一个基础 Agent 模板然后通过扩展来创建特定角色的 Agent这能极大提升代码复用率。2.2 协作层让 AI 团队高效运转单个 Agent 能力有限真正的威力在于让多个 Agent 协作。SDK 提供了两种核心协作机制Agents as Tools和Handoffs。Agents as Tools是把一个 Agent 包装成另一个 Agent 可调用的工具。这适合主从式、任务分解的场景。比如一个“客服主管”Agent 接到用户关于订单和产品的混合问题它可以调用“订单查询”Agent 工具和“产品咨询”Agent 工具来分别获取信息再综合回答。Handoffs则更像是工作流的“交接棒”。一个 Agent 在处理到某个阶段后可以主动将整个对话上下文Session移交给另一个更专业的 Agent。这与工具调用的区别在于控制权完全转移了后续的对话将由新的 Agent 主导。这非常适合线性管道式的工作流。例如一个“需求分析”Agent 完成分析后将任务 Handoff 给“方案设计”Agent后者再 Handoff 给“代码生成”Agent。// 伪代码示例Handoff 流程 const analyst new Agent({...}); // 需求分析师 const designer new Agent({...}); // 方案设计师 // 当 analyst 判断需求已清晰可以执行 await handoff(designer, sessionId); // 此后用户接下来的对话将直接由 designer 这个 Agent 来处理。选择哪种协作模式取决于你的业务逻辑是“并行分解”还是“串行接力”。2.3 控制层给 AI 系上“安全带”让 AI 自由行动的前提是确保安全可控。SDK 的Guardrails和Human-in-the-loop就是为此而生。Guardrails我习惯叫它“护栏”。它可以在 Agent 的输入前pre-processing和输出后post-processing插入验证逻辑。这不仅仅是内容过滤更是业务规则的强制实施。import { Guardrail } from openai/agents; import { z } from zod; // 1. 输入护栏验证用户输入是否符合预期格式 const inputSchema z.object({ topic: z.string().min(1).max(100), depth: z.enum([brief, detailed]).default(brief), }); const inputGuardrail new Guardrail({ name: 验证查询主题, validateInput: async (input) { const parsed inputSchema.safeParse(JSON.parse(input)); if (!parsed.success) { return { valid: false, message: 请输入有效的主题和深度。错误${parsed.error.message} }; } return { valid: true, transformedInput: JSON.stringify(parsed.data) }; }, }); // 2. 输出护栏检查输出是否包含敏感信息或未声明来源 const outputGuardrail new Guardrail({ name: 检查信息溯源, validateOutput: async (output) { if (output.includes(据内部消息) !output.includes(来源)) { return { valid: false, message: 请为引用的内部消息注明具体来源。 }; } return { valid: true }; }, }); // 将护栏附加到 Agent const safeAgent new Agent({ ...agentConfig, guardrails: [inputGuardrail, outputGuardrail], });Human-in-the-loop机制则是在关键决策点暂停自动化流程等待人工审核或输入。这在对准确性、安全性要求极高的场景如医疗建议、法律文书、大额交易审批中不可或缺。SDK 提供了标准化的接口来挂起任务并等待外部系统如你的后台管理界面提供人工反馈后再继续。2.4 运维层洞察与持久化Sessions和Tracing是保障应用可维护、可调试的基石。Sessions自动管理对话历史。你不需要自己维护一个不断增长的messages数组。SDK 会为每一次run或连续的交互关联一个 Session自动保存上下文。这意味着你可以轻松实现“继续上次对话”的功能也方便后续对历史对话进行分析。Tracing是开发调试的神器。它记录了每一次 Agent 调用、工具执行、Handoff 发生的详细日志包括输入、输出、耗时、token 用量等。通过内置的 UI 或集成到如 LangSmith 等平台你可以可视化整个工作流的执行轨迹快速定位是哪个 Agent 的指令不清还是哪个工具调用超时。这对于优化复杂工作流的性能和成本至关重要。3. 实战构建一个多智能体内容创作系统理论说再多不如动手。我们一起来构建一个简化但完整的多智能体系统一个自动化的技术博客大纲生成器。它包含三个 Agent选题分析员分析用户输入的模糊选题提炼出核心关键词和角度。大纲生成员根据明确的关键词生成详细的博客大纲。风格审核员检查大纲的结构、可读性并给出修改建议。3.1 环境准备与项目初始化首先确保你的环境符合要求。我推荐使用 Node.js 22 和 pnpm但 npm 或 yarn 也可以。# 创建项目目录并初始化 mkdir multi-agent-blog-planner cd multi-agent-blog-planner pnpm init -y # 安装核心依赖 pnpm add openai/agents zod # 安装 TypeScript 及相关类型如果使用 TS pnpm add -D typescript types/node npx tsc --init # 创建 .env 文件设置你的 OpenAI API Key echo OPENAI_API_KEYsk-your-key-here .env注意务必在.env文件中配置OPENAI_API_KEY并将.env添加到.gitignore中避免密钥泄露。在代码中通过process.env.OPENAI_API_KEY读取。3.2 定义智能体与工具我们创建三个 Agent并将前两个 Agent 定义为第三个 Agent 可用的工具。// src/agents.ts import { Agent, Tool } from openai/agents; import { z } from zod; // 1. 选题分析员 Agent export const topicAnalyzerAgent new Agent({ name: TopicAnalyzer, instructions: 你是一名技术博客选题专家。用户会提出一个宽泛或模糊的技术话题。你的任务是 1. 解析话题的核心领域如前端框架、数据库、 DevOps。 2. 提炼出3-5个最相关、最具讨论价值的具体关键词。 3. 建议一个独特的写作角度例如入门指南、深度原理剖析、性能对比、最佳实践。 请以 JSON 格式输出包含 fields: { coreDomain: string, keywords: string[], suggestedAngle: string }。, model: gpt-4o-mini, // 使用轻量模型进行初步分析 }); // 将分析员包装成一个 Tool export const topicAnalysisTool new Tool({ name: analyze_blog_topic, description: 分析一个宽泛的技术话题提炼核心领域、关键词和写作角度。, inputSchema: z.object({ rawTopic: z.string() }), call: async ({ rawTopic }) { const result await topicAnalyzerAgent.run(分析以下话题${rawTopic}); // 这里可以加入对 result 的解析和错误处理 return result.finalOutput; }, }); // 2. 大纲生成员 Agent export const outlineGeneratorAgent new Agent({ name: OutlineGenerator, instructions: 你是一名资深技术作家。根据提供的具体关键词和写作角度生成一篇结构完整、层次分明的技术博客大纲。 大纲必须包含 - 标题吸引人且包含核心关键词 - 前言痛点引入、文章价值 - 至少3个主要章节每个章节下包含2-4个子要点 - 总结与展望 请使用 Markdown 格式输出确保逻辑连贯子要点内容具体。, model: gpt-4o, // 使用能力更强的模型进行创造性工作 }); // 将生成员包装成一个 Tool export const outlineGenerationTool new Tool({ name: generate_blog_outline, description: 根据具体关键词和角度生成详细的 Markdown 格式博客大纲。, inputSchema: z.object({ keywords: z.array(z.string()), angle: z.string(), }), call: async ({ keywords, angle }) { const prompt 关键词${keywords.join(, )}\n写作角度${angle}\n请生成博客大纲。; const result await outlineGeneratorAgent.run(prompt); return result.finalOutput; }, }); // 3. 风格审核员 Agent (主协调员) export const styleReviewerAgent new Agent({ name: StyleReviewer, instructions: 你是内容主编负责协调和审核博客大纲的生成流程。 你的工作流程是 1. 首先使用 analyze_blog_topic 工具对用户输入的原始话题进行分析得到结构化数据。 2. 然后使用 generate_blog_outline 工具将上一步得到的关键词和角度输入生成初步大纲。 3. 最后审核生成的大纲。检查其结构是否合理前言-主体-结论、技术深度是否适中、可读性如何。给出1-2条具体的修改建议。 请最终输出一个包含以下部分的完整报告 - 原始话题 - 分析结果领域、关键词、角度 - 生成的大纲 - 你的审核建议, model: gpt-4o, tools: [topicAnalysisTool, outlineGenerationTool], // 装配工具 });3.3 运行工作流并查看追踪现在我们可以运行这个多智能体工作流了。为了获得更好的调试体验我们启用 Tracing。// src/index.ts import { run } from openai/agents; import { styleReviewerAgent } from ./agents; async function main() { const userInput 如何学习 TypeScript; console.log(用户输入: ${userInput}\n); console.log(开始多智能体协作流程...\n---); const result await run( styleReviewerAgent, // 启动主协调员 userInput, { // 启用追踪可以在控制台看到链接 tracing: { enabled: true, }, // 可以设置一个固定的 sessionId 来关联多次对话 // sessionId: some-unique-id, } ); console.log(---\n流程结束); console.log(\n最终输出\n); console.log(result.finalOutput); // 追踪 UI 的链接会在控制台输出类似 // Tracing enabled: https://trace.openai.com/session/xxx // 点击链接即可查看详细的执行流程图和每一步的输入输出。 } main().catch(console.error);运行ts-node src/index.ts或配置好后的npm start你会看到控制台输出完整的报告并得到一个追踪链接。点击链接你能清晰地看到StyleReviewerAgent 是如何先调用analyze_blog_topic工具等待其返回结果后再调用generate_blog_outline工具最后进行综合审核的。这个可视化视图对于理解工作流和排查问题比如某个工具调用失败有巨大帮助。3.4 添加护栏与人工干预点让我们增强系统的稳健性。为StyleReviewerAgent添加一个输出护栏确保最终报告不包含任何占位符或未完成标记。同时模拟一个“人工审批”环节。// src/guardrails.ts import { Guardrail } from openai/agents; export const finalOutputGuardrail new Guardrail({ name: 检查报告完整性, validateOutput: async (output) { const invalidMarkers [TODO, FIXME, 待补充, ...]; for (const marker of invalidMarkers) { if (output.includes(marker)) { return { valid: false, message: 报告内容不完整包含占位符“${marker}”。请主编完成内容填充。, }; } } // 检查是否包含所有要求的章节 const requiredSections [原始话题, 分析结果, 生成的大纲, 审核建议]; const missingSections requiredSections.filter(section !output.includes(section)); if (missingSections.length 0) { return { valid: false, message: 报告缺少必要章节${missingSections.join(, )}。请确保报告结构完整。, }; } return { valid: true }; }, }); // 在创建 styleReviewerAgent 时附加护栏 export const styleReviewerAgent new Agent({ ...styleReviewerConfig, guardrails: [finalOutputGuardrail], });对于人工干预SDK 提供了requestHumanInput函数。我们可以在审核建议环节后插入一个暂停点。// 在 StyleReviewerAgent 的 instructions 中修改最后一步 // “3. 最后审核生成的大纲...给出1-2条具体的修改建议。” // 改为 // “3. 最后审核生成的大纲...给出1-2条具体的修改建议。 // 4. 在输出最终报告前必须调用 request_human_review 工具等待主编确认。” // 然后定义这个工具 import { requestHumanInput } from openai/agents; const humanReviewTool new Tool({ name: request_human_review, description: 将当前草稿发送给人类主编进行最终审批。, inputSchema: z.object({ draftReport: z.string() }), call: async ({ draftReport }) { // 在实际应用中这里应该触发一个通知到你的后台系统或聊天界面 console.log(\n 需要人工审批 ); console.log(草稿内容预览\n${draftReport.substring(0, 500)}...\n); console.log(请人类主编在控制台输入“approve”或“reject”); // 模拟等待人工输入生产环境可能是从数据库或消息队列读取 const readline require(readline).createInterface({ input: process.stdin, output: process.stdout, }); const response: string await new Promise((resolve) { readline.question(审批意见 , (answer) { readline.close(); resolve(answer.trim().toLowerCase()); }); }); if (response approve) { return { status: approved, message: 主编已批准发布。 }; } else { return { status: rejected, message: 主编已驳回请根据反馈修改。 }; } }, }); // 将这个工具也加入到 styleReviewerAgent 的 tools 数组中。4. 进阶技巧与避坑指南在实际项目中踩过一些坑后我总结出以下经验能帮你节省大量调试时间。4.1 智能体指令设计的艺术指令是控制 Agent 行为最有效的手段但写得好不容易。具体化避免模糊不要说“好好回答”要说“回答需分点论述每点以‘-’开头并提供一个简短的代码示例”。定义输出格式明确要求 JSON、Markdown、YAML 等格式这能极大简化后续的数据处理。示例中我们要求了 JSON 输出。包含负面约束“不要假设用户有 XX 知识”、“不要在回答中包含个人意见”、“不要使用未在上下文中出现的信息”。角色扮演给 Agent 一个具体的角色“资深 DevOps 工程师”、“新手友好的产品经理”这能自动赋予其特定的知识背景和表达风格。4.2 会话管理与上下文长度Session自动管理历史但要注意 LLM 的上下文窗口限制。选择性记忆对于超长对话不要无脑将全部历史塞进去。可以考虑在run时通过session参数传入一个经过摘要的、更早的历史版本。关键信息注入对于必须在整个会话中记住的信息如用户偏好、项目 ID可以在每次run时将其作为系统指令的一部分附加到用户消息前而不是依赖可能被挤掉的历史消息。清理会话对于一次性任务可以不传递sessionId让 SDK 创建临时会话任务结束即丢弃。4.3 工具调用的可靠性工具调用是 Agent 与外界交互的桥梁必须稳定。健壮的错误处理在 Tool 的call函数内部一定要用try-catch包裹并返回结构化的错误信息让调用它的 Agent 能理解发生了什么。call: async ({ url }) { try { const response await fetch(url); if (!response.ok) throw new Error(HTTP ${response.status}); const data await response.text(); return { success: true, data }; } catch (error) { // 返回 Agent 能理解的错误描述 return { success: false, error: 获取网页失败${error.message} }; } },设置超时对于网络请求等可能长时间阻塞的工具务必设置超时。import { setTimeout } from node:timers/promises; call: async ({ params }) { const timeoutPromise setTimeout(10000, { signal: AbortSignal.timeout(10000) }).then(() { throw new Error(工具调用超时); }); const workPromise doSomeHeavyWork(params); return Promise.race([workPromise, timeoutPromise]); },工具描述要精准description和inputSchema是 Agent 决定是否以及如何调用工具的依据。描述应清晰说明工具的用途和输入参数的意义。4.4 成本与性能优化多 Agent 调用意味着多次 LLM API 请求成本可控性很重要。模型分级像我们示例中那样将轻量任务如分析、分类交给gpt-4o-mini或gpt-3.5-turbo将需要深度思考、创造或复杂推理的任务交给gpt-4o。缓存对于纯函数式、输入相同输出必然相同的工具如查询静态数据、计算可以引入缓存机制内存缓存如lru-cache或分布式缓存如 Redis避免重复调用 LLM 或外部 API。并行化如果多个工具调用之间没有依赖关系可以考虑并行执行。虽然 SDK 的run是顺序的但你可以在自定义的顶层逻辑中手动并行运行多个 Agent然后汇总结果。4.5 常见问题排查Agent 不调用工具首先检查工具的description是否足够清晰能让 LLM 理解在什么场景下使用它。其次检查inputSchema是否与 Agent 试图提供的数据匹配。打开 Tracing 查看 Agent 在决定时的思考过程。Handoff 后上下文丢失Handoff 会传递整个 Session 历史。如果感觉丢失检查目标 Agent 的instructions是否过于笼统未能有效利用历史。可以在目标 Agent 的指令中明确说明“请基于之前的对话历史来回答”。Guardrail 导致循环如果 Guardrail 的validateOutput一直不通过Agent 会不断重试。务必确保你的验证逻辑是可达的并且在不通过时提供足够具体、可操作的message指导 Agent 如何修正。实时语音 Agent 的延迟对于Realtime Agents网络延迟和音频处理耗时是关键。尽量在离用户近的区域部署服务端并优化音频编解码流程。SDK 的流式响应设计有助于减少感知延迟。5. 从示例到生产架构思考当你玩转示例后想要将其用于生产环境还需要考虑以下几点部署与扩展Agent 工作流本质是无状态的函数组合。你可以将每个Agent或Tool部署为独立的 Serverless Function如 Vercel Edge Functions, Cloudflare Workers通过事件或消息队列串联。SDK 对 Cloudflare Workers 的实验性支持正是为此方向铺路。状态持久化虽然Session管理对话历史但如果你需要持久化更复杂的应用状态如工作流进度、用户数据需要将其与你的数据库结合。可以将sessionId作为外键存储在业务数据表中。监控与告警充分利用Tracing数据。可以将其导出到监控系统如 Datadog, Sentry设置告警规则如工具调用失败率 5%、平均响应时间过长。对于成本记录每次run的 token 消耗并设置每日/每月预算告警。测试策略测试 AI 应用颇具挑战。可以对固定输入进行回归测试对比输出是否在可接受范围内。更有效的是测试“工作流”本身模拟工具调用验证 Agent 在特定中间状态下是否能做出正确的决策调用正确的工具或进行 Handoff。SDK 的模块化设计使得 Mock 工具和 Agent 变得相对容易。OpenAI Agents SDK for JavaScript/TypeScript 提供了一个极其优雅的抽象层让你能专注于设计 AI 的协作逻辑而不是陷入底层的胶水代码。从简单的自动化脚本到复杂的多模态交互系统它都能提供坚实的支撑。我个人最大的体会是它促使我更结构化地思考 AI 应用——不再是单个提示词的“黑魔法”而是由角色明确、职责清晰的“数字员工”组成的、可预测、可调试、可扩展的系统。开始用它构建你的第一个智能体团队吧从那个博客大纲生成器开始你会发现拆解复杂任务并分配给不同的 AI 专家去协同完成是一件既高效又充满乐趣的事。