OpenRouter

Use OpenRouter unified API with Agno agents.

OpenRouter is a platform for providing endpoints for Large Language models.

Authentication

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

Mac

export OPENROUTER_API_KEY=***

setx OPENROUTER_API_KEY ***

Example

Use OpenRouter with your Agent:

agent.py

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

agent = Agent(
    model=OpenRouter(id="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	"openai/gpt-4o-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
app_name	Optional[str]	"agno"	Application name for OpenRouter request headers

OpenRouter also supports the params of OpenAI.

Responses API

OpenRouter also supports the OpenAI Responses API (currently in beta). Use OpenRouterResponses for this interface:

agent.py

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")

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 will happen automatically using our OpenRouter model, when the used provider supports it. In other cases you can activate it via the cache_control header. You can read more about prompt caching with OpenRouter in their docs.