多 Agent Handoff

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

​

多 Agent Handoff

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

​

两种触发模式

​

Tool 模式（委托）

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

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

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 间的正式切换：

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

decision = Decision.handoff(target="researcher")

​

上下文策略

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

​

FULL — 完整传递

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

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

from qitos.core.agent_spec import AgentSpec, ContextStrategy

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

​

SUMMARY — 压缩传递（默认）

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

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

spec = AgentSpec(
    name="coder",
    description="编码专家",
    agent=coder_agent,
    context_strategy=ContextStrategy.SUMMARY,
)

​

ISOLATED — 隔离传递

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

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

spec = AgentSpec(
    name="executor",
    description="执行者",
    agent=executor_agent,
    context_strategy=ContextStrategy.ISOLATED,
)

​

SharedMemory 共享

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

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

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 提供了比上下文策略更精细的控制：

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

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 跨度记录：

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

from qitos.tracing import TracingProvider

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