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 2026")
print(result)

Agent configuration with AgentConfig

Pass agent metadata and execution options through AgentConfig, not as direct Agent(...) keyword arguments:

from elsai import Agent
from elsai.agent import AgentConfig

agent = Agent(
    model="us.amazon.nova-pro-v1:0",
    system_prompt="You are a helpful assistant.",
    tools=[my_tool],
    config=AgentConfig(
        agent_id="assistant",
        name="My Agent",
        plugins=[my_plugin],
        hooks=[my_hook],
        session_manager=session,
    ),
)

See the full AgentConfig reference.

Deprecated kwargs

Direct keyword arguments such as Agent(plugins=[...]), Agent(hooks=[...]), or Agent(agent_id=..., session_manager=...) still work but emit a deprecation warning. Use AgentConfig in new code.

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.
load_tools_from_directory	bool	False	Auto-load tools from ./tools/ with hot-reload.
config	AgentConfig | None	None	Agent metadata and execution options — see table below.

AgentConfig fields

Field	Description
agent_id	Identifier for sessions and multi-agent (default "default").
name	Human-readable agent name.
description	What this agent does (used when wrapping as a tool).
state	Initial shared mutable state accessible to tools.
plugins	Plugin instances to extend functionality.
hooks	Lifecycle event hooks.
session_manager	Persists conversation state across runs.
retry_strategy	Retry behaviour on transient errors.
tool_executor	Controls how parallel tool calls are executed.
limits	Default per-invocation budget caps (turns, output_tokens, total_tokens) — see Invocation Limits.
sandbox	Shared Sandbox workspace for isolated execution — see Sandbox API.

For isolated shell and file execution, see Sandbox instead of host prebuilt tools alone.

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" | "limit_turns" | "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
from elsai.agent import AgentConfig

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

Related

• Sandbox — isolated workspace execution
• Agent Loop — how the event loop works
• Invocation Limits — per-call turn and token caps
• Hooks — lifecycle callbacks
• State — shared mutable state
• Structured Output — typed responses
• Streaming — real-time token streaming