結論先說
- 官方 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 條評論
還沒有評論,來搶沙發~