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

​
上下文类型

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

​
输入上下文

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

系统提示

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

记忆

配置时始终加载的持久 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）。仅当系统提示本身必须随请求变化时才添加中间件。

​
记忆

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

​
技能

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

​
工具提示

工具提示是塑造模型使用工具方式的指令。所有工具都暴露模型在其提示中看到的元数据——通常是模式和描述。通过 tools 参数传递的工具会将该工具元数据（模式和描述）呈现给模型。深度智能体内置工具打包在中间件中，通常也会使用更多工具指导更新系统提示。 内置工具 – 添加辅助功能（规划、文件系统、子智能体）的中间件会自动将特定于工具的指令附加到系统提示，创建解释如何有效使用这些工具的工具提示：
  • 规划提示 – 用于 write_todos 以维护结构化任务列表的指令
  • 文件系统提示 – ls、read_file、write_file、edit_file、glob、grep（以及使用沙箱后端时的 execute）的文档
  • 子智能体提示 – 使用 task 工具委派工作的指导
  • 人在环路提示 – 在指定工具调用时暂停的用法（当 interrupt_on 设置时）
  • 本地上下文提示 – 当前目录和项目信息（仅限 CLI）
您提供的工具 – 通过 tools 参数传递的工具会将其描述（来自工具模式）发送给模型。您还可以添加自定义中间件来添加工具并附加其自己的系统提示指令。 对于您提供的工具，请确保提供清晰的名称、描述和参数描述。这些指导模型关于何时以及如何使用工具的推理。在描述中包含何时使用工具，并描述每个参数的作用。 
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"),
    }),
  }
);
有关内置功能，请参阅辅助；有关直接传递工具，请参阅自定义。

​
完整系统提示

深度智能体的系统消息——在运行开始时模型接收的组装系统提示——由以下部分组成：
  1. 自定义 system_prompt（如果提供）
  2. 基础智能体提示
  3. 待办事项列表提示：如何使用待办事项列表进行规划的说明
  4. 记忆提示：AGENTS.md + 记忆使用指南（仅在提供 memory 时）
  5. 技能提示：技能位置 + 带有 frontmatter 信息的技能列表 + 用法（仅在提供技能时）
  6. 虚拟文件系统提示（文件系统 + 适用时的执行工具文档）
  7. 子智能体提示：任务工具用法
  8. 用户提供的中间件提示（如果提供自定义中间件）
  9. 人在环路提示（当 interrupt_on 设置时）

​
运行时上下文

运行时上下文是您在调用智能体时传递的每次运行配置。它不会自动包含在模型提示中；模型仅在工具、中间件或其他逻辑读取它并将其添加到消息或系统提示时才会看到它。使用运行时上下文存储用户元数据（ID、偏好、角色）、API 密钥、数据库连接、功能标志或您的工具和辅助所需的其他值。 使用 contextSchema 定义该数据的形状，通常是一个 Zod 对象模式（例如 z.object({ ... })）。在您传递给 invoke / ainvoke 的选项对象的 context 字段中传递运行时值。有关完整详情，请参阅运行时和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 生成的摘要。

​
卸载

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

​
摘要

当前的摘要行为（通过 wrapModelCall 进行模型内摘要、准确的令牌计数和自动 ContextOverflowError 回退）需要 deepagents>=1.6.0。
当上下文大小超过模型的上下文窗口限制（例如 max_input_tokens 的 85%），并且没有更多上下文可卸载时，深度智能体会摘要消息历史。 此过程有两个组成部分：
  • 上下文内摘要：LLM 生成对话的结构化摘要，包括会话意图、创建的工件和下一步——这将替换智能体工作记忆中的完整对话历史。
  • 文件系统保存：完整的原始对话消息作为规范记录写入文件系统。
这种双重方法确保智能体通过摘要保持对其目标和进度的意识，同时保留在需要时恢复特定细节的能力（通过文件系统搜索）。 摘要示例，显示智能体的对话历史，其中多个步骤被压缩 配置：
  • 在模型 max_input_tokens 的 85% 时触发（来自其模型配置文件）
  • 保留 10% 的令牌作为最近上下文
  • 如果模型配置文件不可用，则回退到 170,000 个令牌触发 / 保留 6 条消息
  • 如果任何模型调用引发标准 ContextOverflowError，深度智能体会立即回退到摘要并使用摘要 + 保留的最近消息重试
  • 较旧的消息由模型摘要
来自智能体的流式令牌通常包括摘要步骤生成的令牌。您可以使用其关联元数据过滤掉这些令牌：
for await (const [namespace, chunk] of await agent.stream(
  { messages: [...] },
  { streamMode: "messages" },
)) {
  const [message, metadata] = chunk;
  if (metadata?.lcSource === "summarization") {
    continue;
  } else {
    ...
  }
}
摘要工具中间件需要 deepagents>=1.6.0。
深度智能体包含一个可选的工具用于摘要，使智能体能够在适当时机（例如任务之间）触发摘要，而不是在固定的令牌间隔。 您可以通过将其附加到中间件列表来启用此工具： 
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=[  // [!code highlight]
        create_summarization_tool_middleware(model, backend),  // [!code highlight]
    ],  // [!code highlight]
)
启用此功能不会禁用在模型上下文限制的 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. 使用文件系统处理大型数据：子智能体可以将结果写入文件；主智能体读取其需要的内容。
有关配置，请参阅子智能体；有关运行时上下文传播和每个子智能体命名空间，请参阅上下文管理。

​
长期记忆

使用默认文件系统时，您的深度智能体会将其工作记忆文件存储在智能体状态中，该状态仅在单个线程内持久存在。 长期记忆使您的深度智能体能够跨不同线程和对话持久保存信息。 深度智能体可以使用长期记忆存储用户偏好、累积知识、研究进度或任何应超出单个会话持久的信息。 要使用长期记忆，您必须使用 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 密钥和工具所需的其他静态配置。

​
相关资源

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