结论先说
- 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 条评论
还没有评论,来抢沙发~