Agents

The Agent class is the core primitive in Elsai. It wraps a language model, manages conversation history, executes tools, and coordinates the full reasoning loop.

Basic usage

from elsai import Agent

agent = Agent()
result = agent("Summarize the top trends in AI for 2025")
print(result)

Constructor parameters

Parameter	Type	Default	Description
model	Model | str | None	BedrockModel()	The LLM to use. Pass a model instance, a Bedrock model ID string, or None for the default.
tools	list | None	None	Tools available to the agent.
system_prompt	str | list | None	None	Instructions that guide model behavior.
messages	list | None	[]	Pre-load conversation history.
conversation_manager	ConversationManager | None	SlidingWindowConversationManager	Controls how conversation history is managed.
callback_handler	Callable | None	PrintingCallbackHandler	Receives streaming events during execution.
structured_output_model	type[BaseModel] | None	None	Pydantic model for structured responses.
session_manager	SessionManager | None	None	Persists conversation state across runs.
hooks	list | None	None	Lifecycle event hooks.
plugins	list | None	None	Plugin instances to extend functionality.
agent_id	str | None	"default"	Identifier for this agent (used in sessions and multi-agent).
name	str | None	"Elsai Agents"	Human-readable agent name.
description	str | None	None	What this agent does (used when wrapping as a tool).
state	AgentState | dict | None	AgentState()	Shared mutable state accessible to tools.
load_tools_from_directory	bool	False	Auto-load tools from ./tools/ with hot-reload.
tool_executor	ToolExecutor | None	ConcurrentToolExecutor	Controls how parallel tool calls are executed.
retry_strategy	ModelRetryStrategy | None	Default retry	Retry behaviour on transient errors.

Calling the agent

Natural language input

result = agent("What is the capital of France?")

Multi-modal input (images, documents)

import base64

with open("chart.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

result = agent([
    {"image": {"format": "png", "source": {"bytes": image_data}}},
    {"text": "Describe what this chart shows."}
])

Passing full messages

result = agent([
    {"role": "user", "content": [{"text": "Hello"}]},
    {"role": "assistant", "content": [{"text": "Hi there! How can I help?"}]},
    {"role": "user", "content": [{"text": "What did I just say?"}]},
])

Return value — AgentResult

Every agent call returns an AgentResult:

result = agent("Hello")

print(result.message)        # Final assistant message
print(result.stop_reason)    # "end_turn" | "max_tokens" | "tool_use" | "cancelled"
print(result.metrics)        # Token usage, latency
print(result.state)          # Agent state snapshot

Async usage

import asyncio
from elsai import Agent

agent = Agent()

async def main():
    result = await agent.invoke_async("Tell me a joke")
    print(result)

asyncio.run(main())

Cancellation

Cancel a running agent from another thread:

import threading
from elsai import Agent

agent = Agent()

def cancel_after(seconds):
    import time
    time.sleep(seconds)
    agent.cancel()

threading.Thread(target=cancel_after, args=(5,)).start()
result = agent("Do a very long task...")
print(result.stop_reason)  # "cancelled"

Agent identity

Give agents meaningful names and descriptions — required when using them as tools inside other agents:

from elsai import Agent

researcher = Agent(
    name="researcher",
    description="Searches the web and summarises findings on any topic.",
    agent_id="researcher-001",
)

Related

• Agent Loop — how the event loop works
• Hooks — lifecycle callbacks
• State — shared mutable state
• Structured Output — typed responses
• Streaming — real-time token streaming