feat: support Google's url_context builtin tool (#2604)

Co-authored-by: Marcelo Trylesinski <[email protected]>

Author: vinnymeller

docs/builtin-tools.md

@@ -4,10 +4,11 @@ Builtin tools are native tools provided by LLM providers that can be used to enh
 
 ## Overview
 
-PydanticAI supports two types of builtin tools:
+PydanticAI supports the following builtin 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
+- **[`UrlContextTool`][pydantic_ai.builtin_tools.UrlContextTool]**: Enables agents to pull URL contents into their context
 
 These tools are passed to the agent via the `builtin_tools` parameter and are executed by the model provider's infrastructure.
 
@@ -118,6 +119,35 @@ result = agent.run_sync('Calculate the factorial of 15 and show your work')
 # > The factorial of 15 is **1,307,674,368,000**.
 ```
 
+## URL Context Tool
+
+The [`UrlContextTool`][pydantic_ai.builtin_tools.UrlContextTool] 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 |
+|----------|-----------|
+| Google | ✅ |
+| OpenAI | ❌ |
+| Anthropic | ❌ |
+| Groq | ❌ |
+| Bedrock | ❌ |
+| Mistral | ❌ |
+| Cohere | ❌ |
+| HuggingFace | ❌ |
+
+### Usage
+
+```py title="url_context_basic.py"
+from pydantic_ai import Agent, UrlContextTool
+
+agent = Agent('google-gla:gemini-2.5-flash', builtin_tools=[UrlContextTool()])
+
+result = agent.run_sync('What is this? https://ai.pydantic.dev')
+# > A Python agent framework for building Generative AI applications.
+```
+
 ## API Reference
 
 For complete API documentation, see the [API Reference](api/builtin_tools.md).

pydantic_ai_slim/pydantic_ai/__init__.py

@@ -1,7 +1,7 @@
 from importlib.metadata import version as _metadata_version
 
 from .agent import Agent, CallToolsNode, EndStrategy, ModelRequestNode, UserPromptNode, capture_run_messages
-from .builtin_tools import CodeExecutionTool, WebSearchTool, WebSearchUserLocation
+from .builtin_tools import CodeExecutionTool, UrlContextTool, WebSearchTool, WebSearchUserLocation
 from .exceptions import (
     AgentRunError,
     FallbackExceptionGroup,
@@ -45,6 +45,7 @@
     # builtin_tools
     'WebSearchTool',
     'WebSearchUserLocation',
+    'UrlContextTool',
     'CodeExecutionTool',
     # output
     'ToolOutput',

pydantic_ai_slim/pydantic_ai/builtin_tools.py

@@ -103,3 +103,11 @@ class CodeExecutionTool(AbstractBuiltinTool):
     * OpenAI
     * Google
     """
+
+
+class UrlContextTool(AbstractBuiltinTool):
+    """Allows your agent to access contents from URLs.
+
+    Supported by:
+    * Google
+    """

pydantic_ai_slim/pydantic_ai/models/google.py

@@ -13,7 +13,7 @@
 from .. import UnexpectedModelBehavior, _utils, usage
 from .._output import OutputObjectDefinition
 from .._run_context import RunContext
-from ..builtin_tools import CodeExecutionTool, WebSearchTool
+from ..builtin_tools import CodeExecutionTool, UrlContextTool, WebSearchTool
 from ..exceptions import UserError
 from ..messages import (
     BinaryContent,
@@ -72,6 +72,7 @@
         ToolConfigDict,
         ToolDict,
         ToolListUnionDict,
+        UrlContextDict,
     )
 
     from ..providers.google import GoogleProvider
@@ -270,6 +271,8 @@ def _get_tools(self, model_request_parameters: ModelRequestParameters) -> list[T
         for tool in model_request_parameters.builtin_tools:
             if isinstance(tool, WebSearchTool):
                 tools.append(ToolDict(google_search=GoogleSearchDict()))
+            elif isinstance(tool, UrlContextTool):
+                tools.append(ToolDict(url_context=UrlContextDict()))
             elif isinstance(tool, CodeExecutionTool):  # pragma: no branch
                 tools.append(ToolDict(code_execution=ToolCodeExecutionDict()))
             else:  # pragma: no cover

tests/models/cassettes/test_google/test_google_model_url_context_tool.yaml

@@ -0,0 +1,76 @@
+interactions:
+- request:
+    body: '{"contents": [{"parts": [{"text": "What is the first sentence on the page
+      https://ai.pydantic.dev? Reply with only the sentence."}], "role": "user"}],
+      "systemInstruction": {"parts": [{"text": "You are a helpful chatbot."}], "role":
+      "user"}, "tools": [{"urlContext": {}}], "generationConfig": {}}'
+    headers:
+      accept:
+      - '*/*'
+      accept-encoding:
+      - gzip, deflate
+      connection:
+      - keep-alive
+      content-length:
+      - '295'
+      content-type:
+      - application/json
+      host:
+      - generativelanguage.googleapis.com
+    method: POST
+    uri: https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent
+  response:
+    body:
+      string: "{\n  \"candidates\": [\n    {\n      \"content\": {\n        \"parts\"\
+        : [\n          {\n            \"text\": \"Pydantic AI is a Python agent framework\
+        \ designed to make it less painful to build production grade applications\
+        \ with Generative AI.\"\n          }\n        ],\n        \"role\": \"model\"\
+        \n      },\n      \"finishReason\": \"STOP\",\n      \"index\": 0,\n     \
+        \ \"groundingMetadata\": {\n        \"groundingChunks\": [\n          {\n\
+        \            \"web\": {\n              \"uri\": \"https://ai.pydantic.dev\"\
+        ,\n              \"title\": \"Pydantic AI\"\n            }\n          }\n\
+        \        ],\n        \"groundingSupports\": [\n          {\n            \"\
+        segment\": {\n              \"endIndex\": 131,\n              \"text\": \"\
+        Pydantic AI is a Python agent framework designed to make it less painful to\
+        \ build production grade applications with Generative AI.\"\n            },\n\
+        \            \"groundingChunkIndices\": [\n              0\n            ]\n\
+        \          }\n        ]\n      },\n      \"urlContextMetadata\": {\n     \
+        \   \"urlMetadata\": [\n          {\n            \"retrievedUrl\": \"https://ai.pydantic.dev\"\
+        ,\n            \"urlRetrievalStatus\": \"URL_RETRIEVAL_STATUS_SUCCESS\"\n\
+        \          }\n        ]\n      }\n    }\n  ],\n  \"usageMetadata\": {\n  \
+        \  \"promptTokenCount\": 32,\n    \"candidatesTokenCount\": 41,\n    \"totalTokenCount\"\
+        : 2515,\n    \"promptTokensDetails\": [\n      {\n        \"modality\": \"\
+        TEXT\",\n        \"tokenCount\": 32\n      }\n    ],\n    \"toolUsePromptTokenCount\"\
+        : 2395,\n    \"toolUsePromptTokensDetails\": [\n      {\n        \"modality\"\
+        : \"TEXT\",\n        \"tokenCount\": 2395\n      }\n    ],\n    \"thoughtsTokenCount\"\
+        : 47\n  },\n  \"modelVersion\": \"gemini-2.5-flash\",\n  \"responseId\": \"\
+        qgqkaI-iDLrTjMcP0bP24A4\"\n}\n"
+    headers:
+      Alt-Svc:
+      - h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
+      Content-Type:
+      - application/json; charset=UTF-8
+      Date:
+      - Tue, 19 Aug 2025 05:24:58 GMT
+      Server:
+      - scaffolding on HTTPServer2
+      Server-Timing:
+      - gfet4t7; dur=9182
+      Transfer-Encoding:
+      - chunked
+      Vary:
+      - Origin
+      - X-Origin
+      - Referer
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - SAMEORIGIN
+      X-XSS-Protection:
+      - '0'
+      content-length:
+      - '1627'
+    status:
+      code: 200
+      message: OK
+version: 1

tests/models/test_google.py

@@ -12,7 +12,7 @@
 
 from pydantic_ai import UsageLimitExceeded
 from pydantic_ai.agent import Agent
-from pydantic_ai.builtin_tools import CodeExecutionTool, WebSearchTool
+from pydantic_ai.builtin_tools import CodeExecutionTool, UrlContextTool, WebSearchTool
 from pydantic_ai.exceptions import ModelRetry, UnexpectedModelBehavior, UserError
 from pydantic_ai.messages import (
     AudioUrl,
@@ -600,6 +600,19 @@ async def test_google_model_web_search_tool(allow_model_requests: None, google_p
     assert result.output == snapshot('Today is Wednesday, May 28, 2025, in Utrecht.\n')
 
 
+async def test_google_model_url_context_tool(allow_model_requests: None, google_provider: GoogleProvider):
+    m = GoogleModel('gemini-2.5-flash', provider=google_provider)
+    agent = Agent(m, system_prompt='You are a helpful chatbot.', builtin_tools=[UrlContextTool()])
+
+    result = await agent.run(
+        'What is the first sentence on the page https://ai.pydantic.dev? Reply with only the sentence.'
+    )
+
+    assert result.output == snapshot(
+        'Pydantic AI is a Python agent framework designed to make it less painful to build production grade applications with Generative AI.'
+    )
+
+
 async def test_google_model_code_execution_tool(allow_model_requests: None, google_provider: GoogleProvider):
     m = GoogleModel('gemini-2.0-flash', provider=google_provider)
     agent = Agent(m, system_prompt='You are a helpful chatbot.', builtin_tools=[CodeExecutionTool()])

tests/test_examples.py

@@ -304,6 +304,7 @@ async def call_tool(
     'Who was Albert Einstein?': 'Albert Einstein was a German-born theoretical physicist.',
     'What was his most famous equation?': "Albert Einstein's most famous equation is (E = mc^2).",
     'What is the date?': 'Hello Frank, the date today is 2032-01-02.',
+    'What is this? https://ai.pydantic.dev': 'A Python agent framework for building Generative AI applications.',
     'Put my money on square eighteen': ToolCallPart(
         tool_name='roulette_wheel', args={'square': 18}, tool_call_id='pyd_ai_tool_call_id'
     ),