strands.agent.conversation_manager.sliding_window_conversation_manager

Sliding window conversation history management.

SlidingWindowConversationManager

class SlidingWindowConversationManager(ConversationManager)

Defined in: src/strands/agent/conversation_manager/sliding_window_conversation_manager.py:20

Implements a sliding window strategy for managing conversation history.

This class handles the logic of maintaining a conversation window that preserves tool usage pairs and avoids invalid window states.

When truncation is enabled (the default), large tool results are partially truncated, preserving the first and last 200 characters, and image blocks inside tool results are replaced with descriptive text placeholders. Truncation targets the oldest tool results first so the most relevant recent context is preserved as long as possible.

Supports proactive management during agent loop execution via the per_turn parameter.

__init__

def __init__(window_size: int = 40,
             should_truncate_results: bool = True,
             *,
             per_turn: bool | int = False,
             proactive_compression: bool | ProactiveCompressionConfig
             | None = None)

Defined in: src/strands/agent/conversation_manager/sliding_window_conversation_manager.py:34

Initialize the sliding window conversation manager.

Arguments:

• window_size - Maximum number of messages to keep in the agent’s history. Use 0 to clear all messages on every reduction. Defaults to 40 messages.

• should_truncate_results - Truncate tool results when a message is too large for the model’s context window

• per_turn - Controls when to apply message management during agent execution.

  • False (default): Only apply management at the end (default behavior)
  • True: Apply management before every model call
  • int (e.g., 3): Apply management before every N model calls

  When to use per_turn: If your agent performs many tool operations in loops (e.g., web browsing with frequent screenshots), enable per_turn to proactively manage message history and prevent the agent loop from slowing down. Start with per_turn=True and adjust to a specific frequency (e.g., per_turn=5) if needed for performance tuning.

• proactive_compression - Enable proactive context compression before the model call.

  • True: compress when 70% of the context window is used (default threshold).
  • \{"compression_threshold": float}: compress at the specified ratio (0, 1].
  • False or None: disabled, only reactive overflow recovery is used.

Raises:

• ValueError - If window_size is negative, or if per_turn is 0 or a negative integer.

register_hooks

def register_hooks(registry: "HookRegistry", **kwargs: Any) -> None

Defined in: src/strands/agent/conversation_manager/sliding_window_conversation_manager.py:78

Register hook callbacks for per-turn conversation management.

Arguments:

• registry - The hook registry to register callbacks with.
• **kwargs - Additional keyword arguments for future extensibility.

get_state

def get_state() -> dict[str, Any]

Defined in: src/strands/agent/conversation_manager/sliding_window_conversation_manager.py:120

Get the current state of the conversation manager.

Returns:

Dictionary containing the manager’s state, including model call count for per-turn tracking.

restore_from_session

def restore_from_session(state: dict[str, Any]) -> list | None

Defined in: src/strands/agent/conversation_manager/sliding_window_conversation_manager.py:130

Restore the conversation manager’s state from a session.

Arguments:

• state - Previous state of the conversation manager

Returns:

Optional list of messages to prepend to the agent’s messages.

apply_management

def apply_management(agent: "Agent", **kwargs: Any) -> None

Defined in: src/strands/agent/conversation_manager/sliding_window_conversation_manager.py:143

Apply the sliding window to the agent’s messages array to maintain a manageable history size.

This method is called after every event loop cycle to apply a sliding window if the message count exceeds the window size.

Arguments:

• agent - The agent whose messages will be managed. This list is modified in-place.
• **kwargs - Additional keyword arguments for future extensibility.

reduce_context

def reduce_context(agent: "Agent",
                   e: Exception | None = None,
                   **kwargs: Any) -> None

Defined in: src/strands/agent/conversation_manager/sliding_window_conversation_manager.py:163

Trim the oldest messages to reduce the conversation context size.

When e is set (reactive overflow recovery), attempts to truncate large tool results first before falling back to message trimming.

When e is None (proactive compression or routine management), only trims messages without attempting tool result truncation.

The method handles special cases where trimming the messages leads to:

• toolResult with no corresponding toolUse
• toolUse with no corresponding toolResult

Arguments:

• agent - The agent whose messages will be reduce. This list is modified in-place.
• e - The exception that triggered the context reduction, if any. When set, this is a reactive overflow recovery call. When None, this is a proactive or routine management call.
• **kwargs - Additional keyword arguments for future extensibility.

Raises:

• ContextWindowOverflowException - If the context cannot be reduced further and a context overflow error was provided (e is not None). When called during routine window management or proactive compression (e is None), logs a warning and returns without modification.