Skip to content

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.

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 Agent
from 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,
),
],
},
)

The Offload namespace exposes three methods. Each returns a strategy builder that can be chained with .when().when() to add conditions.

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)

Truncate configuration:

ParameterKeyDefault
Preview sizepreview_tokens1,000
Preview modepreview"head_tail"

Preview modes: "head", "tail", "head_tail""headTail".

Replaces content with an LLM-generated summary. Uses agent.aux_modelagent.auxModel by default.

from strands.experimental.context_manager import Offload
Offload.summarize("*").when(
utilization=0.85,
preserve_recent=4,
)

Summarize configuration:

ParameterKeyDefault
Modelmodelagent.aux_model
Summarization instructionssystem_promptBuilt-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)

Chain .when().when() to control when a strategy fires.

ConditionBehavior
thresholdblockThresholdMinimum size to act on
utilizationcontextUtilizationContext usage that triggers it
preserve_recentpreserveRecentNewest 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%).

Fire eagerly on individual blocks over 2,000 tokens:

from strands.experimental.context_manager import Offload
Offload.truncate("tool_results").when(threshold=2000)

Summarize oldest messages when the window reaches 85%:

from strands.experimental.context_manager import Offload
Offload.summarize("*").when(
utilization=0.85,
preserve_recent=4,
)

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,
)

Targets specify which content a strategy applies to.

TargetValue
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"]

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 key:

  • Omit or pass true for defaults (in-memory storage)
  • Pass a config with a custom storage backend
  • Pass false to disable stash entirely
from strands import Agent
# Disable stash and retrieval tool
agent = Agent(
context_manager={
"stash": False,
},
)

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.

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 (agent.aux_modelagent.auxModel by default) and the agent’s model both support server_side_summaryserverSideSummary, 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 (BedrockModel) does not, so its message-level summaries are always client-side.
  • Eager per-block strategies keep thinking. A per-block strategy with only a thresholdblockThreshold 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.
  • Other strategies drop thinking. A per-block strategy with preserve_recentpreserveRecent, 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.
  • 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.