OpenRouter | Agno

OpenRouter is a platform providing endpoints for Large Language Models.

Authentication

Set your OPENROUTER_API_KEY environment variable. Get your key from here.

export OPENROUTER_API_KEY=***

Example

Install the openai package:

uv pip install -U agno openai

Use OpenRouter with your Agent:

from agno.agent import Agent
from agno.models.openrouter import OpenRouter

agent = Agent(
    model=OpenRouter(id="openai/gpt-5-mini"),
    markdown=True
)

# Print the response in the terminal
agent.print_response("Share a 2 sentence horror story.")

Params

Parameter	Type	Default	Description
`id`	`str`	`"gpt-5.4-mini"`	The id of the OpenRouter model to use
`name`	`str`	`"OpenRouter"`	The name of the model
`provider`	`str`	`"OpenRouter"`	The provider of the model
`api_key`	`Optional[str]`	`None`	The API key for OpenRouter (defaults to OPENROUTER_API_KEY env var)
`base_url`	`str`	`"https://openrouter.ai/api/v1"`	The base URL for the OpenRouter API
`max_tokens`	`int`	`1024`	The maximum number of tokens to generate
`models`	`Optional[List[str]]`	`None`	Fallback model IDs tried in order if the primary model fails

The table records literal SDK defaults. For requests, set an explicit provider-qualified model ID, such as openai/gpt-5-mini, from the current OpenRouter catalog.

OpenRouter also supports the params of OpenAI.

Responses API

OpenRouter also provides an OpenAI-compatible Responses API. Use OpenRouterResponses for this interface:

from agno.agent import Agent
from agno.models.openrouter import OpenRouterResponses

agent = Agent(
    model=OpenRouterResponses(id="openai/gpt-oss-20b"),
    markdown=True,
)

agent.print_response("Share a 2 sentence horror story")

OpenRouter's Responses API is stateless: send the needed conversation history with each request. store=true and a non-null previous_response_id are rejected with 400. Agno's adapter defaults to store=False; use Agno-managed session history for ongoing conversations.

Fallback Model Routing

OpenRouterResponses supports automatic fallback to alternative models if the primary model fails:

from agno.agent import Agent
from agno.models.openrouter import OpenRouterResponses

agent = Agent(
    model=OpenRouterResponses(
        id="openai/gpt-oss-20b",
        models=["openai/gpt-oss-20b", "openai/gpt-4o"],
    ),
    markdown=True,
)

agent.print_response("Write a haiku about coding", stream=True)

See OpenRouterResponses reference for full parameters.

Prompt caching

Prompt caching depends on the selected model and provider. Some cache automatically; others require cache-control settings and minimum prompt sizes. Anthropic supports top-level automatic cache control and explicit content-block breakpoints, with different options for Chat Completions and Responses. Adding a field cannot enable caching on an unsupported provider. Follow OpenRouter's provider-specific caching guide.