Installation

The AgentRoute SDK is a single Python package. Install it, point it at a model with one API key, and you have a working agent. This page covers the install, key configuration, and a verification run.

Requirements

AgentRoute requires Python 3.10 or newer. It depends only on pydantic, httpx, docstring-parser, and typing-extensions, so it installs cleanly into any virtual environment.

Check your Python version

Run python --version (or python3 --version) and confirm it reports 3.10 or higher before installing.

AgentRoute talks to models through OpenRouter by default, so you need one OpenRouter key. Create a key in the OpenRouter dashboard, then expose it as an environment variable. AgentRoute reads AGENTROUTE_API_KEY first, then falls back to OPENROUTER_API_KEY.

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

If you prefer not to set an environment variable, write the key to ~/.agentroute/config instead. It is a simple key=value file (# starts a comment), and the environment variable always takes precedence over it.

~/.agentroute/config

api_key=sk-or-...

Verify with a hello world

Save this to a file and run it. If it prints a response, your install and key are working.

hello.py

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

python hello.py
# Why don't scientists trust atoms? Because they make up everything.

One key, every model

A single OpenRouter key works for every model string. Swap the model= argument for gpt-4o, gemini-2.0-flash, deepseek-v3, or any other supported model without changing a line of config. For a bare name like claude-sonnet-4, AgentRoute infers the vendor prefix for you.

Resolving API keys

When you create an Agent, the key is resolved in this order:

An explicit api_key= argument passed to the Agent constructor.
The environment variables AGENTROUTE_API_KEY, then OPENROUTER_API_KEY.
The ~/.agentroute/config file.
None for endpoints that need no auth, such as local Ollama models.

This means you can keep keys out of source by relying on the environment in production, while still passing api_key= directly in a quick script or notebook.

from agentroute import Agent
 
# Explicit key wins over the environment and config file.
agent = Agent("my-bot", model="claude-sonnet-4", api_key="sk-or-...")

Local models with Ollama

You do not need an OpenRouter key to run models locally. Prefix the model string with ollama/ and AgentRoute routes to http://localhost:11434/v1 with no auth required.

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

See Models for the full set of resolution rules, including custom OpenAI-compatible HTTP endpoints.

Next steps

Quickstart

Build an agent with a tool, memory, and structured output in a few minutes.

Agents

Learn how the agentic loop works and what every Agent option does.