教程8：交接与委托

文档摘要

教程 8：交接与委托掌握代理间任务委托！本教程将教你如何使用 OpenAI Agents SDK 的交接系统，创建专门的代理，让它们能够智能地相互委托任务，从而构建强大的多代理工作流。你将学到的内容代理交接：在专业代理之间委派任务交接配置：自定义工具名称、描述和回调函数输入过滤：控制传递给其他代理的上下文内容分诊模式：构建智能路由与委托系统核心概念：什么是交接？交接功能实现了代理的专业化与委托，让代理能够将任务转交给具备特定专长的其他代理。可以把交接看作一种智能路由系统，它：为不同领域（支持、计费、技术）创建专门的代理根据用户需求实现智能任务委托在代理交接过程中保持对话上下文提供自定义路由逻辑与输入过滤功能教程概览本教程将演示关键的交接模式： 1.

教程 8：交接与委托

掌握代理间任务委托！本教程将教你如何使用 OpenAI Agents SDK 的交接系统，创建专门的代理，让它们能够智能地相互委托任务，从而构建强大的多代理工作流。

你将学到的内容

代理交接：在专业代理之间委派任务
交接配置：自定义工具名称、描述和回调函数
输入过滤：控制传递给其他代理的上下文内容
分诊模式：构建智能路由与委托系统

核心概念：什么是交接？

交接功能实现了代理的专业化与委托，让代理能够将任务转交给具备特定专长的其他代理。可以把交接看作一种智能路由系统，它：

为不同领域（支持、计费、技术）创建专门的代理
根据用户需求实现智能任务委托
在代理交接过程中保持对话上下文
提供自定义路由逻辑与输入过滤功能


┌─────────────────────────────────────────────────────────────┐
│                    HANDOFF WORKFLOW                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  USER REQUEST                                               │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    1. ANALYZE REQUEST                      │
│  │   TRIAGE    │                                            │
│  │   AGENT     │    2. DECIDE DELEGATION                    │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    3. CALL HANDOFF TOOL                    │
│  │   HANDOFF   │    "transfer_to_billing_agent"             │
│  │    TOOL     │                                            │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    4. TRANSFER CONTEXT                     │
│  │  BILLING    │    (with optional filtering)               │
│  │   AGENT     │                                            │
│  └─────────────┘    5. PROCESS REQUEST                      │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    6. RETURN RESPONSE                      │
│  │  RESPONSE   │                                            │
│  │   TO USER   │                                            │
│  └─────────────┘                                            │
└─────────────────────────────────────────────────────────────┘

教程概览

本教程将演示关键的交接模式：

1. 基础交接 (`basic_handoffs.py`)

Simple agent-to-agent delegation
Customer support triage example
Automatic tool creation from handoff definitions

2. Advanced Handoffs (`advanced_handoffs.py`)

自定义交接配置与回调函数
输入过滤与上下文管理
使用结构化输入数据进行交接

项目结构


8_handoffs_delegation/
├── README.md                # This file - concept explanation
├── requirements.txt         # Dependencies
├── basic_handoffs.py        # Simple agent handoffs (40 lines)
├── advanced_handoffs.py     # Advanced handoff patterns (50 lines)
├── app.py                  # Streamlit handoff demo (optional)
└── env.example             # Environment variables template

学习目标

完成本教程后，你将掌握：

✅ 如何创建代理交接以实现任务委托
✅ 配置带有自定义名称与描述的交接工具
✅ 使用输入过滤器控制上下文传递
✅ 构建包含多个代理的智能分诊系统
✅ 何时以及如何使用交接而非直接代理编排

开始使用

安装 OpenAI Agents SDK：
```
pip install openai-agents
```
安装依赖项：
```
pip install -r requirements.txt
```

设置环境变量：


cp env.example .env
# Edit .env and add your OpenAI API key

测试基础交接：
```
python basic_handoffs.py
```
尝试高级模式：
```
python advanced_handoffs.py
```

关键交接模式

1. 基础交接设置


from agents import Agent, handoff

billing_agent = Agent(name="Billing Agent")
support_agent = Agent(name="Support Agent")

triage_agent = Agent(
    name="Triage Agent",
    handoffs=[billing_agent, support_agent]  # Creates tools automatically
)

2. 自定义交接配置


from agents import Agent, handoff

def on_handoff_callback(ctx):
    print(f"Handoff to {ctx.agent.name} initiated")

custom_handoff = handoff(
    agent=billing_agent,
    tool_name_override="escalate_to_billing",
    tool_description_override="Transfer complex billing issues",
    on_handoff=on_handoff_callback
)

3. 输入过滤


from agents.extensions import handoff_filters

filtered_handoff = handoff(
    agent=support_agent,
    input_filter=handoff_filters.remove_all_tools  # Clean context
)

交接设计最佳实践

明确专业化：每个代理应有明确的专业领域
智能路由：为大语言模型使用描述性工具名称与指令
上下文管理：考虑哪些上下文应在代理间传递
回调集成：利用回调记录日志、指标与工作流程
输入验证：在传递特定数据时对输入进行结构化处理

下一步

完成本教程后，你将准备好：

教程 9：多代理编排 - 复杂多代理工作流与并行执行
教程 10：追踪与可观测性 - 监控与调试
教程 11：生产模式 - 真实世界部署策略

专家提示

从简单入手：先从基础交接开始，逐步增加复杂度
清晰说明：让代理角色与交接触发条件一目了然
测试路由：验证大语言模型在不同场景下选择正确的代理
监控交接：利用回调与追踪功能跟踪委托模式
上下文策略：规划哪些信息应在代理间传递

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文（母语）文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。