feat(models): add native OpenRouter support

Author: abhishekbhakat

docs/api/models/openrouter.md

@@ -0,0 +1,7 @@
+# `pydantic_ai.models.openrouter`
+
+## Setup
+
+For details on how to set up authentication with this model, see [model configuration for OpenRouter](../../models/openrouter.md).
+
+::: pydantic_ai.models.openrouter

docs/models/openai.md

@@ -394,9 +394,10 @@ agent = Agent(model)
 
 ### OpenRouter
 
-To use [OpenRouter](https://openrouter.ai), first create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).
+[OpenRouter](https://openrouter.ai) now has dedicated support in PydanticAI with the [`OpenRouterModel`][pydantic_ai.models.openrouter.OpenRouterModel].
+For detailed documentation and examples, see the [OpenRouter documentation](openrouter.md).
 
-Once you have the API key, you can use it with the [`OpenRouterProvider`][pydantic_ai.providers.openrouter.OpenRouterProvider]:
+You can also still use OpenRouter through the OpenAI-compatible interface:
 
 ```python
 from pydantic_ai import Agent

docs/models/openrouter.md

@@ -0,0 +1,106 @@
+# OpenRouter
+
+## Install
+
+To use `OpenRouterModel`, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `openrouter` optional group:
+
+```bash
+pip/uv-add "pydantic-ai-slim[openrouter]"
+```
+
+## Configuration
+
+To use [OpenRouter](https://openrouter.ai/) through their API, go to [openrouter.ai/keys](https://openrouter.ai/keys) and follow your nose until you find the place to generate an API key.
+
+`OpenRouterModelName` contains a list of available OpenRouter models.
+
+## Environment variable
+
+Once you have the API key, you can set it as an environment variable:
+
+```bash
+export OPENROUTER_API_KEY='your-api-key'
+```
+
+You can then use `OpenRouterModel` by name:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+
+model = OpenRouterModel('google/gemini-2.5-flash-lite', api_key='your-api-key')
+agent = Agent(model)
+...
+```
+
+Or initialise the model directly with just the model name:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+
+model = OpenRouterModel('google/gemini-2.5-flash-lite')
+agent = Agent(model)
+...
+```
+
+## Custom API Key
+
+You can provide a custom API key directly to the model:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+
+model = OpenRouterModel(
+    'google/gemini-2.5-flash-lite', api_key='your-api-key'
+)
+agent = Agent(model)
+...
+```
+
+## Custom HTTP Client
+
+You can customize the OpenRouter model with a custom `httpx.AsyncClient`:
+
+```python
+from httpx import AsyncClient
+
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+
+custom_http_client = AsyncClient(timeout=30)
+model = OpenRouterModel(
+    'google/gemini-2.5-flash-lite',
+    api_key='your-api-key',
+    http_client=custom_http_client,
+)
+agent = Agent(model)
+...
+```
+
+## Structured Output
+
+You can use OpenRouter models with structured output by providing a Pydantic model as the `output_type`:
+
+```python {noqa="I001"}
+from pydantic import BaseModel
+
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+
+class OlympicsLocation(BaseModel):
+    city: str
+    country: str
+
+model = OpenRouterModel('google/gemini-2.5-flash-lite', api_key='your-api-key')
+agent = Agent(model, output_type=OlympicsLocation)
+
+result = agent.run_sync('Where were the olympics held in 2012?')
+print(f'City: {result.output.city}')
+#> City: London
+print(f'Country: {result.output.country}')
+#> Country: United Kingdom
+```
+
+The model will validate and parse the response into your specified Pydantic model, allowing type-safe access to structured data fields via `result.output.field_name`.

docs/models/overview.md

@@ -10,6 +10,7 @@ Pydantic AI is model-agnostic and has built-in support for multiple model provid
 * [Cohere](cohere.md)
 * [Bedrock](bedrock.md)
 * [Hugging Face](huggingface.md)
+* [OpenRouter](openrouter.md)
 
 ## OpenAI-compatible Providers
 
@@ -18,7 +19,6 @@ In addition, many providers are compatible with the OpenAI API, and can be used
 - [DeepSeek](openai.md#deepseek)
 - [Grok (xAI)](openai.md#grok-xai)
 - [Ollama](openai.md#ollama)
-- [OpenRouter](openai.md#openrouter)
 - [Vercel AI Gateway](openai.md#vercel-ai-gateway)
 - [Perplexity](openai.md#perplexity)
 - [Fireworks AI](openai.md#fireworks-ai)

mkdocs.yml

@@ -34,6 +34,7 @@ nav:
           - models/groq.md
           - models/mistral.md
           - models/huggingface.md
+          - models/openrouter.md
       - Tools & Toolsets:
           - tools.md
           - tools-advanced.md
@@ -123,6 +124,7 @@ nav:
           - api/models/huggingface.md
           - api/models/instrumented.md
           - api/models/mistral.md
+          - api/models/openrouter.md
           - api/models/test.md
           - api/models/function.md
           - api/models/fallback.md

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -1119,7 +1119,8 @@ async def _process_message_history(
 
         if is_async_callable(processor):
             if takes_ctx:
-                messages = await processor(run_context, messages)
+                async_processor_with_ctx = cast(_HistoryProcessorAsyncWithCtx[DepsT], processor)
+                messages = await async_processor_with_ctx(run_context, messages)
             else:
                 async_processor = cast(_HistoryProcessorAsync, processor)
                 messages = await async_processor(messages)

pydantic_ai_slim/pydantic_ai/_utils.py

@@ -5,6 +5,7 @@
 import inspect
 import re
 import time
+import types
 import uuid
 from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable, Iterator
 from contextlib import asynccontextmanager, suppress
@@ -14,12 +15,21 @@
 from types import GenericAlias
 from typing import TYPE_CHECKING, Any, Generic, TypeAlias, TypeGuard, TypeVar, get_args, get_origin, overload
 
+__all__ = [
+    'guard_tool_call_id',
+    'now_utc',
+    'number_to_datetime',
+    'PeekableAsyncStream',
+    'Unset',
+]
+
+from typing import Literal
+
 from anyio.to_thread import run_sync
 from pydantic import BaseModel, TypeAdapter
 from pydantic.json_schema import JsonSchemaValue
 from typing_extensions import (
     ParamSpec,
-    TypeIs,
     is_typeddict,
 )
 from typing_inspection import typing_objects
@@ -47,21 +57,24 @@ async def run_in_executor(func: Callable[_P, _R], *args: _P.args, **kwargs: _P.k
     return await run_sync(wrapped_func)
 
 
+def _is_class_type(obj: Any) -> TypeGuard[type[Any]]:
+    return isinstance(obj, type) and not isinstance(obj, GenericAlias)
+
+
 def is_model_like(type_: Any) -> bool:
     """Check if something is a pydantic model, dataclass or typedict.
 
     These should all generate a JSON Schema with `{"type": "object"}` and therefore be usable directly as
     function parameters.
     """
+    if not _is_class_type(type_):
+        return False
+
     return (
-        isinstance(type_, type)
-        and not isinstance(type_, GenericAlias)
-        and (
-            issubclass(type_, BaseModel)
-            or is_dataclass(type_)  # pyright: ignore[reportUnknownArgumentType]
-            or is_typeddict(type_)  # pyright: ignore[reportUnknownArgumentType]
-            or getattr(type_, '__is_model_like__', False)  # pyright: ignore[reportUnknownArgumentType]
-        )
+        issubclass(type_, BaseModel)
+        or is_dataclass(type_)
+        or is_typeddict(type_)
+        or getattr(type_, '__is_model_like__', False)
     )
 
 
@@ -311,7 +324,7 @@ async def __anext__(self) -> T:
 
 
 def get_traceparent(x: AgentRun | AgentRunResult | GraphRun | GraphRunResult) -> str:
-    return x._traceparent(required=False) or ''  # type: ignore[reportPrivateUsage]
+    return x._traceparent(required=False) or ''  # pyright: ignore[reportPrivateUsage]
 
 
 def dataclasses_no_defaults_repr(self: Any) -> str:
@@ -333,14 +346,14 @@ def number_to_datetime(x: int | float) -> datetime:
 
 
 @overload
-def is_async_callable(obj: AwaitableCallable[T]) -> TypeIs[AwaitableCallable[T]]: ...
+def is_async_callable(obj: AwaitableCallable[T]) -> Literal[True]: ...
 
 
 @overload
-def is_async_callable(obj: Any) -> TypeIs[AwaitableCallable[Any]]: ...
+def is_async_callable(obj: Any) -> bool: ...
 
 
-def is_async_callable(obj: Any) -> Any:
+def is_async_callable(obj: Any) -> bool:
     """Correctly check if a callable is async.
 
     This function was copied from Starlette:
@@ -349,7 +362,23 @@ def is_async_callable(obj: Any) -> Any:
     while isinstance(obj, functools.partial):
         obj = obj.func
 
-    return inspect.iscoroutinefunction(obj) or (callable(obj) and inspect.iscoroutinefunction(obj.__call__))  # type: ignore
+    # Case 1: Direct check if obj itself is a coroutine function
+    if inspect.iscoroutinefunction(obj):
+        return True
+
+    # Case 2: If obj is callable, check its __call__ method
+    if callable(obj):
+        call_method = getattr(obj, '__call__', None)
+        if call_method is None:
+            return False
+
+        if isinstance(call_method, types.MethodType):
+            call_method = call_method.__func__
+
+        if isinstance(call_method, types.FunctionType) and inspect.iscoroutinefunction(call_method):
+            return True
+
+    return False
 
 
 def _update_mapped_json_schema_refs(s: dict[str, Any], name_mapping: dict[str, str]) -> None:

pydantic_ai_slim/pydantic_ai/ag_ui.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import uuid
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Mapping, Sequence
@@ -24,7 +25,6 @@
 
 from pydantic import BaseModel, ValidationError
 
-from . import _utils
 from ._agent_graph import CallToolsNode, ModelRequestNode
 from .agent import AbstractAgent, AgentRun, AgentRunResult
 from .exceptions import UserError
@@ -378,10 +378,9 @@ async def run_ag_ui(
                 yield encoder.encode(event)
 
         if on_complete is not None and run.result is not None:
-            if _utils.is_async_callable(on_complete):
-                await on_complete(run.result)
-            else:
-                await _utils.run_in_executor(on_complete, run.result)
+            result = on_complete(run.result)
+            if asyncio.iscoroutine(result):
+                await result
     except _RunError as e:
         yield encoder.encode(
             RunErrorEvent(message=e.message, code=e.code),