OpenAI Agents SDK 多代理教學:Handoffs 交接與 Agents as Tools 怎麼選

用 OpenAI Agents SDK 搭多智能體系統時,該用 handoffs 交接會話,還是用 agent.as_tool() 把子智能體當工具調?按官方文檔講清兩者的控制權差異、上下文過濾、Python 代碼寫法與選型標準。

NNathaniel bigo··原創首發·AI 輔助撰寫
8 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 其他 帳號

結論先說

  1. SDK 官方把多代理協作明確劃分為兩種核心模式:交接(Handoffs)與智能體當工具(Agents as Tools)。
  2. 選 handoffs 就是「轉人工專席」:分診智能體一旦觸發交接,對話控制權徹底移交給目標專家智能體,由專家直接讀取歷史並向用戶輸出最終回答。
  3. 選 agent.as_tool() 就是「經理派單收結果」:主控智能體全程握着方向盤,子智能體像普通函數一樣接收簡短參數、跑完把字符串結果交回主控,不對用戶直接說話。
  4. 單線深度接待用 Handoffs,多路並行彙總用 Agents as Tools;兩者還可以在同一套系統裏嵌套混用。
  5. 交接預設傳遞完整會話歷史;若想隱藏上游雜亂的工具調用記錄或觸發埋點回調,用 handoff() 包裝函數自定義 input_filter 和 on_handoff。

Handoffs 與智能體當工具對比

圖:本站根據 OpenAI Agents SDK 官方文檔:Handoffs 整理的示意圖

本文根據 OpenAI Agents SDK 官方文檔《Handoffs》《Agents》及官方 GitHub 倉庫整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。如果你還沒裝好環境或沒跑過單智能體示例,請先看 OpenAI Agents SDK 快速入門教學。

適用於誰

  • 已經跑通單個 Agent,準備把複雜業務拆成多個專職智能體協作,卻分不清 handoffs 和 as_tool() 該用哪個的 Python 開發者;
  • 用交接模式時發現下游智能體被上游幾十條冗長對話干擾,想裁剪傳遞歷史的人;
  • 想實現「總控編排器同時調三個專家智能體,再合併成一份統一口吻報告」的人。

一、模式一:Handoffs(完全移交會話控制權)

在客服中心、售後工單或技術分流場景裏,接待台搞清楚用戶意圖是「查退款」還是「修接口報錯」之後,就沒必要每次都在中間傳話了。直接把 handoffs 列表掛在入口智能體上,SDK 會自動為每個目標智能體生成一個形如 transfer_to_<agent_name> 的底層交接工具。

基礎交接與 handoff() 進階定製示例

除了直接把 Agent 實例放進列表,官方還提供了 handoff() 輔助函數,支持在交接瞬間執行回調函數(比如打日誌、預加載用戶訂單)或用 input_filter 清洗上下文:

python
from agents import Agent, Runner, handoff, RunContextWrapper

billing_agent = Agent(
    name="Billing Specialist",
    handoff_description="處理帳單核對、退款與發票相關問題",
    instructions="你是帳單專員,直接向用戶解答扣款與退款規則。",
)

tech_agent = Agent(
    name="Tech Support",
    handoff_description="排查 API 報錯、SDK 安裝與代碼異常",
    instructions="你是技術支援工程師,按步驟幫用戶定位報錯。",
)

def log_transfer(ctx: RunContextWrapper[None]):
    print("已觸發向帳單專員的會話交接")

triage_agent = Agent(
    name="Triage Agent",
    instructions="先判斷用戶訴求類別,再交接給對應的專員智能體處理。",
    handoffs=[
        handoff(agent=billing_agent, on_handoff=log_transfer),
        tech_agent,
    ],
)

result = Runner.run_sync(triage_agent, "我上個月的訂閱扣了兩次錢,怎麼查?")
print("最終作答智能體:", result.last_agent.name)
print(result.final_output)

注意看 result.last_agent:交接完成後,它指向的是接手的 Billing Specialist。如果你在做多輪對話循環,下一輪可以直接把 result.last_agent 作為新的起始智能體,讓帳單專員繼續跟用戶聊,省掉再次經過分診台的額外模型開銷。

二、模式二:Agents as Tools(主控編排與並行彙總)

反過來,如果用戶的請求是「把這段產品說明同時翻成日文和法文,並對比兩邊語氣差異」,交接模式就不合適了——因為交接給日文智能體後會話就結束了,沒人去調法文和做彙總。

這時調用 agent.as_tool(),把每個子智能體包裝成標準工具掛在主控經理(Manager)名下:

python
from agents import Agent, Runner

jp_translator = Agent(
    name="JP Translator",
    instructions="只把輸入文本準確翻譯成自然商務日語,不要加多餘解釋。",
)

fr_translator = Agent(
    name="FR Translator",
    instructions="只把輸入文本準確翻譯成自然商務法語,不要加多餘解釋。",
)

manager_agent = Agent(
    name="Translation Manager",
    instructions="按用戶要求調用對應的翻譯工具,收集齊所有語種譯文後統一排版輸出。",
    tools=[
        jp_translator.as_tool(
            tool_name="translate_to_japanese",
            tool_description="將給定文本翻譯為商務日語",
        ),
        fr_translator.as_tool(
            tool_name="translate_to_french",
            tool_description="將給定文本翻譯為商務法語",
        ),
    ],
)

result = Runner.run_sync(manager_agent, "請把「服務將於今晚零點升級維護」譯成日語和法語。")
print(result.final_output)

在這個結構裏,子智能體完全不知道外層長對話講了什麼,只收到 translate_to_japanese 傳進去的那一句話,上下文非常乾淨,Token 帳單也更容易預測。底層接口底座差異可參考 OpenAI Responses API 是什麼。

多智能體委派該選哪種寫法

圖:本站根據 OpenAI Agents SDK 官方文檔:Agents 整理的示意圖

三、實戰選型與防死循環細節

在實際工程裏,把上面兩種模式跑穩還要留心三處官方細節:

  1. 寫好 handoff_description 與 tool_description:分診或主控模型全靠這段簡短描述決定該點誰的名。邊界含糊(比如兩個專家都寫「負責處理用戶問題」)會導致路由亂跳。
  2. 避免雙向無條件來回交接:如果 A 能交接給 B,B 又能交接回 A,務必在兩邊的 instructions 裏寫清「什麼條件下自己答、什麼條件下才允許轉走」,併合理設定 Runner.run(..., max_turns=...) 上限防止死循環燒乾額度(遇到限流排查見 OpenAI API 429 錯誤處理)。
  3. 開發調試配合個人訂閱工具:SDK 運行消耗的是開發者平台 API 餘額;如果你在編寫和調試這套多代理代碼時使用 Codex 或 ChatGPT 輔助排錯,想補充日常開發額度可查看本站 ChatGPT Plus 充值說明。另一家主流官方代理工具包的橫向參考見 Claude Agent SDK 快速上手。

常見問題

問:handoffs 和 as_tool() 能在同一個項目裏混着用嗎?

答:完全可以,而且很常見。例如入口分診台先用 handoffs 把用戶轉給「研發排錯專家」,而這位專家內部再把「日誌提取子智能體」和「文檔檢索子智能體」通過 as_tool() 當助手調用。

問:子智能體能不能用比主控智能體更便宜的小模型?

答:可以。每個 Agent(...) 實例都支持單獨傳 model="..." 參數,分診路由或簡單格式提取配輕量模型、核心複雜推理配旗艦模型是官方推薦的省錢做法。

問:交接時如果不想把前幾輪工具調用的原始大 JSON 傳給下一個智能體怎麼辦?

答:使用 handoff(agent=..., input_filter=...),SDK 的 agents.extensions.handoff_filters 模組裏也內置了現成的過濾函數(例如移除所有工具調用歷史),直接傳入即可瘦身。

相關教學

參考資料

  • OpenAI Agents SDK 官方文檔:Handoffs — https://openai.github.io/openai-agents-python/handoffs/
  • OpenAI Agents SDK 官方文檔:Agents — https://openai.github.io/openai-agents-python/agents/
  • GitHub 倉庫:openai/openai-agents-python — https://github.com/openai/openai-agents-python

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  5. 05

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  6. 06

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0

同模型

  1. 01

    OpenAI 多模型分工指南:便宜模型做路由、強模型啃難題的官方選型方法

    所有請求都發給最強旗艦模型太慢又費額度?按 OpenAI 官方模型選型指南整理:先用旗艦建質素基線、再逐節點下探最輕檔位,讓輕量模型承擔意圖路由與護欄提取、強模型專注複雜多步推理。

    ChatGPTCodex0
  2. 02

    OpenAI Agents SDK 的 Guardrails 與 Tracing 怎麼用:安全護欄與鏈路追蹤詳解

    多智能體上線怕跑偏或出錯難查?按 OpenAI Agents SDK 官方文檔整理:@input_guardrail 與 @output_guardrail 熔斷機制、多代理鏈路裏的護欄生效位置,以及用 trace() 合併追蹤與脫敏控制。

    ChatGPT其他 AI 工具0
  3. 03

    GPT-6 發佈時間與更新了什麼:從 GPT-6 Astra 到聊天版 GPT-6(2026 年 9 月至 10 月時間線)

    GPT-6 什麼時候發佈?9 月 3 日 Astra 先向有限組織開放,9 月 22 日 Sol 和 Luna 進 Work 和 Codex,10 月 7 日 GPT-6 與 Intelligent UI 進入聊天。按時間線講更新了什麼。

    ChatGPT0
  4. 04

    GPT-6 怎麼用:在 ChatGPT 裏選到 GPT-6、各套餐能用哪幾檔,Intelligent UI 能讓它做什麼(可複製的提問)

    GPT-6 怎麼用?在 ChatGPT 模型選單選 GPT-6,再用 Thinking 滑桿選檔,Plus 有 Medium 和 High。講各套餐能用哪幾檔,以及 Intelligent UI 的用法和可複製的提問。

    ChatGPT0
  5. 05

    GPT-6 Pro(Astra)怎麼用、哪些套餐有:怎麼選到 Pro 檔、用量限制和 Pro 三檔價格

    GPT-6 Pro(Astra)怎麼用、哪些套餐有?按 OpenAI 幫助中心核對:聊天裏 Pro 檔給 Pro 100、Pro 200、Business 和 Enterprise;Plus 在 Work 和 Codex 裏含 Astra。講怎麼選到、用量上限和官方 Pro 價格。

    ChatGPT0
  6. 06

    OpenAI Agents SDK 教學:安裝、第一個智能體、工具與多智能體交接(Python)

    OpenAI Agents SDK 是什麼、怎麼上手?按官方 README 和 Quickstart 講清安裝命令、設定 API Key、十行代碼跑起第一個智能體、給它加函數工具、用 handoffs 做多智能體分工、在 Trace viewer 裏看調用過程,以及它的核心概念各是什麼。

    ChatGPT其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  4. 04

    A2A 協議是什麼、怎麼用:Agent2Agent 智能體互聯規範、名片發現與 Python 接入流程

    A2A(Agent2Agent)是由 Google 發起並移交 Linux 基金會託管的開放智能體通信協議,用來讓不同團隊、不同框架開發的獨立智能體跨網絡互相派單協作。本文按官方規範講清 Agent Card、Task 狀態機與 Python SDK 接入步驟。

    Gemini其他 AI 工具0
  5. 05

    AutoGen 現在怎麼樣了?微軟官方演進路線與 Microsoft Agent Framework 入門

    搜 AutoGen 新教學常被 0.2、0.4、社區分支和 Semantic Kernel 繞暈。按微軟官方文檔,微軟已將 AutoGen 與 Semantic Kernel 兩支團隊合併推出統一的開源框架 Microsoft Agent Framework。本文講清現狀與 Python 快速上手。

    ChatGPT其他 AI 工具0
  6. 06

    CrewAI 多輪對話與記憶怎麼配:memory=True 三層記憶、人工介入與 Flows 狀態持久化

    剛用上 CrewAI 的人常疑惑 kickoff 跑完就結束,怎麼做多輪連續對話與跨次記憶。本文按官方文檔拆解 memory=True 的短期/長期/實體三層記憶、嵌入模型配置,以及用 Flows 狀態流和 @persist 搭建多輪會話的實戰寫法。

    其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~