深度智能体中的上下文工程

上下文工程是以正确的格式提供正确的信息和工具，使你的深度智能体能够可靠地完成任务。深度智能体可以访问多种类型的上下文。一些来源在启动时提供给智能体；其他的在运行时变得可用，例如用户输入。深度智能体包含内置机制来管理长时间运行会话中的上下文。本页面概述了你的深度智能体可以访问和管理的不同类型的上下文。

上下文工程新手？请参阅概念概述了解不同类型的上下文及其使用场景。

上下文类型

上下文类型	你控制的内容	范围
输入上下文	智能体启动时提示中包含的内容（系统提示、记忆、技能）	静态，每次运行时应用
运行时上下文	调用时传入的静态配置（用户元数据、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）。仅当系统提示本身必须在每个请求中变化时才添加中间件。

要为特定提供商或模型调整已组装的系统提示，请使用框架配置文件：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 的 frontmatter，然后仅在确定技能相关时加载完整的技能内容。这在提供专业工作流的同时减少了 Token 使用：

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.1-pro-preview",
  skills: ["/skills/research/", "/skills/web-search/"],
});

保持每个技能聚焦于单一工作流或领域；范围广泛或重叠的技能会稀释相关性并在加载时膨胀上下文。在技能内部，保持主要内容简洁，将详细的参考材料移动到技能文件中引用的单独文件中。将始终相关的约定放在记忆中。技能编写和配置请参阅技能。

工具提示

工具提示是塑造模型如何使用工具的指令。所有工具暴露模型在提示中看到的元数据——通常是 schema 和描述。你通过 tools 参数传入的工具会将该工具元数据（schema 和描述）呈现给模型。深度智能体的内置工具打包在中间件中，通常也会用更多关于这些工具的指导更新系统提示。 内置工具 – 添加框架能力（规划、文件系统、子智能体）的中间件自动将工具特定指令追加到系统提示中，创建解释如何有效使用这些工具的工具提示：

规划提示 – 使用 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"),
    }),
  }
);

要为特定提供商或模型覆盖内置或用户提供的工具的描述，请使用框架配置文件的 tool_description_overrides（按工具名称键控）。excluded_tools 完全从可见工具集中移除工具。

参阅框架了解内置能力和自定义了解直接传入工具。

完整系统提示

深度智能体的系统消息——模型在运行开始时接收到的已组装系统提示——由以下部分组成：

自定义 system_prompt（如果提供）
基础智能体提示
待办事项提示：如何使用待办事项列表进行规划的指令
记忆提示：AGENTS.md + 记忆使用指南（仅当提供了 memory 时）
技能提示：技能位置 + 带有 frontmatter 信息的技能列表 + 用法（仅当提供了技能时）
虚拟文件系统提示（文件系统 + execute 工具文档（如适用））
子智能体提示：Task 工具用法
用户提供的中间件提示（如果提供了自定义中间件）
人机协作提示（当设置了 interrupt_on 时）

运行时上下文

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

卸载

深度智能体使用内置文件系统工具自动卸载内容，并根据需要搜索和检索卸载的内容。当工具调用输入或结果超过 Token 阈值（默认 20,000）时触发内容卸载：

工具调用输入超过 20,000 Token：文件写入和编辑操作会在智能体的对话历史中留下包含完整文件内容的工具调用。由于此内容已持久化到文件系统，因此通常是冗余的。当会话上下文超过模型可用窗口的 85% 时，深度智能体会截断较早的工具调用，用磁盘上文件的指针替换它们，并减小活跃上下文的大小。
工具调用结果超过 20,000 Token：发生时，深度智能体将响应卸载到配置的后端，并用文件路径引用和前 10 行的预览替换它。智能体随后可以根据需要重新读取或搜索内容。

摘要

当前的摘要行为（通过 wrapModelCall 进行的模型内摘要、精确 Token 计数和自动 ContextOverflowError 回退）需要 deepagents>=1.6.0。

当上下文大小超过模型的上下文窗口限制（例如 max_input_tokens 的 85%），且没有更多符合卸载条件的上下文时，深度智能体会对消息历史进行摘要。此过程有两个组成部分：

上下文内摘要：LLM 生成对话的结构化摘要，包括会话意图、创建的工件和后续步骤——这将替换智能体工作记忆中的完整对话历史。
文件系统保存：完整的原始对话消息作为规范记录写入文件系统。

这种双重方法确保智能体保持对其目标和进度的感知（通过摘要），同时保留在需要时恢复特定细节的能力（通过文件系统搜索）。

配置：

在模型模型配置文件的 max_input_tokens 的 85% 处触发
保留 10% 的 Token 作为最近上下文
如果模型配置文件不可用，回退到 170,000 Token 触发 / 保留 6 条消息
如果任何模型调用引发标准 ContextOverflowError，深度智能体立即回退到摘要并使用摘要 + 最近保留的消息重试
较早的消息由模型进行摘要

从智能体流式输出 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 {
    ...
  }
}

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

子智能体解决了上下文膨胀问题。当主智能体使用产生大量输出的工具（网络搜索、文件读取、数据库查询）时，上下文窗口很快就会被填满。子智能体隔离这项工作——主智能体只接收最终结果，而不是产生它的数十个工具调用。你还可以将每个子智能体与主智能体分开配置（例如模型、工具、系统提示和技能）。 工作原理：

主智能体有一个 task 工具来委派工作
子智能体使用自己的全新上下文运行
子智能体自主执行直到完成
子智能体向主智能体返回单个最终报告
主智能体的上下文保持清洁

最佳实践：

委派复杂任务：对会干扰主智能体上下文的多步骤工作使用子智能体。

保持子智能体响应简洁：指示子智能体返回摘要而非原始数据：

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],
};

使用文件系统处理大数据：子智能体可以将结果写入文件；主智能体按需读取。

参阅子智能体了解配置和上下文管理了解运行时上下文传播和每个子智能体的命名空间。

长期记忆

使用默认文件系统时，你的深度智能体将其工作记忆文件存储在智能体状态中，只在单个线程内持久化。长期记忆使你的深度智能体能够跨不同线程和对话持久化信息。深度智能体可以使用长期记忆来存储用户偏好、积累的知识、研究进度，或任何应超越单个会话持久化的信息。要使用长期记忆，你必须使用 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。设置和用例请参阅长期记忆。

最佳实践

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

Documentation Index

​上下文类型

​输入上下文

系统提示

记忆

技能

工具提示

​系统提示

​记忆

​技能

​工具提示

​完整系统提示

​运行时上下文

​上下文压缩

卸载

摘要

​卸载

​摘要

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

​长期记忆

​最佳实践

​相关资源

上下文类型

输入上下文

系统提示

记忆

技能

工具提示

完整系统提示

运行时上下文

上下文压缩

卸载

摘要

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

长期记忆

最佳实践

相关资源