Agent Loop

The agent loop is the core reasoning cycle that powers every Elsai agent. Understanding it helps you reason about latency, token usage, and when hooks fire.

How it works

The loop continues until:

• The model returns end_turn (has a final answer)
• max_tokens is reached
• The agent is cancelled

Event sequence

For each agent invocation, these hooks fire in order:

Conversation history

The agent accumulates messages in agent.messages. Each round trip looks like:

agent.messages = [
    {"role": "user",      "content": [{"text": "What is 2+2?"}]},
    {"role": "assistant", "content": [{"toolUse": {"name": "calculator", ...}}]},
    {"role": "user",      "content": [{"toolResult": {"toolUseId": "...", "content": [{"text": "4"}]}}]},
    {"role": "assistant", "content": [{"text": "2 + 2 = 4."}]},
]

Conversation managers

Manage context window size with a conversation manager:

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

# Keep the last 20 messages
manager = SlidingWindowConversationManager(max_messages=20)
agent = Agent(conversation_manager=manager)

Built-in managers:

Class	Behaviour
SlidingWindowConversationManager	Drops oldest messages when limit reached (default)
SummarizingConversationManager	Summarises old messages using the model itself
NullConversationManager	No management — used with stateful models

Context window overflow

When the model returns a context-too-long error, the SDK automatically asks the conversation manager to reduce context and retries:

from elsai.agent.conversation_manager import SummarizingConversationManager

agent = Agent(conversation_manager=SummarizingConversationManager())
# Automatically summarises and retries on context overflow

Retry strategy

Transient errors (throttling, network timeouts) are retried automatically with exponential backoff:

from elsai import Agent
from elsai.event_loop._retry import ModelRetryStrategy

agent = Agent(
    retry_strategy=ModelRetryStrategy(
        max_attempts=6,
        initial_delay=4.0,
        max_delay=240.0,
    )
)

# Disable retries
agent = Agent(retry_strategy=None)

Tool execution

By default tools are executed concurrently when the model requests multiple at once:

from elsai import Agent
from elsai.tools.executors import ConcurrentToolExecutor, SequentialToolExecutor

# Concurrent (default)
agent = Agent(tool_executor=ConcurrentToolExecutor())

# Sequential (one at a time)
agent = Agent(tool_executor=SequentialToolExecutor())

Inspecting the loop

Access raw metrics after a call:

result = agent("Calculate something complex")
print(result.metrics.input_tokens)
print(result.metrics.output_tokens)
print(result.metrics.latency_ms)