> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
Agentor 0.1.0 is a prerelease, so ask for it with `--pre`:
```bash theme={null} theme={null}
pip install --pre agentor
```
Plain `pip install agentor` gives you the stable 0.0.x line instead. See [Installation](/agentor/installation) for the difference.
Set your LLM provider API key as an environment variable:
```bash theme={null} theme={null}
# 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:
```python theme={null} theme={null}
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:
```python theme={null} theme={null}
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:
```python theme={null} theme={null}
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:
```python theme={null} theme={null}
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:
```python theme={null} theme={null}
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:
```bash theme={null} theme={null}
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:
The CLI is included with Agentor:
```bash theme={null} theme={null}
celesto --version
```
Save your agent code to a Python file (e.g., `agent.py`):
```python theme={null} theme={null}
from agentor import Agentor
agent = Agentor(
name="Weather Agent",
model="gpt-4o-mini",
tools=["get_weather"]
)
if __name__ == "__main__":
agent.serve()
```
`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](/agentor/deploy).
```bash theme={null} theme={null}
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:
```python OpenAI theme={null} theme={null}
from agentor import Agentor
agent = Agentor(
name="My Agent",
model="gpt-4o-mini", # or gpt-4o, gpt-5-mini
tools=["get_weather"]
)
```
```python Anthropic theme={null} theme={null}
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"]
)
```
```python Google theme={null} theme={null}
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"]
)
```
```python OpenRouter theme={null} theme={null}
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](/agentor/model-providers) for endpoints.
## Get typed output
Ask for a shape instead of prose and you get a validated Python object back:
```python theme={null} theme={null}
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:
```python theme={null} theme={null}
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)
```
## Configure model parameters
Fine-tune model behavior with `ModelSettings`:
```python theme={null} theme={null}
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:
Learn advanced agent patterns and best practices
Create custom tools for your agents
Save runs and resume them after a crash
Return validated objects instead of free text
Build MCP servers with LiteMCP
Enable agent-to-agent communication with A2A protocol