Context engineering in Deep Agents

​

Types of context

​

Input context

​

System prompt

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    system_prompt=(
        "You are a research assistant specializing in scientific literature. "
        "Always cite sources. Use subagents for parallel research on different topics."
    ),
)

​

Memory

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    memory=["/project/AGENTS.md", "~/.deepagents/preferences.md"],
)

​

Skills

agent = create_deep_agent(
    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)

@tool(parse_docstring=True)
def search_orders(
    user_id: str,
    status: str,
    limit: int = 10
) -> str:
    """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.

    Args:
        user_id: Unique identifier for the user
        status: Order status: 'pending', 'shipped', or 'delivered'
        limit: Maximum number of results to return
    """
    # Implementation here
    ...

​

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

from langchain.agents import tool

@tool
def fetch_user_data(query: str, config) -> str:
    """Fetch data for the current user."""
    user_id = config.get("context", {}).get("user_id")
    return f"Data for user {user_id}: {query}"

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    tools=[fetch_user_data],
    context_schema={"user_id": str, "api_key": str},
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Get my recent activity"}]},
    config={"context": {"user_id": "user-123", "api_key": "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

Summarization Tool

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import (
    create_summarization_tool_middleware,
)

backend = StateBackend  # if using default backend

model = "openai:gpt-5.4"
agent = create_deep_agent(
    model=model,
    middleware=[
        create_summarization_tool_middleware(model, backend),
    ],
)

​

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

   research_subagent = {
       "name": "researcher",
       "description": "Conducts research on a topic",
       "system_prompt": """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": [web_search],
   }
   
3. Use the filesystem for large data: Subagents can write results to files; the main agent reads what it needs.

​

Long-term memory

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

def make_backend(runtime):
    return CompositeBackend(
        default=StateBackend(runtime),
        routes={"/memories/": StoreBackend(runtime)},
    )

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    store=InMemoryStore(),
    backend=make_backend,
    system_prompt="""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