Merge branch 'main' into feat-anthropic-cache-all

Author: DouweM

Makefile

@@ -43,6 +43,7 @@ typecheck-pyright:
 .PHONY: typecheck-mypy
 typecheck-mypy:
 	uv run mypy
+	uv run mypy typings/ --strict
 
 .PHONY: typecheck
 typecheck: typecheck-pyright ## Run static type checking

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/builtin-tools.md

@@ -9,7 +9,7 @@ Pydantic AI supports the following built-in tools:
 - **[`WebSearchTool`][pydantic_ai.builtin_tools.WebSearchTool]**: Allows agents to search the web
 - **[`CodeExecutionTool`][pydantic_ai.builtin_tools.CodeExecutionTool]**: Enables agents to execute code in a secure environment
 - **[`ImageGenerationTool`][pydantic_ai.builtin_tools.ImageGenerationTool]**: Enables agents to generate images
-- **[`UrlContextTool`][pydantic_ai.builtin_tools.UrlContextTool]**: Enables agents to pull URL contents into their context
+- **[`WebFetchTool`][pydantic_ai.builtin_tools.WebFetchTool]**: Enables agents to fetch web pages
 - **[`MemoryTool`][pydantic_ai.builtin_tools.MemoryTool]**: Enables agents to use memory
 - **[`MCPServerTool`][pydantic_ai.builtin_tools.MCPServerTool]**: Enables agents to use remote MCP servers with communication handled by the model provider
 
@@ -306,18 +306,18 @@ For more details, check the [API documentation][pydantic_ai.builtin_tools.ImageG
 | `quality` | ✅ | ❌ |
 | `size` | ✅ | ❌ |
 
-## URL Context Tool
+## Web Fetch Tool
 
-The [`UrlContextTool`][pydantic_ai.builtin_tools.UrlContextTool] enables your agent to pull URL contents into its context,
+The [`WebFetchTool`][pydantic_ai.builtin_tools.WebFetchTool] enables your agent to pull URL contents into its context,
 allowing it to pull up-to-date information from the web.
 
 ### Provider Support
 
 | Provider | Supported | Notes |
 |----------|-----------|-------|
-| Google | ✅ | No [`BuiltinToolCallPart`][pydantic_ai.messages.BuiltinToolCallPart] or [`BuiltinToolReturnPart`][pydantic_ai.messages.BuiltinToolReturnPart] is currently generated; please submit an issue if you need this. Using built-in tools and function tools (including [output tools](output.md#tool-output)) at the same time is not supported; to use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
+| Anthropic | ✅ | Full feature support. Uses Anthropic's [Web Fetch Tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-fetch-tool) internally to retrieve URL contents. |
+| Google | ✅ | No parameter support. The limits are fixed at 20 URLs per request with a maximum of 34MB per URL. Using built-in tools and function tools (including [output tools](output.md#tool-output)) at the same time is not supported; to use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
 | OpenAI | ❌ | |
-| Anthropic | ❌ | |
 | Groq | ❌ | |
 | Bedrock | ❌ | |
 | Mistral | ❌ | |
@@ -327,10 +327,10 @@ allowing it to pull up-to-date information from the web.
 
 ### Usage
 
-```py {title="url_context_basic.py"}
-from pydantic_ai import Agent, UrlContextTool
+```py {title="web_fetch_basic.py"}
+from pydantic_ai import Agent, WebFetchTool
 
-agent = Agent('google-gla:gemini-2.5-flash', builtin_tools=[UrlContextTool()])
+agent = Agent('google-gla:gemini-2.5-flash', builtin_tools=[WebFetchTool()])
 
 result = agent.run_sync('What is this? https://ai.pydantic.dev')
 print(result.output)
@@ -339,6 +339,49 @@ print(result.output)
 
 _(This example is complete, it can be run "as is")_
 
+### Configuration Options
+
+The `WebFetchTool` supports several configuration parameters:
+
+```py {title="web_fetch_configured.py"}
+from pydantic_ai import Agent, WebFetchTool
+
+agent = Agent(
+    'anthropic:claude-sonnet-4-0',
+    builtin_tools=[
+        WebFetchTool(
+            allowed_domains=['ai.pydantic.dev', 'docs.pydantic.dev'],
+            max_uses=10,
+            enable_citations=True,
+            max_content_tokens=50000,
+        )
+    ],
+)
+
+result = agent.run_sync(
+    'Compare the documentation at https://ai.pydantic.dev and https://docs.pydantic.dev'
+)
+print(result.output)
+"""
+Both sites provide comprehensive documentation for Pydantic projects. ai.pydantic.dev focuses on PydanticAI, a framework for building AI agents, while docs.pydantic.dev covers Pydantic, the data validation library. They share similar documentation styles and both emphasize type safety and developer experience.
+"""
+```
+
+_(This example is complete, it can be run "as is")_
+
+#### Provider Support
+
+| Parameter | Anthropic | Google |
+|-----------|-----------|--------|
+| `max_uses` | ✅ | ❌ |
+| `allowed_domains` | ✅ | ❌ |
+| `blocked_domains` | ✅ | ❌ |
+| `enable_citations` | ✅ | ❌ |
+| `max_content_tokens` | ✅ | ❌ |
+
+!!! note "Anthropic Domain Filtering"
+    With Anthropic, you can only use either `blocked_domains` or `allowed_domains`, not both.
+
 ## Memory Tool
 
 The [`MemoryTool`][pydantic_ai.builtin_tools.MemoryTool] enables your agent to use memory.

docs/models/openai.md

@@ -233,7 +233,7 @@ agent = Agent(model)
 ```
 
 Various providers also have their own provider classes so that you don't need to specify the base URL yourself and you can use the standard `<PROVIDER>_API_KEY` environment variable to set the API key.
-When a provider has its own provider class, you can use the `Agent("<provider>:<model>")` shorthand, e.g. `Agent("deepseek:deepseek-chat")` or `Agent("openrouter:google/gemini-2.5-pro-preview")`, instead of building the `OpenAIChatModel` explicitly. Similarly, you can pass the provider name as a string to the `provider` argument on `OpenAIChatModel` instead of building instantiating the provider class explicitly.
+When a provider has its own provider class, you can use the `Agent("<provider>:<model>")` shorthand, e.g. `Agent("deepseek:deepseek-chat")` or `Agent("moonshotai:kimi-k2-0711-preview")`, instead of building the `OpenAIChatModel` explicitly. Similarly, you can pass the provider name as a string to the `provider` argument on `OpenAIChatModel` instead of building instantiating the provider class explicitly.
 
 #### Model Profile
 
@@ -385,34 +385,6 @@ agent = Agent(model)
 ...
 ```
 
-### OpenRouter
-
-To use [OpenRouter](https://openrouter.ai), first create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).
-
-You can set the `OPENROUTER_API_KEY` environment variable and use [`OpenRouterProvider`][pydantic_ai.providers.openrouter.OpenRouterProvider] by name:
-
-```python
-from pydantic_ai import Agent
-
-agent = Agent('openrouter:anthropic/claude-3.5-sonnet')
-...
-```
-
-Or initialise the model and provider directly:
-
-```python
-from pydantic_ai import Agent
-from pydantic_ai.models.openai import OpenAIChatModel
-from pydantic_ai.providers.openrouter import OpenRouterProvider
-
-model = OpenAIChatModel(
-    'anthropic/claude-3.5-sonnet',
-    provider=OpenRouterProvider(api_key='your-openrouter-api-key'),
-)
-agent = Agent(model)
-...
-```
-
 ### Vercel AI Gateway
 
 To use [Vercel's AI Gateway](https://vercel.com/docs/ai-gateway), first follow the [documentation](https://vercel.com/docs/ai-gateway) instructions on obtaining an API key or OIDC token.

docs/models/openrouter.md

@@ -0,0 +1,75 @@
+# 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), first create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).
+
+You can set the `OPENROUTER_API_KEY` environment variable and use [`OpenRouterProvider`][pydantic_ai.providers.openrouter.OpenRouterProvider] by name:
+
+```python
+from pydantic_ai import Agent
+
+agent = Agent('openrouter:anthropic/claude-3.5-sonnet')
+...
+```
+
+Or initialise the model and provider directly:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+from pydantic_ai.providers.openrouter import OpenRouterProvider
+
+model = OpenRouterModel(
+    'anthropic/claude-3.5-sonnet',
+    provider=OpenRouterProvider(api_key='your-openrouter-api-key'),
+)
+agent = Agent(model)
+...
+```
+
+## App Attribution
+
+OpenRouter has an [app attribution](https://openrouter.ai/docs/app-attribution) feature to track your application in their public ranking and analytics.
+
+You can pass in an `app_url` and `app_title` when initializing the provider to enable app attribution.
+
+```python
+from pydantic_ai.providers.openrouter import OpenRouterProvider
+
+provider=OpenRouterProvider(
+    api_key='your-openrouter-api-key',
+    app_url='https://your-app.com',
+    app_title='Your App',
+),
+...
+```
+
+## Model Settings
+
+You can customize model behavior using [`OpenRouterModelSettings`][pydantic_ai.models.openrouter.OpenRouterModelSettings]:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel, OpenRouterModelSettings
+
+settings = OpenRouterModelSettings(
+    openrouter_reasoning={
+        'effort': 'high',
+    },
+    openrouter_usage={
+        'include': True,
+    }
+)
+model = OpenRouterModel('openai/gpt-5')
+agent = Agent(model, model_settings=settings)
+...
+```

docs/models/overview.md

@@ -5,32 +5,32 @@ Pydantic AI is model-agnostic and has built-in support for multiple model provid
 * [OpenAI](openai.md)
 * [Anthropic](anthropic.md)
 * [Gemini](google.md) (via two different APIs: Generative Language API and VertexAI API)
-* [Groq](groq.md)
-* [Mistral](mistral.md)
-* [Cohere](cohere.md)
 * [Bedrock](bedrock.md)
+* [Cohere](cohere.md)
+* [Groq](groq.md)
 * [Hugging Face](huggingface.md)
+* [Mistral](mistral.md)
+* [OpenRouter](openrouter.md)
 * [Outlines](outlines.md)
 
 ## OpenAI-compatible Providers
 
 In addition, many providers are compatible with the OpenAI API, and can be used with `OpenAIChatModel` in Pydantic AI:
 
+- [Azure AI Foundry](openai.md#azure-ai-foundry)
+- [Cerebras](openai.md#cerebras)
 - [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)
-- [Together AI](openai.md#together-ai)
-- [Azure AI Foundry](openai.md#azure-ai-foundry)
-- [Heroku](openai.md#heroku-ai)
 - [GitHub Models](openai.md#github-models)
-- [Cerebras](openai.md#cerebras)
+- [Grok (xAI)](openai.md#grok-xai)
+- [Heroku](openai.md#heroku-ai)
 - [LiteLLM](openai.md#litellm)
 - [Nebius AI Studio](openai.md#nebius-ai-studio)
+- [Ollama](openai.md#ollama)
 - [OVHcloud AI Endpoints](openai.md#ovhcloud-ai-endpoints)
+- [Perplexity](openai.md#perplexity)
+- [Together AI](openai.md#together-ai)
+- [Vercel AI Gateway](openai.md#vercel-ai-gateway)
 
 Pydantic AI also comes with [`TestModel`](../api/models/test.md) and [`FunctionModel`](../api/models/function.md)
 for testing and development.
@@ -180,7 +180,7 @@ contains all the exceptions encountered during the `run` execution.
 === "Python >=3.11"
 
     ```python {title="fallback_model_failure.py" py="3.11"}
-    from pydantic_ai import Agent, ModelHTTPError
+    from pydantic_ai import Agent, ModelAPIError
     from pydantic_ai.models.anthropic import AnthropicModel
     from pydantic_ai.models.fallback import FallbackModel
     from pydantic_ai.models.openai import OpenAIChatModel
@@ -192,7 +192,7 @@ contains all the exceptions encountered during the `run` execution.
     agent = Agent(fallback_model)
     try:
         response = agent.run_sync('What is the capital of France?')
-    except* ModelHTTPError as exc_group:
+    except* ModelAPIError as exc_group:
         for exc in exc_group.exceptions:
             print(exc)
     ```
@@ -206,7 +206,7 @@ contains all the exceptions encountered during the `run` execution.
     ```python {title="fallback_model_failure.py" noqa="F821" test="skip"}
     from exceptiongroup import catch
 
-    from pydantic_ai import Agent, ModelHTTPError
+    from pydantic_ai import Agent, ModelAPIError
     from pydantic_ai.models.anthropic import AnthropicModel
     from pydantic_ai.models.fallback import FallbackModel
     from pydantic_ai.models.openai import OpenAIChatModel
@@ -222,10 +222,11 @@ contains all the exceptions encountered during the `run` execution.
     fallback_model = FallbackModel(openai_model, anthropic_model)
 
     agent = Agent(fallback_model)
-    with catch({ModelHTTPError: model_status_error_handler}):
+    with catch({ModelAPIError: model_status_error_handler}):
         response = agent.run_sync('What is the capital of France?')
     ```
 
 By default, the `FallbackModel` only moves on to the next model if the current model raises a
+[`ModelAPIError`][pydantic_ai.exceptions.ModelAPIError], which includes
 [`ModelHTTPError`][pydantic_ai.exceptions.ModelHTTPError]. You can customize this behavior by
 passing a custom `fallback_on` argument to the `FallbackModel` constructor.

docs/thinking.md

@@ -144,6 +144,20 @@ agent = Agent(model, model_settings=settings)
 ...
 ```
 
+## OpenRouter
+
+To enable thinking, use the [`OpenRouterModelSettings.openrouter_reasoning`][pydantic_ai.models.openrouter.OpenRouterModelSettings.openrouter_reasoning] [model setting](agents.md#model-run-settings).
+
+```python {title="openrouter_thinking_part.py"}
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel, OpenRouterModelSettings
+
+model = OpenRouterModel('openai/gpt-5')
+settings = OpenRouterModelSettings(openrouter_reasoning={'effort': 'high'})
+agent = Agent(model, model_settings=settings)
+...
+```
+
 ## Mistral
 
 Thinking is supported by the `magistral` family of models. It does not need to be specifically enabled.

mkdocs.yml

@@ -32,8 +32,9 @@ nav:
           - models/bedrock.md
           - models/cohere.md
           - models/groq.md
-          - models/mistral.md
           - models/huggingface.md
+          - models/mistral.md
+          - models/openrouter.md
           - models/outlines.md
       - Tools & Toolsets:
           - tools.md
@@ -142,22 +143,23 @@ nav:
           - api/format_prompt.md
           - api/direct.md
           - api/ext.md
-          - api/models/base.md
-          - api/models/openai.md
           - api/models/anthropic.md
+          - api/models/base.md
           - api/models/bedrock.md
           - api/models/cohere.md
+          - api/models/fallback.md
+          - api/models/function.md
           - api/models/google.md
           - api/models/groq.md
           - api/models/huggingface.md
           - api/models/instrumented.md
+          - api/models/mcp-sampling.md
           - api/models/mistral.md
+          - api/models/openai.md
+          - api/models/openrouter.md
           - api/models/outlines.md
           - api/models/test.md
-          - api/models/function.md
-          - api/models/fallback.md
           - api/models/wrapper.md
-          - api/models/mcp-sampling.md
           - api/profiles.md
           - api/providers.md
           - api/retries.md