Context engineering in Deep Agents

​

Types of context

​

Input context

​

System prompt

import { createDeepAgent } from "deepagents";

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

​

Skills

const agent = await createDeepAgent({
  model: "claude-sonnet-4-6",
  skills: ["/skills/research/", "/skills/web-search/"],
});

​

Tool prompts

• Planning prompt – Instructions for write_todos to maintain a structured task list
• Filesystem prompt – Documentation for ls, read_file, write_file, edit_file, glob, grep (and execute when using a sandbox backend)
• Subagent prompt – Guidance for delegating work with the task tool
• Human-in-the-loop prompt – Usage for pausing at specified tool calls (when interrupt_on is set)
• Local context prompt – Current directory and project info (CLI only)

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 (if provided)
2. Base agent prompt
3. To-do list prompt: Instructions for how to plan with to do lists
4. Memory prompt: AGENTS.md + memory usage guidelines (only when memory provided)
5. Skills prompt: Skills locations + list of skills with frontmatter information + usage (only when skills provided)
6. Virtual filesystem prompt (filesystem + execute tool docs if applicable)
7. Subagent prompt: Task tool usage
8. User-provided middleware prompts (if custom middleware is provided)
9. Human-in-the-loop prompt (when interrupt_on is set)

​

Runtime context

import { tool } from "langchain";
import { z } from "zod";

const fetchUserData = tool(
  (input, config) => {
    const userId = config.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 contextSchema = z.object({
  userId: z.string(),
  apiKey: z.string(),
});

const agent = await createDeepAgent({
  model: "claude-sonnet-4-6",
  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 exceed 20,000 tokens: File write and edit operations leave behind tool calls containing the complete file content in the agent’s conversation history. Since this content is already persisted to the filesystem, it’s often redundant. As the session context crosses 85% of the model’s available window, deep agents truncate older tool calls, replacing them with a pointer to the file on disk and reducing the size of the active context.
2. Tool call results exceed 20,000 tokens: When this occurs, the deep agent offloads the response to the configured backend and substitutes it with a file path reference and a preview of the first 10 lines. Agents can then re-read or search the content as needed.

​

Summarization

• In-context summary: An LLM generates a structured summary of the conversation including session intent, artifacts created, and next steps—which replaces the full conversation history in the agent’s working memory.
• Filesystem preservation: The complete, original conversation messages are written to the filesystem as a canonical record.

• Triggers at 85% of the model’s max_input_tokens from its model profile
• Keeps 10% of tokens as recent context
• Falls back to 170,000-token trigger / 6 messages kept if model profile is unavailable
• If any model call raises a standard ContextOverflowError, Deep Agents immediately falls back to summarization and retries with summary + recent preserved messages
• Older messages are summarized by the model

​

Context isolation with subagents

• Main agent has a task tool to delegate work
• Subagent runs with its own fresh context
• Subagent executes autonomously until completion
• Subagent returns a single final report to the main agent
• Main agent’s context stays clean

1. Delegate complex tasks: Use subagents for multi-step work that would clutter the main agent’s context.
2. Keep subagent responses concise: Instruct subagents to return summaries, not raw data:
   Copy

   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. Use the filesystem for large data: Subagents can write results to files; the main agent reads what it needs.

​

Long-term memory

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: `When users tell you their preferences, save them to /memories/user_preferences.txt so you remember them in future conversations.`,
});

​

Best practices

1. Start with the right input context – Keep memory minimal for always-relevant conventions; use focused skills for task-specific capabilities.
2. Leverage subagents for heavy work – Delegate multi-step, output-heavy tasks to keep the main agent’s context clean.
3. Adjust subagent outputs in configuration – If you notice when debugging that subagents generate long output, you can add guidance to the subagent’s system_prompt to create summaries and synthesized findings.
4. Use the filesystem – Persist large outputs to files (for example subagent writes or automatic offloading) so the active context stays small; the model can pull in fragments with read_file and grep when it needs details.
5. Document long-term memory structure – Tell the agent what lives in /memories/ and how to use it.
6. Pass runtime context for tools – Use context for user metadata, API keys, and other static configuration that tools need.

​

Related resources

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