Handoff
把当前对话控制权从分流 Agent 转交给专业 Agent。
学习目标
- 能说明Handoff解决什么问题,以及何时适用。
- 能解释为什么“把 Handoff 当普通函数工具”是误区。
学习前需要掌握
背景与问题
当专家需要直接与用户交流、使用自己的指令和工具时,交接比让主管代为转述更自然。
概念定义
在 OpenAI Agents SDK 中,Handoff 作为模型可见的类函数工具,但调用后进入专门的交接路径,由目标 Agent 接管后续对话。
直观理解
前台确认问题类型后把电话真正转给专家,而不是每句话都通过前台中转。
核心原理
Handoff 与 agent.asTool() 不同:前者转移控制,后者由 Manager 保持控制。
交接输入 Schema 传递模型在交接时决定的元数据,不等同于应用上下文。
授权依赖参数时,应在 onHandoff 开始处、任何副作用之前检查。
理解与实践步骤
- 1
分流 Agent 识别领域
- 2
生成交接调用与必要载荷
- 3
应用验证目标和权限
- 4
目标 Agent 接管上下文
- 5
目标 Agent 产生最终输出
代码实现
示例 1
Agents SDK:分流 Agent 把会话交给专家
example_01.py用途:对应 OpenAI Agents SDK TypeScript 当前 Handoff 结构。仅展示,不在本站运行;实际运行需要按官方文档配置 SDK 与模型访问。
import { Agent, run } from '@openai/agents';
const chineseAgent = new Agent({
name: 'Chinese specialist',
instructions: 'Reply in Chinese and keep technical terms precise.',
});
const englishAgent = new Agent({
name: 'English specialist',
instructions: 'Reply in English.',
});
const triageAgent = new Agent({
name: 'Language triage',
instructions: 'Hand off to the specialist matching the user language.',
handoffs: [chineseAgent, englishAgent],
});
const result = await run(triageAgent, '请解释 Handoff。');
console.log(result.finalOutput);代码解析
解析始终位于完整代码下方,并按实际代码段逐项对应。
输入数据与任务
对应 OpenAI Agents SDK TypeScript 当前 Handoff 结构。仅展示,不在本站运行;实际运行需要按官方文档配置 SDK 与模型访问。
Step 1 · 1–1 行
导入当前步骤需要的数值计算、预处理、模型或评价工具。依赖集中写在代码开头,便于复现。
import { Agent, run } from '@openai/agents';Step 2 · 3–6 行
triageAgent 的 handoffs 声明可交接目标。
const chineseAgent = new Agent({
name: 'Chinese specialist',
instructions: 'Reply in Chinese and keep technical terms precise.',
});Step 3 · 8–11 行
run 内部处理模型调用、交接与后续 Agent 循环;最终输出来自接管后的 Agent。
const englishAgent = new Agent({
name: 'English specialist',
instructions: 'Reply in English.',
});Step 4 · 13–17 行
执行当前代码段,并把得到的状态传给下一步。
const triageAgent = new Agent({
name: 'Language triage',
instructions: 'Hand off to the specialist matching the user language.',
handoffs: [chineseAgent, englishAgent],
});Step 5 · 19–20 行
执行当前代码段,并把得到的状态传给下一步。
const result = await run(triageAgent, '请解释 Handoff。');
console.log(result.finalOutput);预期输出或运行结果
中文专家接管并返回中文解释;实际文本由所配置模型决定。
常见错误 · 3 条
- 把 Handoff 当普通函数工具
- 未过滤不必要历史
- 在授权前产生副作用
实际应用
- 客服分流
- 多语言专家
常见错误
输入、输出与执行边界
输入
- 目标 Agent
- 交接参数
- 过滤后的历史
输出
- 新的活动 Agent
- 交接轨迹
能力
- 客服分流
- 多语言专家
官方来源与时效
资料记录日期:2026-08-30(不代表已逐项核验)。产品能力、SDK 参数和协议状态可能变化,请以链接页面的当前版本为准。
推荐学习资料
openai/openai-agents-python
OpenAI Agents SDK 的 Python 源码、文档、示例与集成测试仓库。
OpenAI · GitHub
仓库信息
构建和研究多 Agent 工作流
主要语言:Python包含数据集或实验需要额外环境