Summarization and offload, with the actual numbers

An agent that runs for four hours does not fail because the model got worse. It fails because the context window filled up with tool output nobody needed.

The failure this module exists for

Long-running agents die of their own success. Every tool call returns something, every something gets appended, and the window is finite. The killer is almost never the conversation, it is tool results: a file read, a search hit list, a database dump, an API response with two thousand rows in it.

So the defences are aimed there, and they are mechanical rather than clever. There are two, they drain different reservoirs, and a serious agent needs both.

Offloading: 20,000 tokens

The tool-result offload threshold is 20,000 tokens. Past that, a result does not go into the context. It goes to a file.

That figure is a constructor argument, not folklore: FilesystemMiddleware(tool_token_limit_before_evict=20000). The same constructor carries a second, less-quoted threshold: human_message_token_limit_before_evict=50000, which does the same job for an oversized human message. Two thresholds, two message types, and the larger one is the easier exam distractor precisely because most study notes only mention the first.

Summarization: whose defaults are these

Here is the boundary that the numbers below hang off, and it is the single most misread thing in this module.

That function picks one of two mutually exclusive branches, based on whether the model profile exposes max_input_tokens:

profile exposes max_input_tokens:
  trigger                 ("fraction", 0.85)
  keep                    ("fraction", 0.10)
  truncate_args_settings  ("fraction", 0.85) / ("fraction", 0.10)

no profile info:
  trigger                 ("tokens", 170000)
  keep                    ("messages", 6)
  truncate_args_settings  ("messages", 20) / ("messages", 20)

Read that as alternatives, not as percentages plus fallbacks. Exactly one branch applies to any given model. The fixed figures are not a safety net underneath the fractions; they are what you get instead of them, and the source comments call them deliberately conservative because they are guarding an unknown limit.

It fires at 0.85 and keeps 0.10. Say those as a pair every time, because the exam distractor is the one that reuses 0.85 for both. Consistency feels right and the real design is deliberately lopsided.

What survives is a summary of the older conversation plus the most recent slice kept intact. That shape is deliberate: recent messages are the ones the model is mid-reasoning about, so paraphrasing them would break the thread it is currently pulling on. Old ones are safe to compress because only their conclusions still matter.

Which gives you a real tuning rule: if an agent loses the plot right after a compression, the keep-ratio is too aggressive, not the trigger. Raising the trigger only delays the same failure.

The eighty-five collision, corrected

0.85 really does appear twice, and the tempting explanation is that the two uses measure against different denominators, one the context window and one max_input_tokens. That reading is wrong. Both are ("fraction", 0.85), and a fraction is only ever resolved one way: against the model profile’s max_input_tokens.

The two uses differ in what they do, not in what they measure:

• truncate_args_settings clips oversized tool-call arguments on messages older than the keep window. Think write_file content and edit_file patches.
• The summarization trigger compacts the conversation itself.

And the ordering is the point: argument truncation is the cheap pre-pass, and it frequently reclaims enough room that full summarization never has to run at all. One threshold, two escalating responses.

Where it sits in the stack

SummarizationMiddleware is part of the fixed deep agent base stack, after FilesystemMiddleware and the subagent middleware and before PatchToolCallsMiddleware. Its exact ordinal position moves, because the middleware ahead of it is conditional: skills middleware is only present if you passed skills, and subagent middleware only if the agent has inline subagents. Learn it by neighbours, not by number.

One more precision worth carrying: what a deep agent installs is deepagents’ own wrapper around the LangChain middleware, not the plain class. The wrapper adds backend offload of evicted history to /conversation_history/{thread_id}.md, the pre-summarization argument truncation above, a retry on provider context-overflow errors, and non-mutating message state. The plain SummarizationMiddleware drops evicted messages with no recovery path. Defaults and assembly, not capability, one more time.