Build your first AI agent with Agentor

Build your first AI agent with Agentor in under five minutes — install the framework, write a weather agent, attach tools, and run your first query.

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

1. Install Agentor

   pip install agentor
   
2. 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:

1. Install the Celesto CLI

   The CLI is included with Agentor:

   celesto --version
   
2. 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()
   
3. 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:

OpenAI

from agentor import Agentor

agent = Agentor(
    name="My Agent",
    model="gpt-4o-mini",  # or gpt-4o, gpt-5-mini
    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