Quickstart

Build your first elsai agent in under 5 minutes.

Step 1 — Install

pip install --extra-index-url https://elsai-agents.elsai.ai/root/ elsai-agents==0.3.1
pip install --extra-index-url https://core-packages.elsai.ai/root/ "elsai-model[bedrock]==2.1.0"

For OpenAI instead of Bedrock, use "elsai-model[openai]==2.1.0" and pass an OpenAIModel in Step 5 — see Model Providers.

Step 2 — Create your first agent

Default model is Amazon Bedrock

Agent() with no model= uses Amazon Bedrock (global.anthropic.claude-sonnet-4-6 in us-west-2). Configure AWS credentials before running:

aws configure
# or:
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-west-2

To use another provider, skip ahead to Step 5 or Model Providers.

from elsai import Agent

agent = Agent()
result = agent("What is the capital of India?")
print(result)

The agent sends your message to the model and returns a natural-language response.

Step 3 — Build a custom tool

Add your own Python function as a tool using the @tool decorator:

from elsai import Agent, tool

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city.

    Args:
        city: The name of the city to get weather for.

    Returns:
        A description of current weather conditions.
    """
    # In a real app, call a weather API here
    return f"It's sunny and 72°F in {city}."

agent = Agent(tools=[get_weather])
result = agent("What's the weather like in Tokyo?")
print(result)

Step 4 — Add a system prompt

Guide the agent's behavior with a system prompt:

from elsai import Agent

agent = Agent(
    system_prompt="You are a helpful Python coding assistant. "
                  "Always provide complete, runnable code examples."
)
result = agent("Write a function that reverses a string")
print(result)

Step 5 — Configure a model

Pass a model instance from elsai-model to Agent (for example, Claude on Amazon Bedrock). Requires "elsai-model[bedrock]==2.1.0" from Step 1 and AWS credentials.

from elsai import Agent
from elsai_model.bedrock import BedrockModel

model = BedrockModel(
    model_id="global.anthropic.claude-sonnet-4-6",
    region_name="us-west-2",
)

agent = Agent(model=model, system_prompt="You are a concise assistant.")
result = agent("Explain machine learning in one sentence")
print(result)

Step 6 — Stream responses

Get tokens as they're generated (same Bedrock default / AWS requirement as Step 2):

import asyncio
from elsai import Agent

agent = Agent()

async def stream():
    async for event in agent.stream_async("Tell me a short story"):
        if "data" in event:
            print(event["data"], end="", flush=True)

asyncio.run(stream())

Step 7 — Multi-turn conversation

Agents maintain conversation history automatically:

from elsai import Agent

agent = Agent()

agent("My name is Alice and I'm a software engineer.")
agent("What do you know about me?")
# → "Your name is Alice and you're a software engineer."

What's next?

• Core Concepts — understand how agents work
• Tools — build powerful tools
• Model Providers — configure your preferred LLM
• Multi-Agent — orchestrate multiple agents