Custom Strategies
When the built-in modes don’t fit, build a custom strategy pipeline. Define which content to reduce, how to reduce it, and when each strategy fires.
Strategy pipeline
Section titled “Strategy pipeline”Strategies run as an ordered pipeline. Each strategy sees the output of the previous one, so order determines priority. If two strategies target the same content, the first one to shrink it below the next strategy’s threshold wins.
The SDK always appends an emergency truncation strategy as the final step. It only fires when the context window is still overflowing after all user strategies have run.
from strands import Agentfrom strands.experimental.context_manager import Offload
agent = Agent( context_manager={ "strategies": [ Offload.truncate("tool_results").when( threshold=2000, ), Offload.summarize("*").when( utilization=0.8, preserve_recent=4, ), ], },)import { Agent } from '@strands-agents/sdk'import { Offload } from '@strands-agents/sdk/experimental'
const agent = new Agent({ contextManager: { strategies: [ Offload.truncate('toolResults').when({ blockThreshold: 2000, }), Offload.summarize('*').when({ contextUtilization: '80%', preserveRecent: 4, }), ], },})Offload builder
Section titled “Offload builder”The Offload namespace exposes three methods. Each returns a strategy builder that can be chained with .when().when()
Truncate
Section titled “Truncate”Replaces oversized content with a head/tail preview. The original content is stored in the stash for later retrieval.
from strands.experimental.context_manager import Offload
Offload.truncate( "tool_results", {"preview_tokens": 750},).when(threshold=1500)import { Offload } from '@strands-agents/sdk/experimental'
Offload.truncate('toolResults', { previewTokens: 750,}).when({ blockThreshold: 1500 })Truncate configuration:
| Parameter | Key | Default |
|---|---|---|
| Preview size | preview_tokens | 1,000 |
| Preview mode | preview | "head_tail" |
| Parameter | Key | Default |
|---|---|---|
| Preview size | previewTokens | 1,000 |
| Preview mode | preview | "headTail" |
Preview modes: "head", "tail", "head_tail""headTail"
Summarize
Section titled “Summarize”Replaces content with an LLM-generated summary. Uses agent.aux_modelagent.auxModel
from strands.experimental.context_manager import Offload
Offload.summarize("*").when( utilization=0.85, preserve_recent=4,)import { Offload } from '@strands-agents/sdk/experimental'
Offload.summarize('*').when({ contextUtilization: '85%', preserveRecent: 4,})Summarize configuration:
| Parameter | Key | Default |
|---|---|---|
| Model | model | agent.aux_model |
| Summarization instructions | system_prompt | Built-in |
A batched summary resends the conversation with the agent’s system prompt and tools, followed by the summarization instructions. When it runs on the agent’s model, it can reuse the agent’s prompt cache. If the summary leaves out messages it keeps, such as a pinned message or one under the threshold, it sends only the first message and the messages it replaces. Custom instructions replace the default guidance, but the client-side request always tells the model not to act on the conversation or call tools.
| Parameter | Key | Default |
|---|---|---|
| Model | model | agent.auxModel |
| Summarization instructions | systemPrompt | Built-in |
A batched summary resends the conversation with the agent’s system prompt and tools, followed by the summarization instructions. When it runs on the agent’s model, it can reuse the agent’s prompt cache. If the summary leaves out messages it keeps, such as a pinned message or one under the threshold, it sends only the first message and the messages it replaces. Custom instructions replace the default guidance, but the client-side request always tells the model not to act on the conversation or call tools.
Removes matching content entirely. No preview, no stash entry.
from strands.experimental.context_manager import Offload
Offload.drop("tool_results").when(preserve_recent=5)import { Offload } from '@strands-agents/sdk/experimental'
Offload.drop('toolResults').when({ preserveRecent: 5,})Conditions
Section titled “Conditions”Chain .when().when()
| Condition | Behavior |
|---|---|
thresholdblockThreshold | Minimum size to act on |
utilizationcontextUtilization | Context usage that triggers it |
preserve_recentpreserveRecent | Newest matches to skip |
Granularity — whether a strategy acts on whole messages or on individual blocks — is decided differently in each SDK.
Conditions decide granularity. threshold alone acts on each block above that
size as messages arrive. utilization alone removes or summarizes the oldest
messages once usage is exceeded. Both together target messages holding blocks
over the threshold, firing at the utilization level.
preserve_recent accepts an integer (absolute count) or a float between 0 and
1 (ratio of matching messages, e.g., 0.7 keeps 70%).
The target decides granularity, not the conditions. '*' always means whole
messages; every other target means individual blocks. contextUtilization
only controls when a strategy fires, and preserveRecent only controls what
is protected.
Each value is a whole number in the condition’s own unit (tokens, or messages for
preserveRecent), or an 'N%' share: of the context window for blockThreshold
and contextUtilization, of the matching messages for preserveRecent. Decimals
throw, so write '85%' rather than 0.85.
Per-block example
Section titled “Per-block example”Fire eagerly on individual blocks over 2,000 tokens:
from strands.experimental.context_manager import Offload
Offload.truncate("tool_results").when(threshold=2000)import { Offload } from '@strands-agents/sdk/experimental'
Offload.truncate('toolResults').when({ blockThreshold: 2000,})Message-level example
Section titled “Message-level example”Summarize oldest messages when the window reaches 85%:
from strands.experimental.context_manager import Offload
Offload.summarize("*").when( utilization=0.85, preserve_recent=4,)import { Offload } from '@strands-agents/sdk/experimental'
Offload.summarize('*').when({ contextUtilization: '85%', preserveRecent: 4,})Combined example
Section titled “Combined example”Target tool results over 1,500 tokens, but only fire when the window reaches 90%:
from strands.experimental.context_manager import Offload
Offload.truncate("tool_results").when( threshold=1500, utilization=0.9,)import { Offload } from '@strands-agents/sdk/experimental'
Offload.truncate('toolResults').when({ blockThreshold: 1500, contextUtilization: '90%',})Targets
Section titled “Targets”Targets specify which content a strategy applies to.
| Target | Value |
|---|---|
| All content | "*" |
| Tool results | "tool_results" |
| Failed tool results | "tool_result_errors" |
| Assistant text | "assistant_text" |
| User text | "user_text" |
| Specific tools | ["tool::bash", "tool::read_file"] |
| Exclude tools | ["!tool::bash"] |
| Target | Value |
|---|---|
| All content | "*" |
| Tool results | "toolResults" |
| Failed tool results | "toolResultErrors" |
| Assistant text | "assistantText" |
| User text | "userText" |
| Specific tools | ["tool::bash", "tool::readFile"] |
| Exclude tools | ["!tool::bash"] |
Tool name lists use the tool:: prefix. Prefix a name with ! to exclude it (apply to all tools except the listed ones).
The stash stores all message content on arrival as JSON, before any strategy runs. Truncated or summarized content can be retrieved on demand through the retrieve_context tool, which the SDK registers by default.
Stash uses in-memory storage by default. Configure it through the stashstash
- Omit or pass
truefor defaults (in-memory storage) - Pass a config with a custom storage backend
- Pass
falseto disable stash entirely
from strands import Agent
# Disable stash and retrieval toolagent = Agent( context_manager={ "stash": False, },)import { Agent } from '@strands-agents/sdk'
const agent = new Agent({ contextManager: { stash: false, },})Emergency truncation
Section titled “Emergency truncation”Every strategy pipeline ends with an emergency truncation strategy, appended automatically. It fires only when the context window is still overflowing after all user strategies have run. When it fires, it drops the oldest 20% of non-head messages.
Emergency truncation intentionally ignores pinned messages so an all-pinned overflow is still recoverable. Regular strategies respect pins.
Models that preserve thinking
Section titled “Models that preserve thinking”Claude models that preserve thinking bind each thinking block to the prefix that produced it: the system prompt, the tools, and the past messages the model saw when it generated the thinking block. A strategy that rewrites content before a thinking block leaves that block stale. Content after a thinking block, including the text in the same message, is not part of its prefix. When the model provider replays a stale block, it retries the request with drop_block, Claude skips the stale blocks, and the prompt cache restarts at the edited message. See Thinking block is bound to a different conversation for how the provider handles this.
Whether a strategy keeps thinking valid depends on its granularity:
- Message-level summaries keep thinking when they run server-side. When the summarizing model (
by default) and the agent’s model both supportagent.aux_modelagent.auxModel , a message-level summary goes through the model provider’s summarization API instead of a client-side summarization request. The provider returns the summary as a single block that stands in for the start of the conversation, so the thinking after it stays valid. The Anthropic model provider supports server-side summary. The Amazon Bedrock model provider (server_side_summaryserverSideSummaryBedrockModel) does not, so its message-level summaries are always client-side. - Eager per-block strategies keep thinking. A per-block strategy with only a
acts on each message as it is added, for any per-block target. It rewrites a tool result or user message before the model sees it, and an assistant message before any later thinking exists, so no thinking block’s prefix changes.thresholdblockThreshold - Other strategies drop thinking. A per-block strategy with
, or a message-level truncate or drop strategy, rewrites older content that later thinking blocks are bound to. Claude skips those thinking blocks, and the prompt cache restarts at the rewrite.preserve_recentpreserveRecent - Emergency truncation drops thinking. It removes the oldest messages when the context still overflows, so the thinking after them goes stale.
To keep thinking blocks on these models, summarize or truncate tool results eagerly and leave message-level summaries to models that support server-side summary. See Server-side summarization for an example.
A message-level summary runs client-side, which drops thinking, when either model lacks server-side support or a pinned message falls inside the summarized range. A pin logs server-side summary does not support pinned messages | falling back to client-side summary. If the server-side request fails or returns no summary, the strategy falls back to a client-side summary and logs a warning ending in the client-side summary rewrites history, so thinking blocks kept after it will be dropped.