agentroute (Python SDK)

Build, deploy, and monetize AI agents. Phase 2 ships Agent with tools, persistent memory, conversation-history policies, and structured output — all against any OpenAI-compatible model (OpenRouter default, plus Ollama and custom HTTP endpoints).

Install

pip install agentroute

Quick start

Layer 0 — three-line hello world

from agentroute import Agent

agent = Agent("my-bot", model="claude-sonnet-4")
print(agent.run("Tell me a joke"))

Set AGENTROUTE_API_KEY (or OPENROUTER_API_KEY) to an OpenRouter key. One key works for every model string (claude-sonnet-4, gpt-4o, gemini-2.0-flash, deepseek-v3, ...).

Layer 1 — add a tool

from agentroute import Agent

agent = Agent("weather-bot", model="claude-sonnet-4")

@agent.tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return "Sunny, 22C"

print(agent.run("What's the weather in Zurich?"))

Memory (conversation + facts)

from agentroute import Agent, Memory, MemorySQLite

# In-RAM (lost on restart):
agent = Agent("bot", model="claude-sonnet-4", memory=Memory())

# Persistent (SQLite + FTS5 search):
agent = Agent("bot", model="claude-sonnet-4", memory=MemorySQLite("agent.db"))

agent.run("remember my favorite color is blue")
agent.run("what is my favorite color?")  # remembers across runs

History policies

from agentroute import Agent, MemorySQLite, HistorySlidingWindow

agent = Agent(
    "bot",
    model="claude-sonnet-4",
    memory=MemorySQLite("agent.db"),
    history=HistorySlidingWindow(20),  # keep last 20 user-turn groups
)

Also available: HistoryTruncate(max_tokens=100_000) and HistorySummarize(model=...).

Structured output

from agentroute import Agent, Retry
from pydantic import BaseModel

class WeatherReport(BaseModel):
    city: str
    temp_c: float

agent = Agent("bot", model="claude-sonnet-4", output=WeatherReport)

@agent.output_validator
def sanity(ctx, output: WeatherReport) -> WeatherReport:
    if output.temp_c > 60:
        raise Retry("Temperature unrealistic, reconsider.")
    return output

result = agent.run("Weather in Zurich?")
print(result.output.city, result.output.temp_c)

Async

import asyncio
from agentroute import Agent

async def main() -> None:
    agent = Agent("bot", model="claude-sonnet-4")
    result = await agent.arun("hi")
    print(result.output)

asyncio.run(main())

Local models (Ollama)

agent = Agent("local", model="ollama/llama3")
print(agent.run("hi"))

Development

cd packages/python
pip install -e '.[dev]'
pytest                 # unit tests (integration tests auto-skipped)
pytest -m integration  # integration tests (mocked + live)
ruff check src tests
mypy src/agentroute

Phase 2 scope: Agent, Tool, Context, Result, Event, ModelCloud, resolve_model(), Config, exceptions (ErrorAgent, ErrorMaxTurns, ErrorBudget, Retry), Memory, MemorySQLite, HistorySlidingWindow, HistorySummarize, HistoryTruncate, structured output with validators. Multi-agent (Team/Company), guards, MCP, A2A, and deployment land in later phases.