OpenRouter Responses

Interact with OpenRouter models using the OpenAI Responses API. OpenRouter's Responses API provides OpenAI-compatible access to multiple AI models through a unified interface.

Requirements

Set the OPENROUTER_API_KEY environment variable:

uv pip install -U agno openai
export OPENROUTER_API_KEY=your-api-key

Key Features

Unified Interface: Access multiple AI providers through a single API
Fallback Model Routing: Automatically try alternative models if the primary fails
Stateless API: Each request is independent (no server-side state persisted)
Reasoning Support: Enable reasoning for supported models

Parameters

Parameter	Type	Default	Description
`id`	`str`	`"openai/gpt-oss-20b"`	The ID of the OpenRouter model to use
`name`	`str`	`"OpenRouterResponses"`	The name of the model
`provider`	`str`	`"OpenRouter"`	The provider of the model
`api_key`	`Optional[str]`	`None`	The API key (defaults to `OPENROUTER_API_KEY` env var)
`base_url`	`str`	`"https://openrouter.ai/api/v1"`	The base URL for the OpenRouter API
`models`	`Optional[List[str]]`	`None`	Fallback model IDs for dynamic model routing when the primary model fails

OpenRouterResponses extends OpenResponses and inherits its constructor parameters. The OpenRouter Responses API is stateless: keep store=False and do not send a non-null previous_response_id. Inheritance does not add server-side response storage or chaining.

Usage

Basic Usage

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

With Reasoning

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

agent = Agent(
    model=OpenRouterResponses(
        id="openai/gpt-oss-20b",
        reasoning={"enabled": True},
    ),
    markdown=True,
)

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

Fallback Model Routing

If the primary model fails due to rate limits, timeouts, or unavailability, OpenRouter automatically tries the fallback models in order:

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

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

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