子 Agent

SubagentMiddleware 会添加一个 subagent 工具。模型调用该工具时，CubePi 创建一个临时子 Agent，运行一段自包含 prompt，并把子 agent 最终 assistant 文本作为工具结果返回。

适合父 agent 需要委派有边界的工作：研究、审查、抽取、聚焦实现等。

定义子 agent

from cubepi import Agent
from cubepi.middleware import SubagentMiddleware, SubagentSpec

subagents = {
    "researcher": SubagentSpec(
        name="researcher",
        description="Researches a narrow question and returns concise notes.",
        system_prompt="You are a precise research assistant.",
    ),
    "reviewer": SubagentSpec(
        name="reviewer",
        description="Reviews code for bugs, regressions, and missing tests.",
        system_prompt="You are a rigorous senior code reviewer.",
    ),
}

model = provider.model("claude-sonnet-4-5-20250929")

agent = Agent(
    model=model,
    middleware=[
        SubagentMiddleware(
            subagents=subagents,
    default_model=model,
            shared_tools=[web_search],
        ),
    ],
)

如果模型请求未知 subagent_type，CubePi 回退到 general-purpose 子 agent。 如果你没有定义它，middleware 会提供一个基础默认版本。

工具访问和 middleware 继承

子 agent 只获得你传入的工具：

• shared_tools 对所有子 agent 可用。
• SubagentSpec.tools 只对该类型子 agent 可用。
• excluded_tool_names 防止递归或 host 专用工具被共享。

用 inherited_middleware 传入所有子 agent 都应运行的 middleware。用 SubagentSpec.middleware 定义某个子 agent 类型专属行为。

把子事件流式传给 host

应用通常需要把子事件写入自己的 UI 或审计日志。传入 event_mapper 和可选 event_handler：

def map_event(event):
    if event.type == "text_delta":
        return {"type": "subagent_text_delta", "delta": event.delta}
    return None

async def handle_event(agent_id, payload):
    await ui_stream.send({"agent_id": agent_id, **payload})

SubagentMiddleware(
    subagents=subagents,
    default_model=model,
    event_mapper=map_event,
    event_handler=handle_event,
)

映射后的 payload 也会存入父工具结果的 details["subagent_events"]。

Tracing 和 abort

通过 tracer=... 传入 Tracer，即可给每个子运行附加 tracing。嵌套子 agent span 共享父 trace，所以 cubepi trace view <trace_id> 会把父工具调用 和子运行一起渲染出来。

父运行的 abort signal 会转发给子 agent。如果父运行在子 agent 执行中被 abort，子 agent 也会被 abort。

Prompt 约定

父模型在 subagent 工具调用里应发送自包含的 prompt。不要假设子 agent 能 看到父 agent 的完整隐藏上下文。prompt 里应包含目标、相关事实、约束和期望 输出格式。