Deep Agents 中的上下文工程 - 以编程方式使用文档

上下文工程是指以正确的格式提供正确的信息和工具，使您的深度智能体能够可靠地完成任务。

深度智能体可以访问多种上下文。某些来源在智能体启动时提供；其他来源在运行时变得可用，例如用户输入。深度智能体包含用于管理跨长时间会话上下文的内置机制。

本页概述了您的深度智能体可以访问和管理的不同类型的上下文。

上下文类型

上下文类型	您控制的内容	范围
输入上下文	启动时输入智能体提示的内容（系统提示、记忆、技能）	静态的，每次运行应用
运行时上下文	调用时传递的静态配置（用户元数据、API 密钥、连接）	每次运行，传播到子智能体
上下文压缩	内置卸载和摘要功能，用于将上下文保持在窗口限制内	自动触发，接近限制时
上下文隔离	使用子智能体隔离重负荷工作，只将结果返回给主智能体	每个子智能体，委托时
长期记忆	使用虚拟文件系统跨线程的持久化存储	跨对话持久化

输入上下文

输入上下文是在深度智能体启动时提供的信息，会成为其系统提示的一部分。最终提示由多个来源组成：

系统提示

您的自定义系统提示会添加到内置系统提示的前面，内置提示包含规划、文件系统工具和子智能体的指导。使用它来定义智能体的角色、行为和知识：

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    system_prompt=(
        "You are a research assistant specializing in scientific literature. "
        "Always cite sources. Use subagents for parallel research on different topics."
    ),
)

system_prompt 参数是静态的，这意味着它不会在每次调用时改变。对于某些用例，您可能需要动态提示：例如，告诉模型"您有管理员权限"与"您有只读权限"，或者从长期记忆. 注入用户偏好，如"用户偏好简洁回复"。如果您的提示依赖于上下文或 runtime.store，请使用 @dynamic_prompt 来构建上下文感知的指令。您的中间件可以读取 request.runtime.context 和 request.runtime.store. 请参阅自定义了解默认中间件堆栈以及用于添加自定义中间件。请参阅 LangChain 上下文工程指南获取示例。

当 **不** 仅工具使用上下文时或 runtime.store；工具直接接收 ToolRuntime 对象（包括 runtime.context 和 runtime.store）直接。仅当需要将工具与系统提示更新打包时才添加中间件。

记忆

记忆文件（AGENTS.md）提供持久上下文，该上下文 **始终加载** 到系统提示中。将记忆用于项目约定、用户偏好和应适用于每次对话的关键准则：

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)

与技能不同，记忆始终被注入——不存在渐进式披露。为避免上下文过载，请保持记忆最小化；对于详细的工作流程和特定领域的内容，请使用技能。请参阅记忆了解配置详情。

技能

技能提供 **on-demand** 能力。代理从每个 SKILL.md 在启动时，然后仅在确定技能相关时才加载完整内容。这减少了token使用量，同时仍提供专业化工作流程：

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    skills=["/skills/research/", "/skills/web-search/"],
)

让每个技能专注于单一工作流程或领域；宽泛或重叠的技能会稀释相关性并在加载时膨胀上下文。在技能内，保持主要内容简洁，将详细参考资料移到在技能文件中引用的单独文件中。将始终相关的约定放在记忆中。参见技能获取创作和配置信息。

工具提示词

工具提示词是指导模型如何使用工具的指令。所有工具都公开模型在其提示词中看到的元数据——通常是模式（schema）和描述。你通过 tools 参数向模型暴露该工具元数据（schema和描述）。深度代理的内置工具被打包在默认中间件堆栈中，通常还会更新系统提示词，为这些工具提供更多指导。

内置工具 – 添加测试框架功能（规划、文件系统、子代理）的中间件会自动将工具特定指令追加到系统提示词，创建解释如何有效使用这些工具的工具提示词。参见自定义获取完整列表： - 规划提示词 – 用于 write_todos 维护结构化任务列表的指令 - 文件系统提示词 – ls, read_file, write_file, edit_file, glob, grep 的文档（以及 execute 使用沙箱后端时） - 子代理提示词 – 使用 task 工具委托工作的指南 - 人机交互提示词 – 在指定工具调用时暂停的使用说明（当 interrupt_on 设置时） - 本地上下文提示词 – 当前目录和项目信息（仅CLI）

你提供的工具 – 通过 tools 参数传递的工具会将其描述（来自工具schema）发送给模型。你还可以添加自定义中间件来添加工具并追加自己的系统提示词指令。

对于你提供的工具，确保提供清晰的名称、描述和参数描述。这些指导模型推理何时以及如何使用该工具。在描述中包含 *何时* 使用该工具，并描述每个参数的作用。

@tool(parse_docstring=True)
def search_orders(
    user_id: str,
    status: str,
    limit: int = 10
) -> str:
    """Search for user orders by status.

    Use this when the user asks about order history or wants to check
    order status. Always filter by the provided status.

    Args:
        user_id: Unique identifier for the user
        status: Order status: 'pending', 'shipped', or 'delivered'
        limit: Maximum number of results to return
    """
    # Implementation here
    ...

参见概述了解内置功能，参见自定义了解直接传递工具的方式。

完整系统提示词

深度智能体的系统消息——模型在运行开始时收到的组合系统提示——由以下部分组成：

自定义 system_prompt （如果提供）
基础智能体提示词
待办事项提示词：关于如何使用待办列表进行规划的说明
记忆提示词： AGENTS.md + 记忆使用指南（仅在 memory 提供时）
技能提示词：技能位置 + 包含 frontmatter 信息的技能列表 + 使用说明（仅在提供技能时）
虚拟文件系统提示词（文件系统 + 执行工具文档，如适用）
子智能体提示词：任务工具使用说明
用户提供的中间件提示词（如果提供了自定义中间件）
人工介入提示词（当 interrupt_on 设置时）

运行时上下文

运行时上下文是调用智能体时传递的每次运行配置。它不会自动包含在模型提示词中；只有当工具、中间件或其他逻辑读取它并将其添加到消息或系统提示词时，模型才会看到它。使用运行时上下文来存储用户元数据（ID、偏好设置、角色）、API 密钥、数据库连接、功能标志或其他工具和测试框架所需的值。

使用 context_schema定义该数据的结构：使用 dataclasses.dataclass or typing.TypedDict 类。使用 **context** 参数传递给 invoke / ainvoke。请参阅运行时和 LangGraph 运行时上下文了解更多详情。

在工具内部，从注入的 ToolRuntime 读取上下文：

from dataclasses import dataclass

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

@dataclass
class Context:
    user_id: str
    api_key: str

@tool
def fetch_user_data(query: str, runtime: ToolRuntime[Context]) -> str:
    """Fetch data for the current user."""
    user_id = runtime.context.user_id
    return f"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    tools=[fetch_user_data],
    context_schema=Context,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Get my recent activity"}]},
    context=Context(user_id="user-123", api_key="sk-..."),
)

运行时上下文 **会传播到所有子智能体**。当子智能体运行时，它会接收与父智能体相同的运行时上下文。请参阅子智能体了解每个子智能体的上下文（命名空间键）。

自定义状态 schema

当数据必须是智能体可变图状态的一部分时使用，需要与线程一起进行 checkpoint，或者可通过 state_schema 使用 runtime.state访问。对于不可变的每次运行输入（如用户 ID、凭据或功能标志），优先使用运行时上下文.

自定义状态模式必须继承 DeepAgentState。这保留了内置 DeltaChannel reducer on messages，这使得检查点的增长与对话长度的增长保持线性关系。

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


class ResearchState(DeepAgentState):
    page_url: str
    file_urls: list[str]


@tool
def cite_page(runtime: ToolRuntime) -> str:
    """Return the current page URL."""
    return runtime.state["page_url"]


agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[cite_page],
    state_schema=ResearchState,
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Cite the current page"}],
        "page_url": "https://example.com/report",
        "file_urls": [],
    }
)

该模式与中间件贡献的状态模式合并。传递给 subagents= 的声明式 SubAgent 规范会继承父级 state_schema ，当 Deep Agents 为 task 工具编译它们时。CompiledSubAgent 可运行对象和远程 AsyncSubAgent 规范不继承它，因为它们的图已经被单独编译或托管。如果这些图需要相同的状态字段，请使用兼容的模式编译它们。

上下文压缩

每个 create_deep_agent 调用包含内置的上下文压缩。您不需要添加中间件来使卸载或摘要功能正常工作。

长时间运行的任务会产生大量工具输出和冗长的对话历史记录。上下文压缩会减少代理工作内存中的信息大小，同时保留与任务相关的细节。以下技术是内置机制，用于确保传递给 LLM 的上下文保持在上下文窗口限制内：

Offloading

大型工具输入和结果被存储在文件系统中，并被替换为引用。

Summarization

当接近限制时，旧消息会被压缩成 LLM 生成的摘要。

卸载

Deep Agents 使用内置文件系统工具来自动卸载内容，并根据需要搜索和检索已卸载的内容。当工具调用输入或结果超过令牌阈值（默认 20,000）时，会发生内容卸载：

1. **工具调用输入超过 20,000 个令牌**：文件写入和编辑操作会留下包含完整文件内容的工具调用，保留在代理的对话历史中。由于此内容已持久化到文件系统，因此通常冗余。当会话上下文超过模型可用窗口的 85% 时，深度代理会截断较旧的工具调用，用指向磁盘上文件的指针替换它们，从而减少活动上下文的大小。

!一个卸载示例，展示了一个被保存到磁盘的大输入，以及用于工具调用的截断版本

**工具调用结果超过 20,000 个令牌**：当发生这种情况时，深度代理会将响应卸载到配置的后端，并将其替换为文件路径引用和前 10 行的预览。然后代理可以根据需要重新读取或搜索内容。

!一个卸载示例，展示了一个被替换为关于卸载结果位置消息和结果前 10 行的大型工具响应

摘要

每个 create_deep_agent 调用包含 SummarizationMiddleware 在默认中间件堆栈中当上下文大小超过模型的上下文窗口限制时（例如85%时 max_input_tokens），且没有更多可卸载的上下文时，深度智能体会自动对消息历史进行摘要。

此过程包含两个部分：

上下文内摘要：LLM会生成对话的结构化摘要，包括会话意图、创建的产物和下一步操作——这会替换智能体工作内存中的完整对话历史。
文件系统保存：原始对话消息的文本呈现会被写入文件系统作为规范记录。

这种双重方法确保智能体通过摘要保持对其目标和进度的认识，同时保留在需要时恢复文本细节的能力（通过文件系统搜索）。

!展示智能体对话历史的摘要示例，其中多个步骤被压缩

Configuration: - 在模型的85%时触发 max_input_tokens 从其模型配置文件中 - 将10%的token作为近期上下文保留 - Falls back to 170,000-token trigger / 6 messages kept if model profile is unavailable - 如果任何模型调用引发标准的 ContextOverflowError，深度智能体会立即回退到摘要模式，并使用摘要+最近保留的消息进行重试 - 旧消息由模型进行摘要

建议

流式token 来自智能体的流式token通常包括摘要步骤生成的token。您可以使用关联的元数据过滤掉这些token：

for chunk in agent.stream(
    {"messages": [...]},
    stream_mode="messages",
    version="v2",
):
    token, metadata = chunk["data"]
    if metadata.get("lc_source") == "summarization":  # [!code highlight]
        continue
    else:
        ...

按需压缩工具

默认情况下，当达到上下文阈值时，自动摘要会运行。另外，您可以给智能体一个 compact_conversation 工具，以便它可以在需要时触发压缩，例如在任务之间，而不是等待达到85%的阈值。

通过传递 create_summarization_tool_middleware 使用 middleware 参数在 create_deep_agent上启用该工具。自定义中间件被插入到默认堆栈中，在 PatchToolCallsMiddleware:

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import (
    create_summarization_tool_middleware,
)

backend = StateBackend  # if using default backend

model = "google_genai:gemini-3.5-flash"
agent = create_deep_agent(
    model=model,
    middleware=[  # [!code highlight]
        create_summarization_tool_middleware(model, backend),  # [!code highlight]
    ],  # [!code highlight]
)

之后。添加压缩工具不会禁用模型上下文限制85%时的自动摘要。两者共享相同的摘要引擎和状态。

参见 SummarizationToolMiddleware 和 create_summarization_tool_middleware 在API参考中了解详情。

使用子智能体进行上下文隔离

子智能体解决了 **上下文膨胀问题**。当主智能体使用具有大量输出的工具（网络搜索、文件读取、数据库查询）时，上下文窗口会迅速填满。子智能体会隔离这项工作——主智能体只接收最终结果，而不是生成它的数十个工具调用。您也可以单独配置每个子智能体（例如模型、工具、系统提示词和技能）。

工作原理：

- 主智能体有一个 task 用于委托工作的工具
- 子智能体使用自己的全新上下文运行
- 子代理自主执行直至完成
- 子代理向主代理返回单一最终报告
- 主代理的上下文保持干净

最佳实践：

**委托复杂任务**：对于会使主代理上下文变得混乱的多步骤工作，使用子代理。
**保持子代理响应简洁**：指示子代理返回摘要而非原始数据：

    research_subagent = {
        "name": "researcher",
        "description": "Conducts research on a topic",
        "system_prompt": """You are a research assistant.
        IMPORTANT: Return only the essential summary (under 500 words).
        Do NOT include raw search results or detailed tool outputs.""",
        "tools": [web_search],
    }

**对大数据使用文件系统**：子代理可以将结果写入文件；主代理按需读取。

参见子代理获取配置和上下文管理获取运行时上下文传播和每个子代理的命名空间。

长期记忆

使用默认文件系统时，深度代理将其工作内存文件存储在代理状态中，仅在单个线程内持久化。长期记忆使深度代理能够跨不同线程和对话持久化信息。深度代理可以使用长期记忆来存储用户偏好、累积知识、研究进度，或任何应超越单个会话持久化的信息。

要使用长期记忆，您必须使用一个 CompositeBackend 将特定路径（通常为 /memories/）路由到 LangGraph Store，提供跨线程的持久化存储。该 CompositeBackend 是一种混合存储系统，其中一些文件无限期持久化，而其他文件仅限单个线程范围。

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

def make_backend(runtime):
    return CompositeBackend(
        default=StateBackend(runtime),
        routes={"/memories/": StoreBackend(runtime)},
    )

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    store=InMemoryStore(),
    backend=make_backend,
    system_prompt="""When users tell you their preferences, save them to
    /memories/user_preferences.txt so you remember them in future conversations.""",
)

您无需预先填充 /memories/ 文件。您提供后端配置、存储和系统提示指令，告诉代理 *保存什么* 和 *保存在哪里*. 例如，您可以提示代理将偏好设置存储在 /memories/preferences.txt. 该路径初始为空，代理使用其文件系统工具（write_file, edit_file）按需创建文件，当用户分享值得记住的信息时。

要预置记忆，请使用 Store API 在 LangSmith 上部署时。参见长期记忆获取设置和用例信息。

最佳实践

**从正确的输入上下文开始** ——对始终相关的约定保持最小记忆；使用专注技能获取特定任务的能力。
**利用子代理处理重活** ——委托多步骤、输出繁重的任务以保持主代理上下文整洁。
**在配置中调整子代理输出** ——如果您在调试时注意到子代理生成了长输出，可以向子代理的 system_prompt 添加指导以创建摘要和综合发现。
**使用文件系统** – 将大输出持久化到文件（例如子代理写入或自动卸载），使活动上下文保持较小；当需要详情时，模型可以拉取片段 read_file 和 grep 当需要详情时。
**记录长期记忆结构** – 告诉代理什么内容存储在 /memories/ 以及如何使用它。
**为工具传递运行时上下文** – 使用 context 传递用户元数据、API 密钥和工具所需的其他静态配置。

上下文类型

输入上下文

System prompt

Memory

Skills

Tool prompts

系统提示

记忆

技能

工具提示词

完整系统提示词

运行时上下文

自定义状态 schema

上下文压缩

Offloading

Summarization

卸载

摘要

按需压缩工具

使用子智能体进行上下文隔离

长期记忆

最佳实践

相关资源