strands.vended_plugins.context_offloader.plugin

ContextOffloader plugin for managing large tool outputs.

This module provides the ContextOffloader plugin that intercepts oversized tool results, persists each content block to a storage backend, and replaces the in-context result with a truncated preview and per-block references.

Example:

from strands import Agent
from strands.vended_plugins.context_offloader import (
    ContextOffloader,
    InMemoryStorage,
    FileStorage,
)

# In-memory storage
agent = Agent(plugins=[
    ContextOffloader(storage=InMemoryStorage())
])

# File storage with custom thresholds and retrieval tool enabled
agent = Agent(plugins=[
    ContextOffloader(
        storage=FileStorage("./artifacts"),
        max_result_tokens=5_000,
        preview_tokens=2_000,
        include_retrieval_tool=True,
    )
])

LineRange

class LineRange(TypedDict)

Defined in: src/strands/vended_plugins/context_offloader/plugin.py:124

A span of lines to retrieve (1-indexed, inclusive).

ContextOffloader

class ContextOffloader(Plugin)

Defined in: src/strands/vended_plugins/context_offloader/plugin.py:141

Plugin that offloads oversized tool results to reduce context consumption.

When a tool result exceeds the configured token threshold, this plugin stores each content block individually to a storage backend and replaces the in-context result with a truncated text preview plus per-block references.

Token estimation uses the agent’s model count_tokens method, which leverages tiktoken when available and falls back to character-based heuristics.

Content type handling:

Text: stored as text/plain, replaced with a preview
JSON: stored as application/json, replaced with a preview
Image: stored in its native format (e.g., image/png), replaced with a placeholder showing format and size
Document: stored in its native format (e.g., application/pdf), replaced with a placeholder showing format, name, and size
Unknown types: passed through unchanged

This operates proactively at tool execution time via AfterToolCallEvent, before the result enters the conversation — unlike SlidingWindowConversationManager which truncates reactively after context overflow.

Arguments:

storage - Backend for storing offloaded content (required).
max_result_tokens - Offload results whose estimated token count exceeds this threshold.
preview_tokens - Number of tokens to keep as a text preview in context.
include_retrieval_tool - Whether to register the retrieve_offloaded_content tool. Defaults to True.

Example:

from strands import Agent
from strands.vended_plugins.context_offloader import ContextOffloader, InMemoryStorage

agent = Agent(plugins=[
    ContextOffloader(storage=InMemoryStorage())
])

init

def __init__(storage: Storage | _LegacyStorage,
             max_result_tokens: int = _DEFAULT_MAX_RESULT_TOKENS,
             preview_tokens: int = _DEFAULT_PREVIEW_TOKENS,
             *,
             include_retrieval_tool: bool = True,
             evict_after_cycles: int | None = 20) -> None

Defined in: src/strands/vended_plugins/context_offloader/plugin.py:185

Initialize the ContextOffloader plugin.

Arguments:

storage - Backend for storing offloaded content. Accepts either a unified Storage (from strands.storage) or a legacy offloader Storage (from this module).
max_result_tokens - Offload results whose estimated token count exceeds this threshold. Defaults to _DEFAULT_MAX_RESULT_TOKENS (2,500).
preview_tokens - Number of tokens to keep as a text preview in context. Uses tiktoken for exact slicing when available, falls back to chars/4 heuristic. Defaults to _DEFAULT_PREVIEW_TOKENS (1,000).
include_retrieval_tool - Whether to register the retrieve_offloaded_content tool so the agent can fetch offloaded content. Defaults to True.
evict_after_cycles - Number of agent loop cycles before an offloaded entry is evicted (unified Storage only). Entries stored more than this many cycles ago are deleted. Defaults to 20. Set to None to disable eviction.

Raises:

ValueError - If max_result_tokens is not positive, preview_tokens is negative, preview_tokens >= max_result_tokens, or evict_after_cycles is invalid.

init_agent

def init_agent(agent: Agent) -> None

Defined in: src/strands/vended_plugins/context_offloader/plugin.py:263

Conditionally register the retrieval tool and bind storage.

retrieve_offloaded_content

@tool(context=True)
async def retrieve_offloaded_content(
        reference: str,
        tool_context: ToolContext,
        pattern: str | None = None,
        line_range: LineRange | None = None,
        context_lines: int | None = None) -> dict | str

Defined in: src/strands/vended_plugins/context_offloader/plugin.py:305

Retrieve offloaded content by reference.

When a tool result was too large to keep in context, it was stored externally and replaced with a preview and a reference. Use this tool with that reference to access the stored content.

Returns:

With pattern: matching lines with line numbers and surrounding context
With line_range: the specified span of lines with line numbers
Without pattern/line_range: the full original content (use sparingly — re-injects all tokens)

Constraints:

pattern/line_range/context_lines only work on text content. For binary content, omit them.
Line numbers in results are 1-indexed and can be used in follow-up line_range calls.

Examples:

\{"reference" - “ref_1”, “pattern”: “error”} -> lines containing “error” with 5 lines context
\{"reference" - “ref_1”, “pattern”: “error|warning”, “context_lines”: 3} -> regex, 3 lines context
\{"reference" - “ref_1”, “line_range”: {“start”: 10, “end”: 25}} -> lines 10-25
\{"reference" - “ref_1”, “pattern”: “TODO”, “line_range”: {“start”: 1, “end”: 50}} -> search within range

Arguments:

reference - The reference string from the offload placeholder (e.g. “mem_1_tool-123_0”).
pattern - Regex or keyword to grep for. Returns only matching lines with context — not the full content.
line_range - Return only this span of lines. A dict with ‘start’ and ‘end’ keys (1-indexed). Combine with pattern to search within the range.
context_lines - Lines before AND after each match (like grep -C). Default: 5. Without pattern/line_range, returns first N lines.
tool_context - Injected by the framework. Not user-facing.