> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 多 Agent Handoff

> 多 Agent 协作中的上下文传递策略和 SharedMemory 共享

# 多 Agent Handoff

QitOS 支持多 Agent 协作，通过 Handoff 机制在 Agent 之间切换执行。Handoff 决定了目标 Agent 接收哪些上下文信息。

## 两种触发模式

### Tool 模式（委托）

通过 `DelegateTool` 触发，适合临时性的子任务委托：

示意片段（非独立程序；完整执行文件见本页链接）。

```python theme={null}
from qitos.core.agent_spec import AgentSpec, AgentRegistry

registry = AgentRegistry()
registry.register(AgentSpec(
    name="coder",
    description="编码专家",
    agent=coder_agent,
))

# Engine 自动为每个注册的 Agent 创建 DelegateTool
delegate_tools = registry.get_delegate_tools()
```

### Decision 模式（切换）

通过 `Decision.handoff()` 触发，适合 Agent 间的正式切换：

示意片段（非独立程序；完整执行文件见本页链接）。

```python theme={null}
decision = Decision.handoff(target="researcher")
```

## 上下文策略

Handoff 时，源 Agent 的对话历史如何传递给目标 Agent 由上下文策略控制：

### FULL — 完整传递

传递完整的对话历史，适合目标 Agent 需要完整上下文的场景。

示意片段（非独立程序；完整执行文件见本页链接）。

```python theme={null}
from qitos.core.agent_spec import AgentSpec, ContextStrategy

spec = AgentSpec(
    name="researcher",
    description="研究员",
    agent=researcher_agent,
    context_strategy=ContextStrategy.FULL,
)
```

### SUMMARY — 压缩传递（默认）

压缩较旧的历史为摘要，保留最近 3 轮完整消息。适合大多数场景，防止上下文爆炸。

示意片段（非独立程序；完整执行文件见本页链接）。

```python theme={null}
spec = AgentSpec(
    name="coder",
    description="编码专家",
    agent=coder_agent,
    context_strategy=ContextStrategy.SUMMARY,
)
```

### ISOLATED — 隔离传递

只传递系统提示和任务描述，目标 Agent 从零开始。适合完全独立的子任务执行。

示意片段（非独立程序；完整执行文件见本页链接）。

```python theme={null}
spec = AgentSpec(
    name="executor",
    description="执行者",
    agent=executor_agent,
    context_strategy=ContextStrategy.ISOLATED,
)
```

## SharedMemory 共享

多 Agent 可以通过 `SharedMemoryManager` 共享状态数据：

示意片段（非独立程序；完整执行文件见本页链接）。

```python theme={null}
from qitos.core.shared_memory import SharedMemoryManager, InMemorySharedMemory

manager = SharedMemoryManager(InMemorySharedMemory())

# 创建命名空间
parent_ns = manager.namespace("parent")
child_ns = manager.namespace("child")

# 父 Agent 写入
parent_ns.write("task", "分析代码")

# 子 Agent 可以读取
child_view = manager.namespace("parent", read_only=True)
task = child_view.read("task")  # "分析代码"

# 只读视图不能写入
child_view.write("task", "修改")  # raises PermissionError
```

## HandoffContext 精细控制

`HandoffContext` 提供了比上下文策略更精细的控制：

示意片段（非独立程序；完整执行文件见本页链接）。

```python theme={null}
from qitos.core.agent_spec import HandoffContext, ContextStrategy

spec = AgentSpec(
    name="sub_agent",
    description="子 Agent",
    agent=sub_agent,
    handoff_context=HandoffContext(
        strategy=ContextStrategy.SUMMARY,
        shared_state_fields=["task", "result"],  # 只共享这些状态字段
        max_history_rounds=5,  # 最多保留 5 轮历史
    ),
)
```

## 追踪

Handoff 事件自动记录在追踪中：

* `HANDOFF_START` — 记录源 Agent、目标 Agent、上下文策略
* `HANDOFF_END` — 记录目标 Agent 确认

启用 `TracingProvider` 后，Handoff 会创建 `HandoffSpanData` 跨度记录：

示意片段（非独立程序；完整执行文件见本页链接）。

```python theme={null}
from qitos.tracing import TracingProvider

provider = TracingProvider()
engine = Engine(agent=my_agent, tracing_provider=provider)
```