Quickstart

AgentRoute is published to PyPI. Install it into your project with pip (Python 3.11+).

pip install agentroute

The default backend is OpenRouter. Export an OpenRouter key as AGENTROUTE_API_KEY (or OPENROUTER_API_KEY) and it works for every model string.

export AGENTROUTE_API_KEY="sk-or-..."

Construct an Agent with a name and a model, then call run with a prompt. run is synchronous — it drives the full agentic loop and returns a Result.

from agentroute import Agent
 
agent = Agent("my-bot", model="claude-sonnet-4")
print(agent.run("Tell me a joke"))
# Why did the developer go broke? Because they used up all their cache.

Result.__str__ returns the text output, so print(agent.run(...)) shows the answer directly. To work with the value, read result.output.

run is a thin wrapper around the async arun. Inside an event loop, call arun directly and await it. Use result.output to get the model's text.

import asyncio
from agentroute import Agent
 
async def main() -> None:
    agent = Agent("my-bot", model="claude-sonnet-4")
    result = await agent.arun("Tell me a joke")
    print(result.output)
 
asyncio.run(main())

Register a Python function as a tool with the @agent.tool decorator. The agent reads the function's type hints and docstring to build the schema the model sees, then calls the function when it decides the tool is useful and feeds the result back into the loop.

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?"))
# It's currently sunny and 22C in Zurich.

When the prompt mentions a city, the model emits a tool call, AgentRoute runs get_weather("Zurich"), returns "Sunny, 22C" to the model, and the model writes the final answer. Sync tool functions run on a worker thread so they never block the loop; async def tools are awaited.