OpenAI Agents SDK(TypeScript / Node.js 版 @openai/agents)入门:定义 Agent、Zod 工具、Handoffs 与流式输出

想用 TypeScript 快速写多智能体协作应用却不想背负厚重框架?本文按官方文档整理 @openai/agents 的安装要求、Agent 定义、Zod 工具函数、Handoffs 路由交接与 stream 流式输出完整代码。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

  1. 官方 TypeScript 版包名为 @openai/agents,核心只有四个原语。分别是 Agent(智能体定义)、tool(基于 Zod 的函数工具)、handoffs(控制权转交)与 run(执行循环引擎),无需学习庞大抽象层。
  2. run() 自动托管多轮工具调用闭环。模型触发工具后,SDK 会自动校验入参、执行本地异步函数、回传结果并继续推理,直到产出 finalOutput 或触发最大轮数上限(maxTurns)。
  3. Zod 工具里的可选字段要配合 .nullable()。由于底层默认开启严格 Schema 模式,单纯写 .optional() 会触发校验报错,应写成 z.string().nullable()。
  4. 开启流式只需在 run 第三个配置参数中传入 stream: true。既可直接读取纯文本流渲染打字机效果,也能遍历底层工具调用与交接事件。
  5. 本地日常写业务代码或联调智能体提示词时,国内缺少境外信用卡的开发者可在本站自助开通 ChatGPT Plus 或高配额 ChatGPT Pro 搭配 Codex 提效,企业团队可了解 ChatGPT Business 团队定制。

Agents SDK TS 四大核心原语

图:本站根据 OpenAI Agents SDK TypeScript 官方文档 整理的示意图

本文根据 OpenAI 官方文档《OpenAI Agents SDK TypeScript》《Agents SDK Guide》及官方 GitHub 仓库整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。

适用于谁

  • 技术栈以 Node.js、Next.js 或全栈 TypeScript 为主,想用官方轻量原语搭建单智能体或多智能体系统的开发者;
  • 需要用 zod 做严格工具入参校验,并让分诊智能体(Triage Agent)自动把任务交接(Handoff)给专职子智能体的人;
  • 希望在后端服务里边执行工具调用边把生成文本流式推送给前端界面的工程师。

一、环境安装与四大核心原语对照

确保本机运行 Node.js 22+(或当前 LTS 版本),安装核心包与 zod(API 密钥准备见 /guides/openai-api-key):

bash
npm install @openai/agents zod
export OPENAI_API_KEY="sk-proj-..."

对比裸调底层函数调用(见 /guides/openai-api-function-calling)和结构化输出(见 /guides/openai-api-structured-outputs),SDK 封装后的对应关系如下:

原语组件作用说明关键配置字段
new Agent(...)绑定人设指令、模型、可用工具与可转交下游name、instructions、model、tools、handoffs
tool(...)把本地 TS 异步函数暴露给模型调用并做类型推导name、description、parameters(Zod 对象)、execute
handoff(agent)将当前对话上下文移交给另一名专职智能体接管handoffDescription、输入过滤器 inputFilter
run(agent, input)驱动多步「思考—调工具—交接—产出」主循环maxTurns、stream、context 依赖注入对象

二、完整示例:Zod 工具定义与多智能体 Handoffs 交接

下面构建一个订单查询工具、一名退款专员智能体与一名负责分流的前台接待智能体:

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

const queryOrderTool = tool({
  name: 'query_order',
  description: '按订单号查询当前发货与支付状态',
  parameters: z.object({
    orderId: z.string().describe('订单编号'),
    note: z.string().nullable().describe('备注说明,无则传 null'),
  }),
  async execute(args) {
    return `订单 ${args.orderId} 状态:已付款未发货,支持极速退款`;
  },
});

const refundSpecialist = new Agent({
  name: 'Refund Specialist',
  handoffDescription: '当用户明确要求办理退款或售后赔付时转交此专员',
  instructions: '你是售后退款专员,请先调用 query_order 核实状态,再用中文给出处理步骤。',
  tools: [queryOrderTool],
});

const triageAgent = new Agent({
  name: 'Triage Agent',
  instructions: '你是客服前台,普通咨询直接简短作答;涉及退款请求请立即转交退款专员。',
  handoffs: [refundSpecialist],
});

async function main() {
  const result = await run(triageAgent, '帮我把订单 ORD-9081 退掉,买错规格了');
  console.log('最终接管智能体:', result.lastAgent?.name);
  console.log('回复内容:', result.finalOutput);
}

main();
订阅与账号准备提示:用 TypeScript 编写复杂的 Agent 编排、路由单测与工具定义时,搭配官方编程助手能节省大量样板代码时间。国内用户可在本站自助选购 ChatGPT Plus 会员 或升级 ChatGPT Pro 充值,免交密码即可卡密兑换。

三、开启流式输出与防死循环常见排错

Agents SDK 常见报错与排查决策

图:本站根据 OpenAI Agents SDK TypeScript 官方文档 整理的示意图

需要流式向终端或前端 SSE 吐字时(流式事件对比见 /guides/openai-api-streaming),开启 stream 选项并消费文本流:

typescript
const streamed = await run(triageAgent, '请问发货地在哪里', {
  stream: true,
  maxTurns: 8,
});

streamed.toTextStream({ compatibleWithNodeStreams: true }).pipe(process.stdout);
await streamed.completed;

开发联调中若遇到报错,重点核查以下三处:

  1. Zod 可选参数报 invalid_json_schema:把 z.string().optional() 改为 z.string().nullable(),满足服务端严格模式对必填键的要求。
  2. 抛出 MaxTurnsExceededError:两个智能体互相把会话转交给对方、或工具持续返回模糊错误导致模型无限重试。务必给 run 显式设置合理的 maxTurns(如 8 到 15),并在 handoffDescription 中写清不重叠的接管条件。
  3. 追踪链路查看:SDK 默认自动上报执行轨迹(Tracing),登录 OpenAI Platform 的 Traces 面板即可可视化查看每一次工具入参、耗时与交接路径。

常见问题

问:@openai/agents 只能调 OpenAI 自家模型吗?

答:默认走 OpenAI Responses API(架构说明见 /guides/openai-responses-api),同时也支持自定义模型提供方适配器接入兼容接口,不过内置的云端可视化 Tracing 与原生托管工具在官方模型下体验最完整。

问:怎么把数据库实例或当前登录用户 ID 安全传给 tool 执行函数,而不暴露给大模型?

答:在 run 的配置参数中通过 context 属性注入本地上下文对象,工具的 execute(args, runContext) 第二个参数即可读取 runContext?.context,该对象不会发往模型端。

问:国内没有外币卡,或者公司研发需要开具增值税发票,怎么开通配套的官方会员?

答:可通过本站 AI 会员充值总览 选购 ChatGPT Plus 或 ChatGPT Pro,支持支付宝、微信支付及 AlipayHK,提供卡密自助兑换与企业定制,并支持开具增值税发票。实时价格以页面显示为准;售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。

相关教程

参考资料

  • OpenAI Agents SDK TypeScript 官方文档 — https://openai.github.io/openai-agents-js/
  • OpenAI Agents SDK JS 官方仓库 — https://github.com/openai/openai-agents-js
  • OpenAI API 官方文档:Agents SDK — https://platform.openai.com/docs/guides/agents-sdk

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同模型

  1. 01

    从免费试水到全职写码:Codex 个人开发者月度额度规划与 Plus / Pro 5x / Pro 20x 升级时机指南

    个人开发者用 Codex 写代码,怎么判断自己该留在 Plus、买 Credits 点数兜底,还是升级 Pro 5x(官方 Pro 100)或 Pro 20x(官方 Pro 200)?本文基于官方定价规则与 /status 预警信号,给出清晰月度额度规划。

    ChatGPTCodex0
  2. 02

    小微研发团队在 ChatGPT Business 与 Pro 之间怎么配 Codex 席位最省钱:角色分层与额度测算

    5 到 20 人的小微研发团队采购 Codex,全员上高配太贵、全员买基础档又天天卡 5 小时限流?本文对照官方 Business(Standard / Premium)与 Pro 规则,给出按角色分层的席位搭配与预算测算框架。

    ChatGPTCodex0
  3. 03

    ChatGPT + Codex 联合开发 SaaS MVP 实战:先写 PRD 与架构图再落库写代码

    直接让 AI 一口气从零写完 SaaS 往往表结构混乱、功能返工。本文拆解 ChatGPT 写 PRD 与架构图、落盘仓库文档与 AGENTS.md、再由 Codex 分片落库与测试验收的完整闭环。

    ChatGPTCodex0
  4. 04

    ChatGPT 智能交互界面(Intelligent UI)怎么触发和用好:表单、计算器、图表与对比卡片实战

    同样是用 GPT-6,为什么别人的 ChatGPT 能直接弹出带滑块的计算器、交互图表和对比卡片,你的却只回一大段纯文字?本文依据 OpenAI GPT-6 官方文档讲清触发前提、4 类高命中提问模板,以及不出交互界面时的排查方法。

    ChatGPT0
  5. 05

    买 ChatGPT Pro 5x 还是 Pro 20x 怎么按月度用量自测:Codex 并发与深度研究频次估算对照

    犹豫买 ChatGPT Pro 5x(官方 Pro 100)还是 Pro 20x(官方 Pro 200)?本文对照官方最新档位规则,用 Codex 并发任务、Fast 模式消耗倍率和深度研究频次三项指标帮你做月度用量自测。

    ChatGPTCodex0
  6. 06

    Codex 额度消耗太快怎么省:模型档位切换、推理强度降级、关闭非必要 Fast 模式与控上下文 6 招

    刚写半天代码就提示 Codex 触达周期限额?本文从 Token 计费原理拆解消耗黑洞,给出模型降档、推理强度调优、关闭非必要高速模式与控上下文的 6 招省额度方案。

    ChatGPTCodex0

同产品的其他教程

  1. 01

    用 ChatGPT 整理家庭装修预算明细、隐蔽工程验收清单与主材优缺点对比表实战

    第一次装修面对几十页施工报价单、密密麻麻的水电防水隐蔽项目与五花八门的主材参数,极易踩坑增项。本文梳理用 ChatGPT 审查装修报价漏项、生成带公式的预算明细表、定制工地隐蔽工程验收单与主材对比表的实战提示词。

    ChatGPT0
  2. 02

    用 ChatGPT 做费曼学习法读书共读:反向追问检验自己是否真读懂专业书籍与整理书单笔记

    读完一本专业硬书常感觉「合上书就忘」,直接让 AI 概括全书又容易产生懂了的错觉。本文介绍用 ChatGPT 结合 Study Mode 与费曼学习法做反向追问共读,通过通俗复述、挑刺盲区到沉淀书单卡片的完整流程与提示词。

    ChatGPT0
  3. 03

    用 ChatGPT 做外贸产品多语种目录、展会邀约与客户跟进节奏表(附脱敏与本地化提示词)

    做外贸展会与海外推广时,手工翻译十几款产品目录费时且容易留下一堆中式英文,展后客户跟进也常缺节奏。本文梳理用 ChatGPT 先脱敏建术语库、再批量产出多语种目录、展前邀约函与展后 21 天跟进节奏表的实战流程与提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写高质量技术专栏文章、开源项目 Release Notes 与版本更新日志实战

    让 AI 直接凭空写技术文章容易满篇空洞套话,直接甩 Git 记录写更新日志又常常漏掉破坏性变更。本文整理用 ChatGPT 结合真实代码片段、压测数据与 PR 摘要,高效产出深度技术专栏、GitHub Release Notes 与 CHANGELOG 的实战工作流。

    ChatGPT0
  5. 05

    用 ChatGPT 做产品用户访谈纪要编码、提炼高频痛点需求池与 RICE 优先级打分实战

    手头攒了十几份用户访谈逐字稿,手工贴便利贴归纳痛点耗时又容易带入主观偏见。本文分享用 ChatGPT 完成脱敏检查、逐份开放式编码、跨样本聚类高频痛点并搭建 RICE 优先级打分表的 5 步实战流,附可直接复制的三段核心提示词。

    ChatGPT0
  6. 06

    ChatGPT 网页版上传超过 10 个文件或回形针附件按钮变灰怎么办:打包合并与配额限制排查

    在 ChatGPT 网页版批量分析文档时,常遇到一次选超 10 个文件被拦截或输入框回形针按钮变灰。本文依据 OpenAI 文件上传与存储说明,梳理 6 类常见报错的分流排查法,提供 ZIP 打包、本地合并与 Projects 复用方案及可直接复制的解包提示词。

    ChatGPT0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~