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

圖:本站根據 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 整理的示意圖
三、實戰選型與防死循環細節
在實際工程裏,把上面兩種模式跑穩還要留心三處官方細節:
- 寫好
handoff_description與tool_description:分診或主控模型全靠這段簡短描述決定該點誰的名。邊界含糊(比如兩個專家都寫「負責處理用戶問題」)會導致路由亂跳。 - 避免雙向無條件來回交接:如果 A 能交接給 B,B 又能交接回 A,務必在兩邊的
instructions裏寫清「什麼條件下自己答、什麼條件下才允許轉走」,併合理設定Runner.run(..., max_turns=...)上限防止死循環燒乾額度(遇到限流排查見 OpenAI API 429 錯誤處理)。 - 開發調試配合個人訂閱工具: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 快速入門教學(Python)
- OpenAI Responses API 是什麼:與 Chat Completions 的區別
- Claude Agent SDK 快速上手
- OpenAI API 429 錯誤排查
參考資料
- 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
0 條評論
還沒有評論,來搶沙發~