跳到主要内容

文档索引

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

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

上下文工程是指以正确的格式提供正确的信息和工具，以便您的 Deep Agent 能够可靠地完成任务。 Deep Agent 可以访问多种类型的上下文。有些来源在代理启动时提供；另一些则在运行时可用，例如用户输入。Deep Agent 包含用于在长时间运行的会话中管理上下文的内置机制。 本页面概述了您的 Deep Agent 可以访问和管理的各种上下文。
不熟悉上下文工程？请参阅概念概述，了解不同类型的上下文及其使用时机。

​
上下文类型

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

​
输入上下文

输入上下文是在 Deep Agent 启动时提供的信息，它成为其系统提示的一部分。最终提示由多个来源组成

系统提示

您提供的自定义指令以及内置的代理指导。

内存

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

技能

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

工具提示

使用内置工具或自定义工具的说明。

​
系统提示

您的自定义系统提示会预置在内置系统提示之前，后者包含规划、文件系统工具和子代理的指导。使用它来定义代理的角色、行为和知识 
import { createDeepAgent } from "deepagents";

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.1-pro-preview",
  systemPrompt: `You are a research assistant specializing in scientific literature.
  Always cite sources. Use subagents for parallel research on different topics.`,
});
systemPrompt 参数是静态的，这意味着它不会随每次调用而改变。对于某些用例，您可能需要一个动态提示：例如，告知模型“您拥有管理员权限”与“您拥有只读权限”，或者从长期记忆中注入用户偏好，如“用户偏好简洁的回复”。如果您的提示依赖于上下文或 runtime.store，请使用 dynamicSystemPromptMiddleware 来构建上下文感知的指令。您的中间件可以读取 request.runtime.context 和 request.runtime.store。有关添加自定义中间件和示例，请参阅自定义和LangChain 上下文工程指南。 当工具单独使用上下文或 runtime.store 时，您不需要中间件；工具会直接接收 runtime 对象（包括 runtime.context 和 runtime.store）。仅当系统提示本身必须因每个请求而异时才添加中间件。
要为特定的提供商或模型调整组装后的系统提示，请使用Harness 配置：base_system_prompt 会完全替换基础提示，而 system_prompt_suffix 则会将其附加到基础提示之后。

​
内存

内存文件 (AGENTS.md) 提供持久上下文，这些上下文始终会加载到系统提示中。使用内存来存储项目约定、用户偏好和应适用于每个对话的关键指南 
const agent = await createDeepAgent({
  model: "google_genai:gemini-3.1-pro-preview",
  memory: ["/project/AGENTS.md", "~/.deepagents/preferences.md"],
});
与技能不同，内存总是被注入的——没有渐进式披露。尽量减少内存使用以避免上下文过载；对于详细的工作流程和特定领域的内容，请使用技能。有关配置详情，请参阅内存。

​
技能

技能提供按需能力。代理在启动时从每个 SKILL.md 文件中读取前置信息，然后仅当它确定技能相关时才加载完整的技能内容。这减少了 token 的使用，同时仍提供专业化的工作流程 
const agent = await createDeepAgent({
  model: "google_genai:gemini-3.1-pro-preview",
  skills: ["/skills/research/", "/skills/web-search/"],
});
每个技能应专注于单一工作流程或领域；宽泛或重叠的技能在加载时会稀释相关性并使上下文膨胀。在技能内部，保持主要内容简洁，并将详细的参考资料移动到单独的文件中，并在技能文件中引用这些文件。将始终相关的约定放入内存中。有关编写和配置，请参阅技能。

​
工具提示

工具提示是指导模型如何使用工具的指令。所有工具都暴露了模型在其提示中看到的元数据——通常是 schema 和描述。您通过 tools 参数传递的工具会将该工具元数据（schema 和描述）呈现在模型面前。Deep Agent 的内置工具打包在中间件中，通常还会更新系统提示，为这些工具提供更多指导。 内置工具 – 添加 Harness 功能（规划、文件系统、子代理）的中间件会自动将特定于工具的指令附加到系统提示中，创建工具提示以解释如何有效地使用这些工具：
  • 规划提示 – write_todos 的指令，用于维护结构化的任务列表
  • 文件系统提示 – ls、read_file、write_file、edit_file、glob、grep（以及使用沙盒后端时的 execute）的文档
  • 子代理提示 – 使用 task 工具委派工作的指南
  • 人工干预提示 – 在指定的工具调用处暂停的用法（当设置 interrupt_on 时）
  • 本地上下文提示 – 当前目录和项目信息（仅限 CLI）
您提供的工具 – 通过 tools 参数传递的工具会将其描述（来自工具 schema）发送给模型。您还可以添加自定义中间件，该中间件会添加工具并附加自己的系统提示指令。 对于您提供的工具，请务必提供清晰的名称、描述和参数描述。这些指导模型何时以及如何使用工具的推理。在描述中包含何时使用该工具，并描述每个参数的作用。
const searchOrders = tool(
  async ({ userId, status, limit }) => { /* ... */ },
  {
    name: "search_orders",
    description: `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.`,
    schema: z.object({
      userId: z.string().describe("Unique identifier for the user"),
      status: z.enum(["pending", "shipped", "delivered"]).describe("Order status to filter by"),
      limit: z.number().default(10).describe("Maximum number of results to return"),
    }),
  }
);
要为特定的提供商或模型覆盖内置或用户提供的工具描述，请使用Harness 配置中以工具名称为键的 tool_description_overrides。excluded_tools 会将某个工具从可见工具集中完全移除。
有关内置功能，请参阅Harness；有关直接传递工具，请参阅自定义。

​
完整系统提示

Deep Agent 的系统消息（即模型在运行开始时收到的组合系统提示）由以下部分组成
  1. 自定义 system_prompt（如果提供）
  2. 基础代理提示
  3. 待办事项列表提示：关于如何使用待办事项列表进行规划的说明
  4. 内存提示：AGENTS.md + 内存使用指南（仅当提供了 memory 时）
  5. 技能提示：技能位置 + 包含前置信息和用法的技能列表（仅当提供了技能时）
  6. 虚拟文件系统提示（文件系统 + 执行工具文档，如果适用）
  7. 子代理提示：任务工具用法
  8. 用户提供的中间件提示（如果提供了自定义中间件）
  9. 人工干预提示（当设置 interrupt_on 时）

​
运行时上下文

运行时上下文是您在调用代理时传递的每次运行的配置。它不会自动包含在模型提示中；只有当工具、中间件或其他逻辑读取它并将其添加到消息或系统提示中时，模型才会看到它。运行时上下文可用于用户元数据（ID、偏好、角色）、API 密钥、数据库连接、功能标志或您的工具和 Harness 所需的其他值。 使用 contextSchema 定义该数据的形状，通常是一个 Zod 对象 schema（例如 z.object({ ... })）。将运行时值作为选项对象中 context 字段的一部分传递给 invoke / ainvoke。有关完整详细信息，请参阅运行时和LangGraph 运行时上下文。 在工具内部，从作为工具处理程序的 runtime 参数提供的 ToolRuntime 实例中读取 runtime.context：
import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  apiKey: z.string(),
});

const fetchUserData = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const userId = runtime.context?.userId;
    return `Data for user ${userId}: ${input.query}`;
  },
  {
    name: "fetch_user_data",
    description: "Fetch data for the current user",
    schema: z.object({ query: z.string() }),
  }
);

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.1-pro-preview",
  tools: [fetchUserData],
  contextSchema,
});

const result = await agent.invoke(
  { messages: [{ role: "user", content: "Get my recent activity" }] },
  { context: { userId: "user-123", apiKey: "sk-..." } },
);
运行时上下文会传播到所有子代理。当子代理运行时，它会收到与父代理相同的运行时上下文。有关每个子代理上下文（命名空间键）的信息，请参阅子代理。

​
上下文压缩

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

卸载

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

总结

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

​
卸载

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

​
总结

当前的摘要行为（通过 wrapModelCall 进行模型内摘要、精确的 token 计数和自动的 ContextOverflowError 回退）要求 deepagents>=1.6.0。
当上下文大小超过模型的上下文窗口限制（例如 max_input_tokens 的 85%），并且没有更多上下文符合卸载条件时，Deep Agent 会对消息历史进行摘要。 此过程包含两个组成部分：
  • 上下文内摘要：LLM 生成对话的结构化摘要，包括会话意图、创建的工件和后续步骤——这会替换代理工作内存中的完整对话历史。
  • 文件系统保留：完整、原始的对话消息作为规范记录写入文件系统。
这种双重方法确保代理通过摘要保持对其目标和进度的认识，同时在需要时（通过文件系统搜索）保留恢复特定细节的能力。 一个摘要示例，展示了代理的对话历史，其中几个步骤被压缩 配置：
  • 在模型模型配置中 max_input_tokens 的 85% 处触发
  • 保留 10% 的 token 作为近期上下文
  • 如果模型配置不可用，则回退到 170,000-token 触发 / 保留 6 条消息
  • 如果任何模型调用引发标准ContextOverflowError，Deep Agent 会立即回退到摘要，并使用摘要 + 近期保留的消息进行重试
  • 旧消息由模型进行摘要
从代理流式传输的 token 通常会包含摘要步骤生成的 token。您可以使用其关联的元数据来过滤掉这些 token
for await (const [namespace, chunk] of await agent.stream(
  { messages: [...] },
  { streamMode: "messages" },
)) {
  const [message, metadata] = chunk;
  if (metadata?.lcSource === "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. 保持子代理响应简洁：指示子代理返回摘要，而不是原始数据 
    const researchSubagent = {
name: "researcher",
description: "Conducts research on a topic",
systemPrompt: `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: [webSearch],
};
  3. 对大型数据使用文件系统：子代理可以将结果写入文件；主代理读取其所需的内容。
有关配置，请参阅子代理；有关运行时上下文传播和每个子代理的命名空间管理，请参阅上下文管理。

​
长期记忆

当使用默认文件系统时，您的 Deep Agent 会将其工作内存文件存储在代理状态中，该状态仅在单个线程内持久存在。长期记忆使您的 Deep Agent 能够在不同线程和对话之间持久保存信息。Deep Agent 可以使用长期记忆来存储用户偏好、累积知识、研究进度或任何应在单个会话之外持久存在的信息。 要使用长期记忆，您必须使用一个 CompositeBackend，它将特定路径（通常是 /memories/）路由到 LangGraph Store，后者提供持久的跨线程持久性。CompositeBackend 是一个混合存储系统，其中一些文件无限期持久存在，而另一些文件则仅限于单个线程。
import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph-checkpoint";

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.1-pro-preview",
  store: new InMemoryStore(),
  backend: new CompositeBackend(
    new StateBackend(),
    { "/memories/": new StoreBackend() },
  ),
  systemPrompt: `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.