Conversation Management

Every agent conversation grows. Each turn adds user messages, assistant responses, and tool results. Eventually, the context window fills up — and then the model either errors out or starts hallucinating because it can't see its own earlier reasoning. Conversation managers solve this by intelligently reducing the message history before it becomes a problem.

The Problem: Context Windows Are Finite

A long-running agent accumulates messages quickly. A single tool call adds 3 messages (assistant tool_use, tool result, assistant response). After 20 turns with tools, you might have 60+ messages. Large tool results (database queries, file contents) can fill thousands of tokens each.

When the context window fills:

• The API returns a context-length error (hard failure)
• The model "forgets" earlier instructions (soft failure — more dangerous)
• Response quality degrades as the model struggles to attend to everything

Conversation managers prevent all three by reducing the message history to fit within limits while preserving the information that matters most.

Three Built-in Managers

NullConversationManager

Does nothing. Messages accumulate without bound. This is the default — fine for short-lived agents with predictable workloads where you know context won't be exceeded:

import { Agent, NullConversationManager } from '@strands-agents/sdk'

const agent = new Agent({
  name: 'short-task',
  model: 'us.anthropic.claude-sonnet-4-6-20250725-v1:0',
  systemPrompt: 'Answer the question briefly.',
  conversationManager: new NullConversationManager(),
  // This is the default — equivalent to not setting it at all
})

SlidingWindowConversationManager

Keeps the N most recent messages and drops everything older. Simple, fast, predictable — but loses context without replacement:

import { Agent, SlidingWindowConversationManager } from '@strands-agents/sdk'

const agent = new Agent({
  name: 'sliding-agent',
  model: 'us.anthropic.claude-sonnet-4-6-20250725-v1:0',
  systemPrompt: 'You are a helpful assistant.',
  conversationManager: new SlidingWindowConversationManager({
    windowSize: 20,                  // Keep last 20 messages
    shouldTruncateResults: true,     // Trim large tool results in kept messages
    maxResultLength: 2000,           // Truncate tool results beyond 2000 chars
  }),
})

The sliding window is appropriate when recent context matters more than historical context — chatbots, iterative coding assistants, real-time Q&A.

SummarizingConversationManager

The intelligent option. Instead of dropping old messages, it summarizes them — preserving the key information in compressed form. Uses a separate model call to create the summary:

import { Agent, SummarizingConversationManager } from '@strands-agents/sdk'

const agent = new Agent({
  name: 'summarizing-agent',
  model: 'us.anthropic.claude-sonnet-4-6-20250725-v1:0',
  systemPrompt: 'You are a project management assistant.',
  conversationManager: new SummarizingConversationManager({
    preserveRecentMessages: 10,   // Always keep the last 10 messages verbatim
    maxSummaryTokens: 500,        // Target length for the summary
    summarizationPrompt: `Summarize the following conversation history.
Focus on: decisions made, action items assigned, and key context.
Omit pleasantries, repeated questions, and tool call details.`,
  }),
})

When the conversation exceeds the threshold, messages older than preserveRecentMessages are replaced by a summary message. The agent sees: [summary of turns 1-30] + [verbatim turns 31-40]. Best of both worlds — compressed history plus full recent context.

Message Pinning

Both SlidingWindow and Summarizing managers support pinFirst — protecting the first N messages from eviction. Use this to ensure system instructions or critical context survive compression:

const agent = new Agent({
  name: 'pinned-agent',
  model: 'us.anthropic.claude-sonnet-4-6-20250725-v1:0',
  systemPrompt: 'You are a financial analyst.',
  conversationManager: new SlidingWindowConversationManager({
    windowSize: 15,
    pinFirst: 2,  // First 2 messages (system + initial context) never evicted
  }),
})

With pinFirst: 2, the conversation always contains the system prompt and whatever context message you injected first, regardless of how many messages are trimmed from the middle. This prevents the common failure mode where a long conversation causes the agent to "forget" its role.

Proactive Compression

By default, conversation managers trigger when the context would exceed the model's limit. Proactive compression triggers earlier — before you hit the wall — giving the model headroom to think:

const agent = new Agent({
  name: 'proactive-agent',
  model: 'us.anthropic.claude-sonnet-4-6-20250725-v1:0',
  systemPrompt: 'You are a research assistant.',
  conversationManager: new SummarizingConversationManager({
    preserveRecentMessages: 8,
    proactiveCompression: {
      enabled: true,
      compressionThreshold: 0.7,  // Compress when 70% of context is used
    },
  }),
})

With compressionThreshold: 0.7, compression fires when the conversation reaches 70% of the model's context window. This leaves 30% for the model's response and reasoning — preventing the case where the model has context for the question but no room to think about the answer.

Custom ConversationManager

If the built-in managers don't fit your needs, extend the base class and implement reduce(). The reduce method receives the full message array and must return a shorter one:

import { ConversationManager, Message } from '@strands-agents/sdk'

class TopicBasedManager extends ConversationManager {
  private maxMessages = 30

  async reduce(messages: Message[]): Promise {
    if (messages.length <= this.maxMessages) {
      return messages // No reduction needed
    }

    // Custom logic: keep system messages, recent messages,
    // and any message containing a "DECISION:" marker
    const system = messages.filter(m => m.role === 'system')
    const recent = messages.slice(-10)
    const decisions = messages.filter(
      m => m.role === 'assistant' &&
           typeof m.content === 'string' &&
           m.content.includes('DECISION:')
    )

    // Deduplicate (recent might overlap with decisions)
    const kept = new Set([...system, ...decisions, ...recent])
    return Array.from(kept)
  }
}

const agent = new Agent({
  name: 'custom-managed',
  model: 'us.anthropic.claude-sonnet-4-6-20250725-v1:0',
  systemPrompt: 'Track decisions across a long conversation.',
  conversationManager: new TopicBasedManager(),
})

Custom managers let you implement domain-specific logic: keep messages tagged as important, preserve tool results from specific tools, or merge multiple messages into one.

Production Pattern: Choosing the Right Manager

Match your manager to your agent's lifecycle:

// Production example: project management assistant
// Long-lived, decisions accumulate, recent context critical
const projectAssistant = new Agent({
  name: 'project-assistant',
  model: 'us.anthropic.claude-sonnet-4-6-20250725-v1:0',
  systemPrompt: `You help manage a software project.
Track decisions, action items, and blockers across conversations.`,
  conversationManager: new SummarizingConversationManager({
    preserveRecentMessages: 8,
    maxSummaryTokens: 800,
    proactiveCompression: {
      enabled: true,
      compressionThreshold: 0.7,
    },
    summarizationPrompt: `Summarize the conversation history for a project assistant.
Preserve: all decisions, action items with owners, unresolved blockers.
Discard: greetings, clarification exchanges, tool call mechanics.`,
  }),
})

Key Takeaways

• Context windows are finite — without management, long conversations error out or degrade silently.
• NullConversationManager (default) is fine for short-lived agents. Don't add complexity you don't need.
• SlidingWindow is fast and cheap — drops old messages. Good when recent context is most relevant.
• SummarizingConversationManager preserves information by compressing old messages into summaries. Costs one extra model call per compression event.
• pinFirst protects critical messages (system prompt, initial context) from eviction.
• Proactive compression (threshold 0.6-0.8) fires before the limit is hit — leaves room for the model to think.
• Custom managers via reduce() let you implement domain-specific retention logic.