05 Subagents：上下文隔离

它是什么

Subagent 用独立上下文处理重活，主 Agent 只接收最终结果。它解决的问题是：网页搜索、文件读取、数据库查询这类多步工具调用会制造大量中间日志，容易把主上下文撑爆。runtime context 会传给 subagent，所以用户和权限信息仍然可用。

最小代码

文件：deepagent_src/context_engineering_teach/05_context_isolation_subagents.py

research_subagent = {
    "name": "researcher",
    "description": "Do heavy research and return only a concise summary.",
    "system_prompt": "Keep the final answer under 120 words. Do not return raw tool logs.",
    "tools": [get_user_marker],
}

运行

uv run python deepagent_src/context_engineering_teach/05_context_isolation_subagents.py

预期输出：

context isolation subagent real agent ok

验证方式

脚本真实调用主 Agent，让它把任务交给 subagent；subagent 调用 get_user_marker 工具，验证 runtime context 能传到 subagent。

常见误区

别让 subagent 返回原始搜索结果和完整工具日志。subagent 的价值就是隔离上下文，返回一份够主 Agent 决策的短总结。

相关资源

查看示例代码：deepagent_src/context_engineering_teach/05_context_isolation_subagents.py

from __future__ import annotations

from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain.tools import ToolRuntime, tool

from _model import get_real_model
from deepagent_src.agent_output import invoke_and_pretty_print


@dataclass
class RunContext:
    user_id: str
    thread_id: str


@tool
def get_user_marker(runtime: ToolRuntime[RunContext]) -> str:
    """Return the user marker from runtime context."""
    return f"{runtime.context.user_id}@{runtime.context.thread_id}"


research_subagent = {
    "name": "researcher",
    "description": "Do heavy research and return only a concise summary.",
    "system_prompt": "Keep the final answer under 120 words. Do not return raw tool logs.",
    "tools": [get_user_marker],
}


def main() -> None:
    agent = create_deep_agent(
        model=get_real_model(),
        subagents=[research_subagent],
        context_schema=RunContext,
    )
    result = invoke_and_pretty_print(
        agent,
        {
            "messages": [
                {
                    "role": "user",
                    "content": (
                        "把任务交给 researcher subagent。"
                        "要求 subagent 调用 get_user_marker 工具，并返回工具结果。"
                    ),
                }
            ]
        },
        context=RunContext(user_id="u-123", thread_id="t-1"),
    )

    assert agent is not None
    assert research_subagent["tools"] == [get_user_marker]
    assert "u-123@t-1" in result["messages"][-1].content
    print("context isolation subagent real agent ok")


if __name__ == "__main__":
    main()