Handoff
把当前对话控制权从分流 Agent 转交给专业 Agent。
学习目标
- 能说明Handoff解决什么问题，以及何时适用。
- 能解释为什么“把 Handoff 当普通函数工具”是误区。
学习前需要掌握
背景与问题
有些场景需要专家直接接着与用户沟通。例如客服已经确认问题属于账单领域，继续由前台中转每一轮问答会增加延迟，还可能遗漏专家需要追问的信息。
Handoff 解决的是活动对话由谁继续处理的问题。它不同于请求专家分析一小段材料后返回主管，因此交接前必须明确目标、上下文和权限是否适合新的处理者。
概念定义
在 OpenAI Agents SDK 中，Handoff 作为模型可见的类函数工具，但调用后进入专门的交接路径，由目标 Agent 接管后续对话。
直观理解
前台确认问题类型后把电话真正转给专家，而不是每句话都通过前台中转。
核心原理
在 OpenAI Agents SDK 中，交接以模型可见的类函数能力暴露；被选中后，运行器进入专门交接路径，由指定目标 Agent 继续当前运行。普通专家工具返回后仍由调用者处理，二者控制流不同。
交接参数可以携带问题类别或简短移交说明等元数据。它不是整个应用上下文，也不会凭参数随意选择另一个目标；目标由应用配置的交接对象决定。
会话历史应按需要过滤，避免把无关私人信息传给新专家；同时保留目标、已验证事实、用户已给出的答案和未解决问题。只给一句含糊摘要可能迫使用户重复输入，也可能丢失原有约束。
若交接涉及不同账户、权限或领域，应用应在任何副作用前重新校验。SDK 的交接回调成功返回后会继续转移，授权失败不能只写一条警告然后正常返回；还要防止专家间来回转接形成循环。
这些控制流与输入参数的区分可对照 Agents SDK 的 Handoff 文档。
案例：客服将账单争议交给账单专家
前台已收集订单标识和用户对重复扣款的描述，交接时传入“疑似重复扣款”的分类元数据，并保留已经核验的订单信息。专家接管后可以直接询问缺失的扣款记录，而不要求用户重新讲述整个问题。
历史中与另一个售后问题相关的地址信息可以过滤，访问账单的权限则必须由系统另外检查。交给账单专家不意味着批准退款；若需要退款，该副作用仍走明确授权与执行验证。用户收到的最终答复来自当前活动专家，而不是假定前台一定再收回汇总。
理解与实践步骤
- 分流 Agent 识别领域
- 生成交接调用与必要载荷
- 应用验证目标和权限
- 目标 Agent 接管上下文
- 目标 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 条
- 把交接当成普通专家工具调用，错误预期会自动返回主管继续汇总。
- 把交接元数据当作完整上下文，或把全部历史未经筛选传给所有专家。
- 在交接回调中发现未授权却只记录日志后返回，或者让专家无限互相转接。
实际应用
- 客服分流
- 多语言专家
常见错误
- 把交接当成普通专家工具调用，错误预期会自动返回主管继续汇总。
- 把交接元数据当作完整上下文，或把全部历史未经筛选传给所有专家。
- 在交接回调中发现未授权却只记录日志后返回，或者让专家无限互相转接。
输入、输出与执行边界
输入
- 目标 Agent
- 交接参数
- 过滤后的历史
输出
- 新的活动 Agent
- 交接轨迹
能力
- 客服分流
- 多语言专家
安全风险与信任边界
移交应传递当前目标、已完成动作和必要证据，避免把整个历史中的敏感内容无差别复制。接收者需区分未执行计划与已发生副作用，不能将移交摘要中未经验证的结论升级为事实。
性能与失败模式
移交会增加上下文重建与角色切换成本，也可能丢失约束。记录移交原因、去向与终止状态，检测重复转交和来回循环；评价要看移交后是否真正完成任务，而不只看路由是否成功。
推荐学习资料
openai/openai-agents-python
OpenAI Agents SDK 的 Python 源码、文档、示例与集成测试仓库。
OpenAI · GitHub
仓库信息
构建和研究多 Agent 工作流
主要语言：Python包含数据集或实验需要额外环境