Build your first AI agent with Agentor

Get up and running with Agentor by building a simple weather agent and then exploring more advanced features.

Prerequisites

Before starting, make sure you have:

Python 3.11 or higher installed
An API key for an LLM provider (OpenAI, Anthropic, or Google)

Installation

Install Agentor

pip install agentor

Set up your API key

Set your LLM provider API key as an environment variable:

# For OpenAI
export OPENAI_API_KEY="your-api-key-here"

# For Anthropic
export ANTHROPIC_API_KEY="your-api-key-here"

# For Google
export GEMINI_API_KEY="your-api-key-here"

Build your first agent

Create a simple weather agent that can answer questions about the weather:

from agentor import Agentor

agent = Agentor(
    name="Weather Agent",
    model="gpt-4o-mini",
    tools=["get_weather"]
)

# Run the agent
result = agent.run("What is the weather in London?")
print(result)

The get_weather tool is a built-in tool that uses the WeatherAPI.com service. You’ll need to set the WEATHER_API_KEY environment variable to use it.

Run with streaming

See agent responses in real-time with streaming:

import asyncio
from agentor import Agentor

agent = Agentor(
    name="Weather Agent",
    model="gpt-4o-mini",
    tools=["get_weather"]
)

async def main():
    async for event in agent.stream_chat("What is the weather in Tokyo?"):
        print(event, flush=True)

asyncio.run(main())

Add custom instructions

Guide your agent’s behavior with custom instructions:

from agentor import Agentor

agent = Agentor(
    name="Weather Bot",
    model="gpt-4o-mini",
    instructions="You are a friendly weather assistant. Always include temperature in both Celsius and Fahrenheit.",
    tools=["get_weather"]
)

result = agent.run("How's the weather in Paris?")
print(result)

Use multiple tools

Combine multiple tools to create more capable agents:

from agentor import Agentor, function_tool

@function_tool
def calculate_temperature_diff(temp1: float, temp2: float) -> str:
    """Calculate the temperature difference between two values."""
    diff = abs(temp1 - temp2)
    return f"The temperature difference is {diff}°F"

agent = Agentor(
    name="Weather Analyzer",
    model="gpt-4o-mini",
    tools=["get_weather", calculate_temperature_diff]
)

result = agent.run("What's the temperature difference between London and Paris?")
print(result)

Serve as an API

Turn your agent into a REST API with a single line:

from agentor import Agentor

agent = Agentor(
    name="Weather Agent",
    model="gpt-4o-mini",
    tools=["get_weather"]
)

# Serve the agent on port 8000
agent.serve(port=8000)

This creates a FastAPI server with these endpoints:

POST /chat - Send messages to the agent
GET /.well-known/agent-card.json - A2A protocol agent card

Query the API

Use curl to interact with your agent API:

curl -X 'POST' \
  'http://localhost:8000/chat' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "input": "What is the weather in London?"
}'

Deploy to production

Deploy your agent to Celesto AI’s serverless platform:

Install the Celesto CLI

The CLI is included with Agentor:

celesto --version

Create your agent file

Save your agent code to a Python file (e.g., agent.py):

from agentor import Agentor

agent = Agentor(
    name="Weather Agent",
    model="gpt-4o-mini",
    tools=["get_weather"]
)

if __name__ == "__main__":
    agent.serve()

Serve it

serve() runs an ordinary ASGI app under uvicorn, so host it the way you host any other Python service - a container, a process manager, or a serverless runtime. See Serve agents as an API.

python weather_agent.py

http://localhost:8000/chat

Use different LLM providers

Swap the model string, or point base_url at any OpenAI-compatible endpoint:

from agentor import Agentor

agent = Agentor(
    name="My Agent",
    model="gpt-4o-mini",  # or gpt-4o, gpt-5-mini
    tools=["get_weather"]
)

import os
from agentor import Agentor

agent = Agentor(
    name="My Agent",
    model="anthropic/claude-sonnet-4-5",
    api_key=os.environ["ANTHROPIC_API_KEY"],
    tools=["get_weather"]
)

import os
from agentor import Agentor

agent = Agentor(
    name="My Agent",
    model="gemini/gemini-2.5-flash",
    api_key=os.environ["GEMINI_API_KEY"],
    tools=["get_weather"]
)

import os
from agentor import Agentor

agent = Agentor(
    name="My Agent",
    model="openai/gpt-4o-mini",
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
    tools=["get_weather"]
)

Groq, Together, Fireworks, DeepSeek, vLLM, and Ollama all work the same way. See Model providers for endpoints.

Get typed output

Ask for a shape instead of prose and you get a validated Python object back:

from pydantic import BaseModel

from agentor import Agentor


class Report(BaseModel):
    city: str
    readings: list[int]


agent = Agentor(name="Reporter", model="gpt-4o-mini", output_type=Report)

result = agent.run("City: Berlin. Readings: 3, 5, 8. Return them.")
print(result.final_output.city)      # Berlin
print(sum(result.final_output.readings))  # 16

Survive a crash

Give the agent a store and every step is written to disk. A different process can finish the job from the run id alone:

from agentor import Agentor
from agentor.engine.store import FileStore

agent = Agentor(
    name="Weather Agent",
    model="gpt-4o-mini",
    tools=["get_weather"],
    store=FileStore("runs"),
)

result = agent.run("What is the weather in London?")
print(result.run_id)  # cabc9046ac5040298aa362c0d6d2c5c5

# later, anywhere:
agent.resume(result.run_id)

Branch a run

Fork any persisted run into a new, independent one — even a finished one, which resume() won’t re-run. The original is never touched:

variant = agent.fork(result.run_id, "How about Paris instead?")
print(variant.run_id)         # a new id — result.run_id is untouched
print(variant.final_output)

See Durable runs for what forking keeps and when to reach for it instead of resume().

Configure model parameters

Fine-tune model behavior with ModelSettings:

from agentor import Agentor, ModelSettings

agent = Agentor(
    name="Creative Writer",
    model="gpt-4o",
    model_settings=ModelSettings(
        temperature=0.9,  # More creative
        max_tokens=2000,
        top_p=0.95
    ),
    tools=[]
)

result = agent.run("Write a short story about a robot learning to paint")
print(result)

Next steps

Now that you’ve built your first agent, explore more advanced features:

Building agents

Learn advanced agent patterns and best practices

Custom tools

Create custom tools for your agents

Durable runs

Save runs, resume them after a crash, or fork them into new ones

Structured output

Return validated objects instead of free text

MCP servers

Build MCP servers with LiteMCP

Agent communication

Enable agent-to-agent communication with A2A protocol

Start Here

Build Agents

Concepts

Tool Use & MCP

Guides

SuperAuth

Build your first AI agent with Agentor

Prerequisites

Installation

Build your first agent

Run with streaming

Add custom instructions

Use multiple tools

Serve as an API

Query the API

Deploy to production

Use different LLM providers

Get typed output

Survive a crash

Branch a run

Configure model parameters

Next steps

Building agents

Custom tools

Durable runs

Structured output

MCP servers

Agent communication

​Prerequisites

​Installation

​Build your first agent

​Run with streaming

​Add custom instructions

​Use multiple tools

​Serve as an API

​Query the API

​Deploy to production

​Use different LLM providers

​Get typed output

​Survive a crash

​Branch a run

​Configure model parameters

​Next steps

Building agents

Custom tools

Durable runs

Structured output

MCP servers

Agent communication

Prerequisites

Installation

Build your first agent

Run with streaming

Add custom instructions

Use multiple tools

Serve as an API

Query the API

Deploy to production

Use different LLM providers

Get typed output

Survive a crash

Branch a run

Configure model parameters

Next steps