OpenRouter Responses

Interact with OpenRouter models using the OpenAI Responses API. OpenRouter’s Responses API (currently in beta) provides OpenAI-compatible access to multiple AI models through a unified interface.

Requirements

Set the OPENROUTER_API_KEY environment variable:

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	List of fallback model IDs for automatic retry
store	Optional[bool]	False	Whether to store responses

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-oss-20b",
            "openai/gpt-4o",
        ],
    ),
    markdown=True,
)

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

Developer Resources

• OpenRouter Responses API Documentation
• OpenRouter Model Routing
• OpenRouter (Chat Completion API)