上下文工程以正确的格式提供正确的信息和工具，使您的deep agent能够可靠地完成任务。 Deep agent可以访问多种上下文, 某些上下文信息在启动时提供给智能体，其他则在运行时提供，比如用户输入。 Deep agent包含了用于跨长时间运行会话进行管理上下文的内置机制。 本页简要介绍了您的深deep agent可以访问和管理的不同类型的上下文。
不熟悉上下文工程？请参阅概念概述了解不同类型的上下文以及何时使用它们。

​
上下文类型

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

​
输入上下文

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

系统提示词

您提供的自定义指令加上内置的智能体指南。

记忆

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

技能

按需加载的能力，在相关时加载（渐进式加载）。

工具提示

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

​
系统提示词

您的自定义系统提示词会被添加到内置系统提示词之前，内置提示词一般包括关于任务规划、文件系统工具和子智能体的指南。系统提示词用来定义智能体的角色、行为和知识： 
from deepagents import create_deep_agent

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    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="claude-sonnet-4-6",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)
与技能不同，记忆始终会被注入 —— 没有渐进式加载。保持记忆最小化以避免上下文过载；对于详细的工作流程和领域特定的内容，请使用技能。请参阅记忆了解配置详情。

​
技能

技能提供按需的能力。智能体在启动时从每个 SKILL.md 读取 frontmatter，然后仅在确定技能相关时才加载完整的技能内容。这减少了Token使用，同时仍提供专门的工作流程： 
agent = create_deep_agent(
    model="claude-sonnet-4-6",
    skills=["/skills/research/", "/skills/web-search/"],
)
保持每个技能专注于单一工作流程或领域；广泛或重叠的技能会稀释相关性，并在加载时膨胀上下文。在技能内部，要保持主要内容简洁，将详细的参考材料保存到一个个的单独文件中，并在技能主文件引用这些参考文件。将始终相关的内容放在记忆中。请参阅技能了解创作和配置。

​
工具提示

工具提示是决定模型如何使用工具的指令。所有工具都将其元数据在提示词中向模型暴露 —— 通常是签名模式和描述。通过 tools 参数传递的工具会向模型暴露该工具的元数据（签名模式和描述）。Deep Agents 内置工具打包在中间件中，通常还会在系统提示词中更新有关这些工具的更多的指南信息。 内置工具 – 添加约束框架能力（规划、文件系统、子智能体）的中间件会自动将工具的指令附加到系统提示词，病创建解释如何有效使用这些工具的工具提示：
  • 规划提示 – 关于如何使用 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:
    """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
    """
    # 实现代码
    ...
请参阅约束框架了解内置能力，请参阅自定义了解直接传递工具。

​
完整的系统提示词

Deep agent 的系统消息 —— 模型在运行开始时收到的组合起来的系统提示词 —— 由以下部分组成：
  1. 自定义 system_prompt（如果提供）
  2. 基础智能体提示词
  3. 待办列表提示：关于如何使用待办列表进行规划的指令
  4. 记忆提示词：AGENTS.md + 记忆使用指南（仅在提供 memory 时）
  5. 技能提示词：技能位置 + 带有 frontmatter 信息的技能列表 + 使用方法（仅在提供技能时）
  6. 虚拟文件系统提示词（文件系统 + execute 工具文档，如适用）
  7. 子智能体提示词：任务工具使用
  8. 用户提供的中间件提示词（如果提供了自定义中间件）
  9. 人工中断提示词（当设置 interrupt_on 时）

​
运行时上下文

运行时上下文(Runtime Context)是您每次调用智能体时传递的运行时配置参数，它不会自动包含在模型提示词中；仅在工具、中间件或其他逻辑读取它并将其添加到消息或系统提示词时，模型才会识别到它。运行时上下文信息适用于用户元数据（ID、偏好、角色）、API 密钥、数据库连接、功能标志或您的工具和约束框架需要的其他信息。 通过context_schema来定义数据的结构： 为dataclasses.dataclass 或 typing.TypedDict 类型。并通过 invoke / ainvoke 的 context 参数传递值。请参阅运行时和 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"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    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-..."),
)
运行时上下文会传播到所有子智能体。当子智能体运行时，它接收与父智能体相同的运行时上下文。请参阅子智能体了解每个子智能体的上下文（带命名空间的键）。

​
上下文压缩

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

消息卸载

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

总结

当接近限额时，旧消息被压缩成 LLM 生成的总结。

​
消息卸载

Deep Agents 使用内置文件系统工具自动进行消息卸载，并在需要时搜索和检索这些卸载的内容。 当工具调用输入或结果超过Token阈值（默认 20,000）时就会进行消息卸载：
  1. 工具调用输入超过 20,000 个Token：文件写入和编辑操作在智能体的对话历史中留下了包含完整文件内容的工具调用记录。 由于此内容已持久化到文件系统，它通常是冗余的。 当会话上下文超过模型可用窗口限额的 85% 时，deep agent 会截断较早的工具调用，用指向磁盘上文件的引用替换它们，并减少活动上下文的大小。 卸载示例，显示大型输入被保存到磁盘，截断版本用于工具调用
  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 会立即回退到总结过程，并用已有的总结 + 保留的最近消息进行重试
  • 旧消息由模型总结
总结工具
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 = "openai:gpt-5.4"
agent = create_deep_agent(
    model=model,
    middleware=[
        create_summarization_tool_middleware(model, backend),
    ],
)
启用此功能不会禁用在模型上下文限制 85% 处的默认进行总结摘要操作。 请参阅 SummarizationToolMiddleware API 参考了解详情。

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

子智能体解决了上下文膨胀问题。当主智能体使用具有大量输出的工具（网络搜索、文件读取、数据库查询）时，上下文窗口会迅速填满。子智能体可隔离这项工作 —— 主智能体仅接收最终结果，而不是产生它的数十个工具调用。您还可以抛开主智能体而配置每个子智能体具体内容（例如，模型、工具、系统提示和技能）。 工作原理：
  • 主智能体有 task 工具来委托工作
  • 子智能体使用自己的新上下文运行
  • 子智能体自主执行直到完成
  • 子智能体向主智能体返回单个最终报告
  • 主智能体的上下文保持纯净
最佳实践：
  1. 委托复杂任务：将多步骤工作委托给子智能体，以保持主智能体的上下文干净。
  2. 保持子智能体响应简洁：指示子智能体返回摘要，而不是原始数据： 
    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],
}
  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="claude-sonnet-4-6",
    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）按需创建文件。 要预先填充记忆，在 LangSmith 上部署时使用 Store API。 请参阅长期记忆了解设置和使用场景。

​
最佳实践

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

​
相关资源

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