Conversation Management

Every agent maintains a message history (agent.messages). Conversation managers control how that history grows and is trimmed to stay within the model's context window.

Default behaviour

The default SlidingWindowConversationManager keeps the last N message pairs:

from elsai import Agent

agent = Agent()  # Uses SlidingWindowConversationManager by default

agent("Message 1")
agent("Message 2")
agent("Message 3")
# agent.messages grows with each turn

Sliding window

Keep only the most recent messages:

from elsai import Agent
from elsai.agent.conversation_manager import SlidingWindowConversationManager

manager = SlidingWindowConversationManager(
    max_messages=20,    # Keep last 20 messages
)

agent = Agent(conversation_manager=manager)

Summarising

Automatically summarise old messages instead of discarding them:

from elsai import Agent
from elsai.agent.conversation_manager import SummarizingConversationManager

manager = SummarizingConversationManager(
    max_tokens=2000,           # Summarise when history exceeds this
    summary_model=None,        # Uses the agent's model for summarisation
)

agent = Agent(conversation_manager=manager)

When the context grows too large, the manager uses the LLM to produce a summary of the earlier conversation, replacing the old messages with the summary.

No management

For models that manage state server-side (like OpenAI's stateful APIs):

from elsai.agent.conversation_manager import NullConversationManager

agent = Agent(conversation_manager=NullConversationManager())

Inspecting conversation history

agent("Tell me your name")
agent("What did I just ask?")

for msg in agent.messages:
    role = msg["role"]
    text = "".join(
        block.get("text", "") for block in msg["content"]
        if "text" in block
    )
    print(f"[{role}] {text[:80]}")

Resetting conversation history

agent.messages = []  # Clear all history

Or start a fresh turn with a system prompt:

agent.messages = []
agent.system_prompt = "New instructions here."
agent("Fresh start!")

Pre-loading messages

Inject conversation history at agent creation time:

agent = Agent(
    messages=[
        {"role": "user", "content": [{"text": "My name is Alice."}]},
        {"role": "assistant", "content": [{"text": "Nice to meet you, Alice!"}]},
    ]
)

result = agent("What is my name?")
# → "Your name is Alice."

Custom conversation manager

Implement ConversationManager for custom behaviour:

from elsai.agent.conversation_manager import ConversationManager
from elsai.agent.base import AgentBase

class DatabaseConversationManager(ConversationManager):
    def __init__(self, db_url: str):
        self.db_url = db_url

    def apply_management(self, agent: AgentBase) -> None:
        # Called after each turn; trim or persist messages
        self._save_to_db(agent.messages)

    def reduce_context(self, agent: AgentBase, e=None) -> None:
        # Called when context window overflows; remove old messages
        agent.messages = agent.messages[-10:]

    def get_state(self) -> dict:
        return {}

    def restore_from_session(self, state: dict) -> None:
        pass