上下文工程

为什么需要它

你的 agent 是否经常"忘记"重要信息，或者上下文窗口被撑爆？

五种上下文

deep agent 可以访问和管理的五种上下文类型

输入上下文

启动时提供给 agent 的信息，成为系统提示的一部分

最终的系统提示由多个来源组装而成，每个来源有不同的加载策略：

系统提示

定义 agent 的角色、行为和知识的最直接方式

白话：系统提示就是你对 Agent 说的"第一句话"，告诉它你是谁、你要做什么、怎么做。它不会变，每次运行都一样。

systemPrompt 参数是静态的，不会在每次调用时改变。用最简洁的语言告诉 agent 它是谁、应该怎么做：

import { createDeepAgent } from "deepagents";

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  // systemPrompt 是静态的，每次运行都一样，定义 Agent 的角色和行为
  systemPrompt: `You are a research assistant specializing in scientific literature.
  Always cite sources. Use subagents for parallel research on different topics.`,
});

记忆文件

始终加载的持久化上下文——AGENTS.md 文件

记忆文件提供了始终加载到系统提示中的持久化上下文。适合存放每次对话都适用的关键准则：

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  // memory 中的文件在每次对话时始终加载到系统提示中
  // 适合存放项目约定、用户偏好、安全规则等始终需要的信息
  memory: ["/project/AGENTS.md", "~/.deepagents/preferences.md"],
});

技能系统

按需加载的能力——只在相关时才注入上下文

技能是 渐进式披露 的核心。agent 启动时只读每个 SKILL.md 的 frontmatter，判断技能相关时才加载完整内容，大幅减少 token 消耗：

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  // skills 下的内容只在相关时才加载（渐进式披露），不是每次都消耗 token
  // 每个目录下的 SKILL.md 的 frontmatter 会先被读取，判断相关后才加载完整内容
  skills: ["/skills/research/", "/skills/web-search/"],
});

工具提示

塑造模型如何使用工具的指令——名称、描述和参数

所有工具都暴露模型能看到的元数据。清晰的工具描述能让模型更好地判断何时、如何使用工具：

import { tool } from "@langchain/core/tools";
import { z } from "zod";

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 用 zod 定义，每个字段用 describe() 标注含义
    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"),
    }),
  }
);

运行时上下文

调用 agent 时传递的每次运行配置——不会自动进入模型提示

运行时上下文用于传递用户元数据、API 密钥、功能标志等。模型只有在工具或中间件读取它时才会看到：

import { createDeepAgent } from "deepagents";
import { tool } from "@langchain/core/tools";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

// 定义运行时上下文的 schema，调用时传入的用户数据必须符合此结构
const contextSchema = z.object({
  userId: z.string(),
  apiKey: z.string(),
});

// 工具通过第二个参数 runtime 获取上下文
const fetchUserData = tool(
  async (input, runtime: ToolRuntime) => {
    // 从 runtime.context 中读取调用时传入的 userId
    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,  // 绑定上下文 schema，工具才能通过 runtime.context 访问
});

// 调用时通过第二个参数的 context 字段传入运行时上下文
const result = await agent.invoke(
  { messages: [{ role: "user", content: "Get my recent activity" }] },
  { context: { userId: "user-123", apiKey: "sk-..." } },
);

内容卸载

当工具输入或结果超过 token 阈值时，自动存入文件系统

长时间运行的任务会产生大量工具输出。内容卸载是第一道防线，默认阈值为 20,000 token：

智能摘要

当卸载不足以释放空间时，自动压缩对话历史

当上下文超过窗口限制（如 max_input_tokens 的 85%），且没有更多可卸载的内容时，触发摘要：

// 过滤掉摘要步骤生成的 token，只处理用户可见的输出
for await (const [namespace, chunk] of await agent.stream(
  { messages: [...] },
  { streamMode: "messages" },  // 以消息模式流式输出
)) {
  const [message, metadata] = chunk;
  if (metadata?.lcSource === "summarization") {
    continue;  // 跳过自动摘要产生的 token，避免干扰用户界面
  } else {
    // 处理正常的输出 token
  }
}

上下文隔离

用子 agent 隔离繁重工作——主 agent 只接收最终结果

当主 agent 使用产生大量输出的工具时，上下文窗口很快被填满。子 agent 解决了这个上下文膨胀问题：

const researchSubagent = {
  name: "researcher",
  description: "Conducts research on a topic",
  // 子 agent 的 systemPrompt 不继承主 agent，必须完整定义
  // 关键：要求返回摘要而非原始数据，避免撑爆主 agent 的上下文
  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],  // 只给搜索工具，保持子 agent 专注
};

长期记忆

跨对话持久保存信息——使用虚拟文件系统 + LangGraph Store

默认情况下，deep agent 的文件仅在线程内持久保存。长期记忆通过 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(),  // LangGraph 存储，用于跨线程持久化
  backend: new CompositeBackend(
    new StateBackend(),                  // 默认后端：线程内临时文件
    { "/memories/": new StoreBackend() }, // /memories/ 路径走跨线程持久化
  ),
  // 在系统提示中告知 Agent 如何使用长期记忆
  systemPrompt: `When users tell you their preferences,
  save them to /memories/user_preferences.txt
  so you remember them in future conversations.`,
});

最佳实践

六条经过验证的上下文管理策略

系统提示组装

理解完整的系统提示由哪些部分组成

模型在运行开始时接收到的系统消息，按顺序由以下部分组成：

本章回顾

上下文工程是让 deep agent 可靠运行的核心能力

延伸阅读