跳到主要内容

文档索引

在以下地址获取完整的文档索引：https://docs.langchain.org.cn/llms.txt

在进一步探索之前，请使用此文件发现所有可用页面。

上下文工程是提供正确格式的信息和工具，以便您的 Deep Agent 能够可靠地完成任务。 Deep Agent 可以访问多种类型的上下文。某些来源在启动时提供给智能体；其他来源在运行时可用，例如用户输入。Deep Agent 包含内置机制，用于管理长期运行会话中的上下文。 本页面概述了您的 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）。仅当工具应随系统提示词更新一起打包时，才添加中间件。
要针对特定提供商或模型调整组装后的系统提示词，请使用 harness profile：base_system_prompt 会彻底替换基础提示词，而 system_prompt_suffix 会附加到其后。

​
内存

记忆文件 (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/"],
)
保持每个技能专注于单一的工作流程或领域；广泛或重叠的技能会稀释相关性，并在加载时使上下文膨胀。在技能内部，保持主要内容简洁，并将详细的参考材料移动到技能文件中引用的独立文件中。将始终相关的规范放在记忆中。有关编写和配置，请参阅技能。

​
工具提示词

工具提示词是塑造模型如何使用工具的指令。所有工具都会公开模型在其提示词中看到的元数据——通常是架构 (Schema) 和描述。您通过 tools 参数传递的工具会将该工具的元数据（架构和描述）展现给模型。Deep Agent 的内置工具封装在中间件中，通常还会通过更多针对这些工具的指导来更新系统提示词。 内置工具 – 添加 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:
    """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
    ...
要针对特定提供商或模型覆盖内置或用户提供工具的描述，请使用 harness profile 的 tool_description_overrides（以工具名称为键）。excluded_tools 可以将工具完全从可见工具集中移除。
有关内置功能，请参阅 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 类。通过 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:
    """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.1-pro-preview",
    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 的上下文保持在其上下文窗口限制内的内置机制：

卸载 (Offloading)

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

总结

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

​
卸载 (Offloading)

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

​
总结

当上下文大小超过模型的上下文窗口限制（例如 max_input_tokens 的 85%），且没有更多符合条件的上下文可以卸载时，Deep Agent 会对消息历史记录进行总结。 此过程包含两个组成部分：
  • 上下文内总结 (In-context summary)：LLM 生成对话的结构化总结，包括会话意图、创建的工件和后续步骤，从而替换智能体工作记忆中的完整对话历史记录。
  • 文件系统保存 (Filesystem preservation)：完整的、原始的对话消息作为规范记录被写入文件系统。
这种双重方法确保智能体保持对其目标和进展的认知（通过总结），同时保留了在需要时恢复特定细节的能力（通过文件系统搜索）。 一个总结示例，显示了智能体的对话历史记录，其中几个步骤被压缩了 配置：
  • 在达到其 模型配置文件 中 max_input_tokens 的 85% 时触发
  • 保留 10% 的 Token 作为最近的上下文
  • 如果模型配置文件不可用，则回退到 170,000 Token 触发 / 保留 6 条消息
  • 如果任何模型调用引发标准的 ContextOverflowError，Deep Agent 会立即回退到总结，并使用“总结 + 最近保留的消息”进行重试
  • 较旧的消息由模型进行总结
来自智能体的 流式 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:
        ...
总结工具
js
总结工具中间件需要 deepagents>=1.6.0。
::: Deep Agent 包含一个可选的总结工具，使智能体能够在合适的时机（例如任务之间）触发总结，而不是在固定的 Token 间隔。 您可以通过将其附加到中间件列表来启用此工具：
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.1-pro-preview"
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 Agent 可以使用长期记忆来存储用户偏好、积累的知识、研究进展或任何应持久存在于单个会话之外的信息。 要使用长期记忆，您必须使用 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="""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 密钥以及工具需要的其他静态配置。
将这些文档连接到 Claude、VSCode 等，以获得实时答案。
在 GitHub 上编辑此页 或 提交问题。
© . This site is unofficial and not affiliated with LangChain, Inc.