Deep Agents 中的上下文工程

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

初次接触上下文工程？请参阅概念概述，了解不同类型的上下文及其使用时机。

上下文类型

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

输入上下文

输入上下文是在深度代理启动时提供给它的信息，这些信息成为其系统提示词的一部分。最终的提示词由多个来源组成：

系统提示

你提供的自定义指令加上内置的代理指导。

记忆

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

技能

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

工具提示

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

系统提示

你的自定义系统提示会附加到内置系统提示之前，内置系统提示包括规划、文件系统工具和子代理的指导。使用它来定义代理的角色、行为和知识：

import { createDeepAgent } from "deepagents";

const agent = await createDeepAgent({
  model: "claude-sonnet-4-6",
  systemPrompt: `你是一位专门研究科学文献的研究助理。
  始终引用来源。对不同主题的研究使用子代理进行并行处理。`,
});

systemPrompt 参数是静态的，这意味着它不会随每次调用而改变。对于某些用例，你可能需要一个动态提示：例如，告诉模型“你拥有管理员访问权限”与“你拥有只读访问权限”，或者从长期记忆中注入用户偏好，如“用户偏好简洁的回复”。如果你的提示依赖于上下文或 runtime.store，请使用 dynamicSystemPromptMiddleware 来构建上下文感知的指令。你的中间件可以读取 request.runtime.context 和 request.runtime.store。有关添加自定义中间件的详细信息，请参阅自定义，以及LangChain 上下文工程指南中的示例。当仅工具使用上下文或 runtime.store 时，你不需要中间件；工具直接接收 runtime 对象（包括 runtime.context 和 runtime.store）。仅当系统提示本身必须随每次请求变化时，才添加中间件。

记忆

记忆文件（AGENTS.md）提供持久化的上下文，这些上下文始终加载到系统提示中。使用记忆来存储项目约定、用户偏好和应适用于每次对话的关键指南：

const agent = await createDeepAgent({
  model: "claude-sonnet-4-6",
  memory: ["/project/AGENTS.md", "~/.deepagents/preferences.md"],
});

与技能不同，记忆总是被注入——没有渐进式披露。保持记忆最小化以避免上下文过载；对于详细的工作流程和特定领域的内容，请使用技能。有关配置详情，请参阅记忆。

技能

技能提供按需能力。代理在启动时从每个 SKILL.md 读取 frontmatter，然后仅在确定技能相关时加载完整的技能内容。这减少了令牌使用量，同时仍提供专业化的工作流程：

const agent = await createDeepAgent({
  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 参数传递的工具会将其描述（来自工具模式）发送给模型。你还可以添加自定义中间件，该中间件添加工具并附加其自己的系统提示指令。对于你提供的工具，请确保提供清晰的名称、描述和参数描述。这些指导模型关于何时以及如何使用该工具的推理。在描述中包含何时使用该工具，并描述每个参数的作用。

const searchOrders = tool(
  async ({ userId, status, limit }) => { /* ... */ },
  {
    name: "search_orders",
    description: `按状态搜索用户订单。

当用户询问订单历史或想要检查订单状态时使用此工具。始终按提供的状态过滤。`,
    schema: z.object({
      userId: z.string().describe("用户的唯一标识符"),
      status: z.enum(["pending", "shipped", "delivered"]).describe("用于过滤的订单状态"),
      limit: z.number().default(10).describe("要返回的最大结果数"),
    }),
  }
);

有关内置功能，请参阅框架；有关直接传递工具，请参阅自定义。

完整的系统提示

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

自定义 system_prompt（如果提供）
基础代理提示
待办事项列表提示：如何规划待办事项的指令
记忆提示：AGENTS.md + 记忆使用指南（仅在提供 memory 时）
技能提示：技能位置 + 带有 frontmatter 信息的技能列表 + 用法（仅在提供技能时）
虚拟文件系统提示（文件系统 + 如果适用，执行工具文档）
子代理提示：任务工具用法
用户提供的中间件提示（如果提供自定义中间件）
人在回路提示（当设置 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 `用户 ${userId} 的数据：${input.query}`;
  },
  {
    name: "fetch_user_data",
    description: "获取当前用户的数据",
    schema: z.object({ query: z.string() }),
  }
);

const agent = await createDeepAgent({
  model: "claude-sonnet-4-6",
  tools: [fetchUserData],
  contextSchema,
});

const result = await agent.invoke(
  { messages: [{ role: "user", content: "获取我最近的活动" }] },
  { context: { userId: "user-123", apiKey: "sk-..." } },
);

运行时上下文传播到所有子代理。当子代理运行时，它接收与父代理相同的运行时上下文。有关每个子代理的上下文（命名空间键），请参阅子代理。

上下文压缩

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

卸载

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

摘要

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

卸载

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

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

摘要

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

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

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

配置：

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

使用子代理进行上下文隔离

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

主代理有一个 task 工具来委托工作
子代理以其自己的全新上下文运行
子代理自主执行直到完成
子代理向主代理返回单个最终报告
主代理的上下文保持清洁

最佳实践：

委托复杂任务：对于会使主代理上下文混乱的多步骤工作，使用子代理。

保持子代理响应简洁：指示子代理返回摘要，而不是原始数据：

const researchSubagent = {
name: "researcher",
description: "对某个主题进行研究",
systemPrompt: `你是一位研究助理。
重要：仅返回必要的摘要（500 字以内）。
不要包含原始搜索结果或详细的工具输出。`,
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: "claude-sonnet-4-6",
  store: new InMemoryStore(),
  backend: (config) => new CompositeBackend(
    new StateBackend(config),
    { "/memories/": new StoreBackend(config) },
  ),
  systemPrompt: `当用户告诉你他们的偏好时，将其保存到 /memories/user_preferences.txt，以便你在未来的对话中记住它们。`,
});

你不需要用文件预填充 /memories/。你提供后端配置、存储和系统提示指令，告诉代理保存什么以及保存到哪里。例如，你可以提示代理将偏好存储在 /memories/preferences.txt 中。该路径开始时为空，当用户分享值得记住的信息时，代理使用其文件系统工具（write_file、edit_file）按需创建文件。要预填充记忆，请在 LangSmith 上部署时使用Store API。有关设置和用例，请参阅长期记忆。

最佳实践

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

Get started

Deployment

Core capabilities

Frontend

Protocols

Deep Agents CLI

上下文类型

输入上下文

系统提示

记忆

技能

工具提示

系统提示

记忆

技能

工具提示

完整的系统提示

运行时上下文

上下文压缩

卸载

摘要

卸载

摘要

使用子代理进行上下文隔离

长期记忆

最佳实践

相关资源

Get started

Deployment

Core capabilities

Frontend

Protocols

Deep Agents CLI

​上下文类型

​输入上下文

系统提示

记忆

技能

工具提示

​系统提示

​记忆

​技能

​工具提示

​完整的系统提示

​运行时上下文

​上下文压缩

卸载

摘要

​卸载

​摘要

​使用子代理进行上下文隔离

​长期记忆

​最佳实践

​相关资源

上下文类型

输入上下文

系统提示

记忆

技能

工具提示

完整的系统提示

运行时上下文

上下文压缩

卸载

摘要

使用子代理进行上下文隔离

长期记忆

最佳实践

相关资源