How Deep Agents manages context when the task outlives the prompt
An implementation-level analysis of LangChain Deep Agents context offloading, filesystem backends, summarization, subagent isolation, and long-horizon reliability.

Turn 1 Read a 40,000-token report.
Turn 8 Write a 2,000-line implementation file.
Turn 19 Delegate a market comparison.
Turn 34 Re-open one sentence from the original report.
An ordinary agent loop tends to treat this as one growing transcript. Every tool result, write payload, plan, and subtask result remains another object the next model call must search through. Eventually the prompt reaches a hard limit. Long before that, useful information becomes expensive to locate and easy to miss.
LangChain Deep Agents takes a different approach. It treats the active model context as a working set, not as the complete record of the task. The harness moves large data to a virtual filesystem, compresses old interaction history, delegates bounded work to subagents, and persists state through LangGraph. The main model keeps enough information to continue. The rest must be recoverable through tools and state.
That design is more than a longer context window with automatic summarization. It changes where information lives, who sees it, and which model call is responsible for finding it again.
What Deep Agents adds to a normal agent loop
Deep Agents is an opinionated harness built around LangChain's create_agent. Its source architecture guide identifies graph.py as the assembly point. create_deep_agent() builds a middleware stack and delegates to langchain.agents.create_agent(). The stack includes filesystem access, subagent delegation, context compression, skills, permissions, and optional memory, human approval, and provider prompt caching.
That distinction is useful. A normal LangChain agent can use middleware, a store, tools, and a checkpointer. Deep Agents packages a particular answer to the long-running-task problem. The answer assumes that an agent will plan, manipulate files, call tools with large outputs, and occasionally delegate work. Those assumptions are helpful for research and coding tasks. They are overhead for a small, deterministic workflow.
The public API can start simply.
from deepagents import create_deep_agent
agent = create_deep_agent(
model="openai:gpt-5",
system_prompt="You are a research engineer. Preserve source paths in your notes.",
)
The generated agent has more than a chat history. It has an execution environment and a lifecycle policy. The Deep Agents documentation describes its virtual filesystem, tools, code execution, and subagent capabilities. The implementation places those features in middleware and pluggable backends instead of putting every artifact into the message list.
The active prompt is deliberately incomplete
The central design choice is easy to state. The context that the model sees now is not the canonical record of the run.
An active context can include the recent messages, the current plan, tool calls that remain useful, a running summary, and references to offloaded files. It does not need to contain the full body of a 40,000-token API response if that response is retrievable from the filesystem. It does not need to repeat an entire file write once the file exists on a backend.
This reduces repeated input tokens. It also reduces a more subtle source of error. A model that sees a large transcript has to perform relevance retrieval and task reasoning in the same forward pass. Lost in the Middle showed that relevant information can be used less reliably when it appears in the middle of a long input. Long context capacity therefore does not prove long-horizon agent capability.
Deep Agents exchanges a passive long prompt for active information recovery. The agent can call read_file, grep, glob, and related filesystem tools to recover old material. This improves control over prompt size. It introduces a new decision. The model has to recognize that an old detail matters, select the correct file or search query, and use the recovered evidence correctly.
The documented compression lifecycle
LangChain's January 2026 engineering article, "Context Management for Deep Agents", describes three compression mechanisms. They run at different moments and preserve different things.
Large tool results move out immediately
When a tool result exceeds 20,000 tokens, Deep Agents offloads the result to the configured filesystem backend. The active conversation receives a file path and a preview of the first ten lines. The model can later call a filesystem tool to read or search the content.
This is offloading, not summarization. The raw content survives without an LLM rewriting it. The next prompt is much smaller, but it no longer contains the evidence itself. It contains a pointer and a preview.
The current FilesystemMiddleware implementation exposes a configurable tool_token_limit_before_evict with a default of 20,000. The docs say that internal large results are stored under /large_tool_results/ by default. These details matter operationally. Offloaded results need the same access controls, retention policy, and observability as the tool output they replace.
Redundant write and edit inputs leave later
An agent that writes a large source file produces a second copy of that file in its own tool-call arguments. The file is already present in the virtual filesystem. Keeping the full argument in every subsequent prompt spends context on redundant data.
When the session reaches 85% of the model context window, Deep Agents can replace older file write and edit arguments with pointers to their persisted file. This is a lower-risk compression than summarization. The content has already been written. The model loses inline access but not the bytes.
The threshold is a default, not a performance guarantee. A model with a large nominal window may still make worse decisions before reaching it. Conversely, a short task may be safer with exact history and no compression. Thresholds control when the harness acts. They do not decide which earlier fact will matter later.
Summarization is the final compaction step
If offloading cannot free sufficient space, Deep Agents summarizes older messages. The active prompt gets an LLM-generated summary that covers the session's intent, artifacts, progress, and next steps. The complete original message history is also offloaded to the filesystem as a canonical record.
The current summarization middleware source stores history as markdown under /conversation_history/{session_id}.md and appends a section for each summarization event. Its Deep Agents summary prompt extends LangChain's base prompt with instructions to preserve filesystem references and offloaded media paths when they may matter later.
This is a useful dual representation. The summary keeps the agent oriented. The full log retains the evidence that the summary omitted. It does not mean a lost detail is automatically available to a later decision. The agent must still search for and read the right part of the history.
Offloading and summarization solve different problems
These terms are often grouped under "context compression." They have different failure modes.
Offloading preserves raw information but removes it from the active context. It works best when the artifact has an address, a useful name or path, and an agent can retrieve a bounded section later. A file report, a large JSON response, or an old edit payload fits this model.
Summarization keeps a smaller semantic representation in the active context. It works when an agent needs continuity more often than it needs exact wording. It is inherently lossy. The summary may collapse a caveat, mistake a proposal for a decision, or retain an outdated version of a fact.
Raw offload
original report -> filesystem -> path and preview in prompt
Summary
message history -> summarizer -> compact interpretation in prompt
message history -> filesystem -> canonical recovery record
The practical consequence is that offloading is an information-location problem. Summarization is an information-fidelity problem. A system usually needs both. Offload high-volume artifacts that can be reopened. Summarize interaction history that the agent must understand as a narrative. Store machine-critical workflow fields separately in state.
Do not ask a summary to hold an invariant that code can store exactly. Approval status, selected customer ID, file digest, policy version, budget consumed, and idempotency key belong in typed state or an external record. The summary can tell the agent why the approval is pending. It should not be the only place that carries the approved amount.
The filesystem is an addressable context store
Deep Agents uses a virtual filesystem rather than assuming local disk. The backend can be thread-scoped state, a persistent LangGraph store, local disk, a sandbox, a composite router, or a custom backend. The backend documentation recommends a CompositeBackend when project files should live on disk while internal context artifacts remain in ephemeral state.
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, FilesystemBackend, StateBackend
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(),
routes={
"/workspace/": FilesystemBackend(
root_dir="/srv/research-workspace",
virtual_mode=True,
)
},
)
)
In this arrangement, a report created at /workspace/findings.md can be durable project work, while /large_tool_results/ and /conversation_history/ remain separate internal artifacts. That separation reduces accidental pollution of a project directory and makes it possible to apply different retention rules.
The filesystem has a practical advantage over a single summary. It supports selective recovery. read_file can page through a large file. grep can search text. glob can discover an artifact whose exact name the model has forgotten. The model does not need to rehydrate the entire original result just to retrieve one paragraph.
It has limitations too. File paths are only useful if the agent can infer that a file matters. Search quality depends on names, file structure, and the query the model generates. An agent can choose the wrong file, read the wrong page, or fail to search at all. A filesystem without metadata is a larger haystack with better tools.
For durable knowledge, use a record format that exposes provenance and time rather than relying on filenames alone.
decision_id: pricing-rule-2026-11-13
status: active
effective_from: 2026-11-13
source: /workspace/approved/pricing-policy-v4.md
supersedes: pricing-rule-2026-08-01
scope: enterprise-eu
This does not replace semantic retrieval. It gives the agent and application a deterministic way to identify the active record when time and scope are known.
Subagent isolation changes information flow
Subagents solve a different context problem. Instead of compressing information after the main agent sees it, they keep much of the work out of the main agent's context in the first place.
The Deep Agents task tool can delegate a bounded task to a specialist. Under the default isolated mode, the subagent receives only the delegated task. It has its own messages, tool calls, and intermediate observations. The parent receives the final report or a structured result, not the whole tool trajectory. This behavior is described in the subagent source, where isolated is the default and fork is the alternative context mode.
Isolation is useful for independent research, file inspection, or a specialized implementation task. The parent avoids paying to include dozens of search results and tool observations in later calls. The subagent can use a different model, tool set, prompt, filesystem permissions, and skills.
It also means the parent cannot inspect details that the subagent omitted from its final result. A sentence such as "no relevant policy found" is a weak handoff if the parent later needs source coverage, search terms, and uncertainty. For important delegations, define a structured response with findings, source paths, unresolved questions, and confidence. Store richer artifacts in a shared or routed backend when the parent may need to audit them.
fork mode makes a different trade. It gives a subagent the parent's effective conversation history and state. This can preserve task continuity when the subtask truly depends on prior reasoning. It also copies context into another agent call and weakens the token-efficiency benefit. Use it for a continuation. Do not use it as the default way to make an isolated specialist understand a poorly specified task.
Persistence is not accessibility
Deep Agents preserves more information than a simple transcript-only agent. Files, complete pre-summary history, state checkpoints, and delegated artifacts can survive beyond an active prompt. That is necessary for long-running work. It is not sufficient for reliable work.
There are four distinct conditions.
- The information still exists in a backend or checkpoint.
- The agent recognizes that it needs the information.
- The agent finds the correct artifact or history segment.
- The agent uses the recovered content correctly in its next decision.
A filesystem improves condition one and can help condition three. It does not guarantee conditions two or four. This is the same separation identified by long-context research. Relevant evidence may exist, but a model can fail to retrieve or apply it.
The Deep Agents engineering article makes this operational. Its targeted evaluations force compression earlier, often at 10% to 20% of the context window rather than the 85% default. The goal is not a synthetic claim about total benchmark performance. It is to create enough compression events to test whether the agent retains its objective and can recover a deliberately offloaded fact. That is the correct test shape for this architecture.
Use this kind of test suite before changing a summarization prompt, backend routing policy, or subagent response format.
{
"case_id": "history-recovery-018",
"early_fact": "The deployment target is eu-west-1 only.",
"force_summarization_after_turn": 4,
"later_request": "Prepare the deployment configuration.",
"required_recovery": "/conversation_history/",
"forbidden_output": "us-east-1"
}
The evaluator should inspect both the final configuration and the trajectory. Did the agent search or read the correct history? Did it use the recovered region? Did it succeed by accident because the region appeared elsewhere?
Context efficiency has an orchestration cost
Deep Agents reduces the repeated token cost of large artifacts in the main agent. It does not make the task free.
Offloading creates file writes and later reads. Summarization adds model calls and may cause recovery reads. Subagents add model calls, tool use, and result synthesis. fork duplicates parent context. Persistent storage adds backend cost and data-governance obligations. Prompt caching can help repeated prefixes, but it cannot turn irrelevant or poorly retrieved context into useful evidence.
The total cost of a long task is therefore not only input tokens in the main agent. It includes retrieval calls, filesystem operations, summarizer calls, subagent work, and the cost of recovering from a wrong or missing fact. A smaller prompt can cost more end to end if the agent repeatedly searches for facts it used to have inline.
The right objective is not minimum prompt length. It is minimum cost for a reliable trajectory. For a short, high-stakes approval sequence, exact state and a compact transcript may beat a file-backed architecture. For a multi-hour research or coding task with large artifacts, a working set plus addressable storage can be far more reliable than an ever-growing transcript.
When the harness earns its complexity
Deep Agents has a clear advantage when the work naturally creates large artifacts, requires plans that change as evidence arrives, benefits from task-specific delegation, and must survive past one context window. Deep research, repository-level coding, audit preparation, and multi-document analysis fit that profile.
It is less compelling when the process is already a known graph with a few small tool calls. A deterministic LangGraph workflow with typed state is easier to test and cheaper to operate. A single support lookup does not need a virtual filesystem and subagents. Adding them can make failures harder to trace because the information path has more branches.
The practical rule is to choose Deep Agents when the task needs a managed workspace, not just a chat loop with tools. Then define the contracts around that workspace. Which paths hold canonical artifacts? What can a subagent write? Which facts must be in state rather than a summary? How does the agent prove that it recovered an offloaded decision before acting?
Deep Agents supplies the mechanisms. The application still has to decide which information is durable, which is recoverable, and which must be visible now. That distinction determines whether context management improves an agent or merely moves its forgotten facts to a different place.
Sources
- LangChain Team, Context Management for Deep Agents, January 2026.
- LangChain, Deep Agents context engineering and backends.
- Deep Agents source,
graph.py,summarization.py,filesystem.py, andsubagents.py. - Liu et al., Lost in the Middle: How Language Models Use Long Contexts, TACL 2024.

