strands.agent.conversation_manager.sliding_window_conversation_manager

Sliding window conversation history management.

SlidingWindowConversationManager

class SlidingWindowConversationManager(ConversationManager)

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.

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

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

Initialize the sliding window conversation manager.

Arguments:

window_size - Maximum number of messages to keep in the agent’s history. 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.

Raises:

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

Arguments:

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

Get the current state of the conversation manager.

Returns:

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

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

Restore the conversation manager’s state from a session.

Arguments:

Returns:

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

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

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.

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

Trim the oldest messages to reduce the conversation context size.

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

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.
**kwargs - Additional keyword arguments for future extensibility.

Raises:

ContextWindowOverflowException - If the context cannot be reduced further. Such as when the conversation is already minimal or when tool result messages cannot be properly converted.