Deep Agents 中的 context engineering

​

Context 类型

​

Input context

​

System prompt

import { createDeepAgent } from "deepagents";

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.5-flash",
  systemPrompt: `You are a research assistant specializing in scientific literature.
  Always cite sources. Use subagents for parallel research on different topics.`,
});

​

Memory

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.5-flash",
  memory: ["/project/AGENTS.md", "~/.deepagents/preferences.md"],
});

​

Skills

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

​

Tool prompts

• Planning prompt：维护 structured task list 的 write_todos instructions
• Filesystem prompt：ls、read_file、write_file、edit_file、glob、grep 的 documentation（以及使用 sandbox backend 时的 execute）
• Subagent prompt：使用 task tool 委派 work 的 guidance
• Human-in-the-loop prompt：在指定 tool calls 处暂停的 usage（设置 interrupt_on 时）
• Local context prompt：当前 directory 和 project info（仅 CLI）

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"),
    }),
  }
);

​

Complete system prompt

1. Custom system_prompt（如果提供）
2. Base agent prompt
3. To-do list prompt：如何使用 to do lists 进行 planning 的 instructions
4. Memory prompt：AGENTS.md + memory usage guidelines（仅提供 memory 时）
5. Skills prompt：Skills locations + 带 frontmatter information 的 skills list + usage（仅提供 skills 时）
6. Virtual filesystem prompt (filesystem + execute tool docs if applicable)
7. Subagent prompt：Task tool usage
8. User-provided middleware prompts（如果提供 custom middleware）
9. Human-in-the-loop prompt（设置 interrupt_on 时）

​

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.5-flash",
  tools: [fetchUserData],
  contextSchema,
});

const result = await agent.invoke(
  { messages: [{ role: "user", content: "Get my recent activity" }] },
  { context: { userId: "user-123", apiKey: "sk-..." } },
);

​

Context compression

​

Offloading

1. Tool call inputs 超过 20,000 tokens：File write 和 edit operations 会在 agent conversation history 中留下包含完整 file content 的 tool calls。 由于此 content 已经持久化到 filesystem，它通常是冗余的。 当 session context 超过 model available window 的 85% 时，deep agents 会 truncate 较早的 tool calls，用指向 disk 上 file 的 pointer 替换它们，从而减少 active context 的大小。
2. Tool call results 超过 20,000 tokens：发生这种情况时，deep agent 会将 response offload 到 configured backend，并用 file path reference 和前 10 行 preview 替代它。Agents 之后可以按需重新读取或搜索该 content。

​

Multimodal inputs

• 将 images、screenshots 和 charts 存储在 filesystem backend 或 external object store 中，然后通过 messages 传递 file paths 或 URLs。
• 在 long-running conversations 中，优先使用 references，而不是 base64-encoded image blocks。
• 如果 tool 生成 image，请让 tool 保存 image，并返回 concise text description 以及 path 或 URL。
• 对 image-heavy inspection work 使用 subagents，让 main agent 接收 compact text result，而不是每个 multimodal intermediate step。
• 当 model provider 对 images 收取很多 tokens 时，调整 summarization thresholds 或提供 custom token counter。

​

Summarization

• In-context summary：LLM 生成 conversation 的 structured summary，包括 session intent、artifacts created 和 next steps，用它替换 agent working memory 中的 full conversation history。
• Filesystem preservation：Original conversation messages 的 text rendering 会作为 canonical record 写入 filesystem。

• 在 model profile 中 model max_input_tokens 的 85% 处触发
• 保留 10% tokens 作为 recent context
• 如果 model profile 不可用，则回退到 170,000-token trigger / 保留 6 条 messages
• 如果任何 model call 抛出标准 ContextOverflowError，deep agent 会立即回退到 summarization，并用 summary + recent preserved messages retry
• Older messages 由 model summarize

for await (const [namespace, chunk] of await agent.stream(
  { messages: [...] },
  { streamMode: "messages" },
)) {
  const [message, metadata] = chunk;
  if (metadata?.lcSource === "summarization") {
    continue;
  } else {
    ...
  }
}

​

Context isolation with subagents

• Main agent 有 task tool 用于 delegate work
• Subagent 使用自己的 fresh context 运行
• Subagent autonomously 执行直到 completion
• Subagent 向 main agent 返回单个 final report
• Main agent context 保持 clean

1. Delegate complex tasks：对会 clutter main agent context 的 multi-step work 使用 subagents。
2. 保持 subagent responses 简洁：指示 subagents 返回 summaries，而不是 raw data：
   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. 对 large data 使用 filesystem：Subagents 可以将 results 写入 files；main agent 读取自己需要的内容。

​

Long-term memory

import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph-checkpoint";

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.5-flash",
  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.`,
});

​

Best practices

1. 从正确的 input context 开始：对始终相关的 conventions 保持 memory 精简；对 task-specific capabilities 使用 focused skills。
2. 用 subagents 处理 heavy work：Delegate multi-step、output-heavy tasks，让 main agent context 保持 clean。
3. 在 configuration 中调整 subagent outputs：如果 debug 时发现 subagents 生成 long output，可以向 subagent 的 system_prompt 添加 guidance，让它创建 summaries 和 synthesized findings。
4. 使用 filesystem：将 large outputs 持久化到 files（例如 subagent writes 或 automatic offloading），使 active context 保持小；model 需要 details 时可以用 read_file 和 grep 拉取 fragments。
5. 记录 long-term memory structure：告诉 agent /memories/ 中有什么以及如何使用。
6. 为 tools 传入 runtime context：将 context 用于 user metadata、API keys 和 tools 需要的其他 static configuration。

​

Related resources

• Harness：Context management overview、offloading、summarization
• Subagents：Context isolation、runtime context propagation
• Long-term memory：Cross-thread persistence
• Skills：Progressive disclosure 和 skill authoring
• Backends：Filesystem backends 和 CompositeBackend
• Context conceptual overview：Context types 和 lifecycle