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 条评论

登录 后参与评论

还没有评论,来抢沙发~