Skip to main content
上下文工程是指以正确的格式提供正确的信息和工具，以便您的 deep agent 能够可靠地完成任务。 Deep agents 可以访问多种类型的上下文。 某些来源在启动时提供给代理；其他来源在运行时变得可用，例如用户输入。 Deep agents 包含用于管理长时间运行会话上下文的内置机制。 本页概述了您的 deep agent 可访问和管理的不同类型的上下文。
刚接触上下文工程？请参阅 概念概述 了解不同类型的上下文及其使用时机。

​
上下文类型

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

​
输入上下文

输入上下文是在启动时提供给您的 deep agent 的信息，成为其系统提示的一部分。最终提示由几个来源组成：

系统提示

您提供的自定义指令加上内置代理指导。

记忆

配置后始终加载的持久 AGENTS.md 文件。

技能

相关时按需加载的功能（渐进式披露）。

工具提示

使用内置工具或自定义工具的指令。

​
系统提示

您的自定义系统提示会前置到内置系统提示之前，其中包括规划、文件系统工具和子代理的指导。使用它来定义代理的角色、行为和知识： 
from deepagents import create_deep_agent

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    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.1-pro-preview",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)
与技能不同，记忆始终被注入——没有渐进式披露。保持记忆最小化以避免上下文过载；使用 技能 处理详细工作流和特定领域内容。请参阅 记忆 了解配置详情。

​
技能

技能提供按需功能。代理在启动时读取每个 SKILL.md 的 Frontmatter，然后仅在确定技能相关时加载完整技能内容。这减少了 Token 使用量，同时仍提供专门的工作流： 
agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    skills=["/skills/research/", "/skills/web-search/"],
)
保持每个技能专注于单个工作流或领域；广泛或重叠的技能会稀释相关性并在加载时膨胀上下文。在技能内部，保持主要内容简洁，并将详细参考材料移至技能文件中引用的单独文件。将始终相关的约定放在 记忆 中。请参阅 技能 了解编写和配置。

​
工具提示

工具 提示是塑造模型如何使用工具的指令。所有工具都暴露模型在其提示中看到的元数据——通常是架构和描述。您通过 tools 参数传递的工具会将该工具元数据（架构和描述）暴露给模型。Deep Agents 内置工具打包在中间件中，通常还会更新系统提示以提供有关这些工具的更多指导。 内置工具 – 添加 harness 功能（规划、文件系统、子代理）的中间件会自动将特定于工具的指令附加到系统提示，创建解释如何有效使用这些工具的工具提示：
  • 规划提示 – write_todos 维护结构化任务列表的指令
  • 文件系统提示 – ls、read_file、write_file、edit_file、glob、grep 的文档（使用沙箱后端时包括 execute）
  • 子代理提示 – 使用 task 工具委托工作的指导
  • 人机协同提示 – 在指定工具调用时暂停的用法（当设置 interrupt_on 时）
  • 本地上下文提示 – 当前目录和项目信息（仅 CLI）
您提供的工具 – 通过 tools 参数传递的工具会将其描述（来自工具架构）发送给模型。您还可以添加 自定义中间件，添加工具并附加其自己的系统提示指令。 对于您提供的工具，请确保提供清晰的名称、描述和参数描述。这些指导模型关于何时以及如何使用该工具的推理。在描述中包含何时使用该工具，并描述每个参数的作用。 
@tool(parse_docstring=True)
def search_orders(
    user_id: str,
    status: str,
    limit: int = 10
) -> str:
    """按状态搜索用户订单。

    当用户询问订单历史或想要检查
    订单状态时使用此工具。始终按提供的状态过滤。

    Args:
        user_id: 用户的唯一标识符
        status: 订单状态：'pending'、'shipped' 或 'delivered'
        limit: 返回的最大结果数
    """
    # 实现在此处
    ...
请参阅 Harness 了解内置功能，以及 自定义 了解直接传递工具。

​
完整系统提示

deep agent 的系统消息——运行开始时模型接收到的组装系统提示——由以下部分组成：
  1. 自定义 system_prompt（如果提供）
  2. 基础代理提示
  3. 待办列表提示：如何使用待办列表进行规划的指令
  4. 记忆提示：AGENTS.md + 记忆使用指南（仅在提供 memory 时）
  5. 技能提示：技能位置 + 技能列表及 Frontmatter 信息 + 用法（仅在提供技能时）
  6. 虚拟文件系统提示（文件系统 + 执行工具文档，如果适用）
  7. 子代理提示：Task 工具用法
  8. 用户提供的中间件提示（如果提供自定义中间件）
  9. 人机协同提示（当设置 interrupt_on 时）

​
运行时上下文

运行时上下文是您在调用代理时传递的每次运行配置。它不会自动包含在模型提示中；仅当工具、中间件或其他逻辑读取它并将其添加到消息或系统提示时，模型才会看到它。将运行时上下文用于用户元数据（ID、偏好、角色）、API 密钥、数据库连接、功能标志或您的工具和 harness 需要的其他值。 使用 context_schema 定义该数据的形状：使用 dataclasses.dataclass 或 typing.TypedDict 类。使用 context 参数将值传递给 invoke / ainvoke。请参阅 Runtime 和 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:
    """获取当前用户的数据。"""
    user_id = runtime.context.user_id
    return f"用户 {user_id} 的数据：{query}"

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    tools=[fetch_user_data],
    context_schema=Context,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "获取我最近的活动"}]},
    context=Context(user_id="user-123", api_key="sk-..."),
)
运行时上下文传播到所有子代理。当子代理运行时，它接收与父代理相同的运行时上下文。请参阅 子代理 了解每个子代理的上下文（命名空间键）。

​
上下文压缩

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

卸载

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

摘要

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

​
卸载

Deep Agents 使用 内置文件系统工具 自动卸载内容并在需要时搜索和检索该卸载内容。 当工具调用输入或结果超过 Token 阈值（默认 20,000）时发生内容卸载：
  1. 工具调用输入超过 20,000 Token：文件写入和编辑操作会在代理的对话历史中留下包含完整文件内容的工具调用。 由于此内容已持久化到文件系统，它通常是冗余的。 当会话上下文超过模型可用窗口的 85% 时，deep agents 截断较旧的工具调用，用磁盘上文件的指针替换它们，并减少活动上下文的大小。 卸载示例，显示保存到磁盘的大型输入以及用于工具调用的截断版本
  2. 工具调用结果超过 20,000 Token：当发生这种情况时，deep agent 将响应卸载到配置的后端，并用文件路径引用和前 10 行的预览替换它。然后代理可以根据需要重新读取或搜索内容。 卸载示例，显示大型工具响应被替换为关于卸载结果位置的消息以及结果的前 10 行

​
摘要

当上下文大小超过模型的上下文窗口限制（例如 max_input_tokens 的 85%），并且没有更多上下文符合卸载条件时，deep agent 会总结消息历史。 此过程有两个组成部分：
  • 上下文内摘要：LLM 生成对话的结构化摘要，包括会话意图、创建的工件和下一步骤——这将替换代理工作记忆中的完整对话历史。
  • 文件系统保存：完整的原始对话消息作为规范记录写入文件系统。
这种双重方法确保代理保持对其目标和进度的意识（通过摘要），同时保留在需要时恢复特定细节的能力（通过文件系统搜索）。 摘要示例，显示代理的对话历史，其中几个步骤被压缩 配置：
  • 在模型的 max_input_tokens 的 85% 处触发，来自其 模型配置文件
  • 保留 10% 的 Token 作为最近上下文
  • 如果模型配置文件不可用，回退到 170,000 Token 触发 / 保留 6 条消息
  • 如果任何模型调用引发标准 ContextOverflowError，Deep Agents 立即回退到摘要并重试，使用摘要 + 最近保留的消息
  • 较旧的消息由模型总结
来自代理的 流式 Token 通常包括摘要步骤生成的 Token。您可以使用其关联的元数据过滤这些 Token：
for chunk in agent.stream(
    {"messages": [...]},
    stream_mode="messages",
    version="v2",
):
    token, metadata = chunk["data"]
    if metadata.get("lc_source") == "summarization":
        continue
    else:
        ...
Summarization Tool
js
摘要工具中间件需要 deepagents>=1.6.0。
::: Deep Agents 包含一个可选的 工具 用于摘要，使代理能够在合适时机触发摘要——例如在任务之间——而不是在固定的 Token 间隔。 您可以通过将其附加到中间件列表来启用此工具： 
from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import (
    create_summarization_tool_middleware,
)

backend = StateBackend  # 如果使用默认后端

model = "google_genai:gemini-3.1-pro-preview"
agent = create_deep_agent(
    model=model,
    middleware=[
        create_summarization_tool_middleware(model, backend),
    ],
)
启用此功能不会禁用模型上下文限制 85% 处的默认摘要操作。 请参阅 SummarizationToolMiddleware API 参考了解详情。 :::

​
使用子代理进行上下文隔离

子代理解决了上下文膨胀问题。当主代理使用具有大量输出的工具（Web 搜索、文件读取、数据库查询）时，上下文窗口会迅速填满。子代理隔离此工作——主代理仅接收最终结果，而不是产生它的数十个工具调用。您还可以单独配置每个子代理与主代理（例如，模型、工具、系统提示和技能）。 工作原理：
  • 主代理有一个 task 工具来委托工作
  • 子代理使用其自己的全新上下文运行
  • 子代理自主执行直到完成
  • 子代理将单个最终报告返回给主代理
  • 主代理的上下文保持干净
最佳实践：
  1. 委托复杂任务：对会弄乱主代理上下文的多步骤工作使用子代理。
  2. 保持子代理响应简洁：指示子代理返回摘要，而不是原始数据： 
    research_subagent = {
    "name": "researcher",
    "description": "对主题进行研究",
    "system_prompt": """您是一名研究助理。
    重要：仅返回基本摘要（500 字以内）。
    不要包含原始搜索结果或详细的工具输出。""",
    "tools": [web_search],
}
  3. 对大数据使用文件系统：子代理可以将结果写入文件；主代理读取所需内容。
请参阅 子代理 了解配置，以及 上下文管理 了解运行时上下文传播和每个子代理的命名空间。

​
长期记忆

使用默认文件系统时，您的 deep agent 将其工作记忆文件存储在代理状态中，这仅在线程内持久化。 长期记忆使您的 deep agent 能够在不同线程和对话之间持久化信息。 Deep agents 可以使用长期记忆存储用户偏好、累积知识、研究进度或任何应超出单个会话持久化的信息。 要使用长期记忆，您必须使用 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.1-pro-preview",
    store=InMemoryStore(),
    backend=make_backend,
    system_prompt="""当用户告诉您他们的偏好时，将它们保存到
    /memories/user_preferences.txt，以便您在未来的对话中记住它们。""",
)
您不需要用文件预填充 /memories/。 您提供后端配置、存储和系统提示指令，告诉代理保存什么以及在哪里。 例如，您可以提示代理将偏好存储在 /memories/preferences.txt 中。 路径开始为空，当用户分享值得记住的信息时，代理使用其文件系统工具（write_file、edit_file）按需创建文件。 要预种子记忆，在 LangSmith 上部署时使用 Store API。 请参阅 长期记忆 了解设置和用例。

​
最佳实践

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

​
相关资源

在 GitHub 上编辑此页面 或 提交问题。
通过 MCP 将 这些文档 连接到 Claude、VSCode 等以获得实时答案。