04 - 多 Agent 编排与 Handoff

04 - 多 Agent 编排与 Handoff

学习目标

本章将带你探索 LlamaIndex 的多 Agent 编排机制。你将学到：

• AgentWorkflow 的多 Agent 管理架构
• handoff 工具的实现原理（return_direct + next_agent）
• can_handoff_to 约束防止无限循环
• AgentWorkflow.from_tools_or_functions() 自动 Agent 选择
• 多 Agent 间的状态传递策略

前置知识

• 多 Agent 路由 — 多 Agent 路由模式
• 事件驱动的 Agent 运行时 — 事件驱动架构

---

项目实践

AgentWorkflow 架构

AgentWorkflow 继承自 Workflow，管理多个 BaseWorkflowAgent，通过 handoff 工具实现 Agent 间的控制权转移。

Handoff 工具的实现原理

LlamaIndex 不使用独立的 Router/Manager Agent，而是通过 handoff 工具实现控制权转移。这是特殊的 return_direct=True 工具。

工作流程：

核心机制：

1. AgentWorkflow 自动为每个 Agent 创建 handoff 工具
2. handoff 工具标记为 return_direct=True——执行后跳过后续推理步骤
3. aggregate_tool_results 检测到 next_agent 状态后，切换到目标 Agent 继续执行
4. 所有 Agent 共享同一个 Context.store，状态自然传递

为什么用工具而非路由器：将交接决策嵌入到 Agent 的正常推理过程中，不需要额外的 LLM 调用来做路由判断。每个 Agent 在推理时可以自主决定是否需要移交控制权。

can_handoff_to 约束

每个 Agent 通过 can_handoff_to 列表限制可以交接的目标 Agent，防止无限循环和意外交接。

agent_a = ReActAgent(
    name="researcher",
    tools=[search_tool],
    can_handoff_to=["analyst"],  # 只能交接给 analyst
)

agent_b = FunctionAgent(
    name="analyst",
    tools=[analysis_tool],
    can_handoff_to=["researcher"],  # 只能交接给 researcher
)

无约束的风险：两个 Agent 可能互相无限 handoff，导致 LLM 调用无限循环。can_handoff_to 在工具级别强制执行交接边界。

多 Agent 状态传递

所有 Agent 共享同一个 Context.store，但通过不同的 key 管理各自的 memory：

记忆隔离：每个 Agent 的 memory 键独立存储，避免对话历史混乱。需要跨 Agent 共享的信息通过 state 传递。

AgentWorkflow.from_tools_or_functions() 自动选择

这个工厂方法根据 LLM 能力自动选择 Agent 类型：

workflow = AgentWorkflow.from_tools_or_functions(
    tools_or_functions=[
        search_tool,
        calculator_fn,
        data_analysis_fn,
    ],
    llm=my_llm,
)

自动选择逻辑：

• LLM 支持 function calling → 创建 FunctionAgent
• 不支持 → 创建 ReActAgent

设计优势：用户不需要了解 Agent 类型的细节，只需提供工具和 LLM，框架自动选择最优配置。

问题与规避

陷阱	对策
多 Agent 互相 handoff 导致无限循环	设置 max_iterations；使用 can_handoff_to 限制交接路径
Agent 间状态混淆	每个 Agent 使用独立的 memory 键；通过 state 显式传递共享数据
Handoff 工具被意外调用	在 handoff 工具的描述中明确其用途，引导 LLM 正确使用
Root Agent 选择不当	root_agent 应该是”最通用”的 Agent，能处理最多类型的查询

设计取舍

Handoff 工具 vs Router Agent

维度	Handoff 工具	Router Agent
决策者	当前 Agent 自主决定	独立 Router 集中决策
LLM 调用	不额外消耗（嵌入在推理中）	额外一次 Router 调用
可控性	低（Agent 可能意外交接）	高（Router 统一约束）
灵活性	高（动态路径选择）	中（Router 预先定义路径）
实现复杂度	低（利用现有工具机制）	中（需要额外 Router 逻辑）

LlamaIndex 选择 handoff 工具的原因：与现有的工具调用机制无缝集成，不需要额外的路由器组件。代价是每个 Agent 需要具备判断是否需要交接的能力。

参考来源

• LlamaIndex 官方文档：https://developers.llamaindex.ai/python/framework/