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

图:本站根据 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 充值,免交密码即可卡密兑换。
三、开启流式输出与防死循环常见排错

图:本站根据 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;
开发联调中若遇到报错,重点核查以下三处:
- Zod 可选参数报
invalid_json_schema:把z.string().optional()改为z.string().nullable(),满足服务端严格模式对必填键的要求。 - 抛出
MaxTurnsExceededError:两个智能体互相把会话转交给对方、或工具持续返回模糊错误导致模型无限重试。务必给run显式设置合理的maxTurns(如8到15),并在handoffDescription中写清不重叠的接管条件。 - 追踪链路查看: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 API 函数调用(function calling)怎么写
- OpenAI API 结构化输出(Structured Outputs)怎么写
- OpenAI API 流式输出(streaming)怎么写
- OpenAI Responses API 与 Chat Completions 区别
参考资料
- 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
0 条评论
还没有评论,来抢沙发~