Building Agents

Build production-ready AI agents with Agentor: configure models, attach tools, add instructions, handle streaming responses, and serve them as APIs.

Agentor makes it easy to build AI agents with tool access, model flexibility, and production-ready features. This guide covers everything from basic agent creation to advanced patterns.

Quick Start

Create your first agent in just a few lines:

from agentor import Agentor

agent = Agentor(
    name="Weather Agent",
    model="gpt-5-mini",
    instructions="You are a helpful weather assistant."
)

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

Core Concepts

Agent Configuration

Every agent has three key components:

• name: Identifies your agent
• model: The LLM to use (supports any LiteLLM model)
• instructions: System prompt that defines agent behavior

agent = Agentor(
    name="Research Assistant",
    model="anthropic/claude-3.5-sonnet",
    instructions="You are a research assistant that provides detailed, well-sourced answers.",
    api_key="your-api-key"  # Optional: model-specific API key
)

Model Selection

A bare name goes to OpenAI. A provider/model-name string is routed through LiteLLM:

# OpenAI models
agent = Agentor(name="Agent", model="gpt-5-mini")
agent = Agentor(name="Agent", model="gpt-4o")

# Anthropic models
agent = Agentor(name="Agent", model="anthropic/claude-sonnet-4-5")

# Google models
agent = Agentor(name="Agent", model="gemini/gemini-2.5-flash")

To reach a provider directly over its OpenAI-compatible endpoint, set base_url. The model string is then passed through as that provider spells it:

import os

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

See Model providers for endpoints and the routing rules.

Model Settings

Customize model behavior with ModelSettings:

from agentor import Agentor, ModelSettings

model_settings = ModelSettings(
    temperature=0.7,
    max_tokens=2000,
    top_p=0.9
)

agent = Agentor(
    name="Creative Writer",
    model="gpt-5-mini",
    model_settings=model_settings
)

Running Agents

Synchronous Execution

For simple, blocking execution:

result = agent.run("Explain quantum computing in simple terms")
print(result)

Async Execution

For better performance and concurrent operations:

import asyncio

async def main():
    result = await agent.arun("What is the capital of France?")
    print(result.final_output)

asyncio.run(main())

Batch Processing

Process multiple prompts concurrently:

import asyncio
from agentor import Agentor

async def main():
    agent = Agentor(name="Assistant", model="gpt-5-mini")
    
    prompts = [
        "What is the weather in London?",
        "What is the weather in Paris?",
        "What is the weather in Tokyo?"
    ]
    
    # Process all prompts concurrently with controlled concurrency
    results = await agent.arun(prompts, limit_concurrency=10)
    
    for result in results:
        print(result.final_output)

asyncio.run(main())

Conversation Context

Maintain conversation history with message format:

messages = [
    {"role": "user", "content": "Hello, I need help with Python."},
    {"role": "assistant", "content": "I'd be happy to help! What do you need?"},
    {"role": "user", "content": "How do I read a file?"}
]

result = await agent.arun(messages)

Agent from Markdown

Create agents from markdown files with frontmatter:

---
name: WeatherBot
tools: [get_weather]
model: gpt-4o-mini
temperature: 0.3
---
You are a concise weather assistant. Always provide temperature in Celsius.

Load the agent:

from agentor import Agentor

agent = Agentor.from_md("weatherbot.md")
result = agent.run("What's the weather in Paris?")

Advanced Features

Fallback Models

Automatically retry with fallback models on rate limits or errors:

result = await agent.arun(
    "Complex task here",
    fallback_models=["gpt-4o-mini", "anthropic/claude-3-haiku"]
)

Structured Outputs

Get typed responses with Pydantic models:

from pydantic import BaseModel

class WeatherResponse(BaseModel):
    location: str
    temperature: float
    conditions: str
    humidity: int

agent = Agentor(
    name="Weather Agent",
    model="gpt-5-mini",
    output_type=WeatherResponse
)

result = agent.run("What's the weather in London?")
print(result.final_output.temperature)  # final_output is a WeatherResponse

Open-ended map fields such as dict[str, int] are rejected when the agent is built — strict structured output cannot describe them. See Structured output for the workarounds.

Durable Runs

Give the agent a store and every step is written to disk, so another process can finish an interrupted run:

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

agent = Agentor(name="Weather Agent", model="gpt-5-mini", store=FileStore("runs"))

result = agent.run("What is the weather in London?")
agent.resume(result.run_id)   # picks up where a crash left off

See Durable runs for stores, limits, and the resume semantics.

Agent Skills

Skills are folders of instructions and scripts that agents load dynamically:

from agentor import Agentor
from agentor.tools import ShellTool

agent = Agentor(
    name="Assistant",
    model="gemini/gemini-2-flash-preview",
    instructions="Your job is to create GIFs. Lean on skills and tools.",
    skills=[".skills/slack-gif-creator"],
    tools=[ShellTool()]
)

result = await agent.arun("Create a cat gif")

Skill folder structure:

example-skill/
├── SKILL.md        # Required: instructions + metadata
├── scripts/        # Optional: helper scripts
├── assets/         # Optional: templates/resources  
└── references/     # Optional: docs or checklists

Thinking Mode

Get the agent’s reasoning process:

result = agent.think("Should I invest in cryptocurrency?")
print(result.final_output)

Best Practices

Next Steps

• Learn how to add custom tools to your agents
• Set up streaming responses for real-time output
• Serve your agent as an API
• Enable observability for production monitoring