Add builtin_tools to Agent (#2102)

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

Author: 3 people

.gitignore

@@ -19,3 +19,4 @@ node_modules/
 **.idea/
 .coverage*
 /test_tmp/
+.mcp.json

docs/api/builtin_tools.md

@@ -0,0 +1,3 @@
+# `pydantic_ai.builtin_tools`
+
+::: pydantic_ai.builtin_tools

docs/builtin-tools.md

@@ -0,0 +1,123 @@
+# Builtin Tools
+
+Builtin tools are native tools provided by LLM providers that can be used to enhance your agent's capabilities. Unlike [common tools](common-tools.md), which are custom implementations that PydanticAI executes, builtin tools are executed directly by the model provider.
+
+## Overview
+
+PydanticAI supports two types of 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
+
+These tools are passed to the agent via the `builtin_tools` parameter and are executed by the model provider's infrastructure.
+
+!!! warning "Provider Support"
+    Not all model providers support builtin tools. If you use a builtin tool with an unsupported provider, PydanticAI will raise a [`UserError`][pydantic_ai.exceptions.UserError] when you try to run the agent.
+
+## Web Search Tool
+
+The [`WebSearchTool`][pydantic_ai.builtin_tools.WebSearchTool] allows your agent to search the web,
+making it ideal for queries that require up-to-date data.
+
+### Provider Support
+
+| Provider | Supported | Notes |
+|----------|-----------|-------|
+| OpenAI | ✅ | Full feature support |
+| Anthropic | ✅ | Full feature support |
+| Groq | ✅ | Limited parameter support |
+| Google | ❌ | Not supported |
+| Bedrock | ❌ | Not supported |
+| Mistral | ❌ | Not supported |
+| Cohere | ❌ | Not supported |
+| HuggingFace | ❌ | Not supported |
+
+!!! note "Groq Support"
+    To use web search capabilities with Groq, you need to use the [compound models](https://console.groq.com/docs/compound).
+
+### Usage
+
+```py title="web_search_basic.py"
+from pydantic_ai import Agent, WebSearchTool
+
+agent = Agent('anthropic:claude-sonnet-4-0', builtin_tools=[WebSearchTool()])
+
+result = agent.run_sync('Give me a sentence with the biggest news in AI this week.')
+# > Scientists have developed a universal AI detector that can identify deepfake videos.
+
+```
+
+### Configuration Options
+
+The `WebSearchTool` supports several configuration parameters:
+
+```py title="web_search_configured.py"
+from pydantic_ai import Agent, WebSearchTool, WebSearchUserLocation
+
+agent = Agent(
+    'anthropic:claude-sonnet-4-0',
+    builtin_tools=[
+        WebSearchTool(
+            search_context_size='high',
+            user_location=WebSearchUserLocation(
+                city='San Francisco',
+                country='US',
+                region='CA',
+                timezone='America/Los_Angeles',
+            ),
+            blocked_domains=['example.com', 'spam-site.net'],
+            allowed_domains=None,  # Cannot use both blocked_domains and allowed_domains with Anthropic
+            max_uses=5,  # Anthropic only: limit tool usage
+        )
+    ],
+)
+
+result = agent.run_sync('Use the web to get the current time.')
+# > In San Francisco, it's 8:21:41 pm PDT on Wednesday, August 6, 2025.
+```
+
+### Parameter Support by Provider
+
+| Parameter | OpenAI | Anthropic | Groq |
+|-----------|--------|-----------|------|
+| `search_context_size` | ✅ | ❌ | ❌ |
+| `user_location` | ✅ | ✅ | ❌ |
+| `blocked_domains` | ❌ | ✅ | ✅ |
+| `allowed_domains` | ❌ | ✅ | ✅ |
+| `max_uses` | ❌ | ✅ | ❌ |
+
+!!! note "Anthropic Domain Filtering"
+    With Anthropic, you can only use either `blocked_domains` or `allowed_domains`, not both.
+
+## Code Execution Tool
+
+The [`CodeExecutionTool`][pydantic_ai.builtin_tools.CodeExecutionTool] enables your agent to execute code
+in a secure environment, making it perfect for computational tasks, data analysis, and mathematical operations.
+
+### Provider Support
+
+| Provider | Supported |
+|----------|-----------|
+| OpenAI | ✅ |
+| Anthropic | ✅ |
+| Google | ✅ |
+| Groq | ❌ |
+| Bedrock | ❌ |
+| Mistral | ❌ |
+| Cohere | ❌ |
+| HuggingFace | ❌ |
+
+### Usage
+
+```py title="code_execution_basic.py"
+from pydantic_ai import Agent, CodeExecutionTool
+
+agent = Agent('anthropic:claude-sonnet-4-0', builtin_tools=[CodeExecutionTool()])
+
+result = agent.run_sync('Calculate the factorial of 15 and show your work')
+# > The factorial of 15 is **1,307,674,368,000**.
+```
+
+## API Reference
+
+For complete API documentation, see the [API Reference](api/builtin_tools.md).

mkdocs.yml

@@ -41,6 +41,7 @@ nav:
       - input.md
       - thinking.md
       - direct.md
+      - builtin-tools.md
       - common-tools.md
       - retries.md
       - MCP:
@@ -72,6 +73,7 @@ nav:
       - api/agent.md
       - api/tools.md
       - api/toolsets.md
+      - api/builtin_tools.md
       - api/common_tools.md
       - api/output.md
       - api/result.md
@@ -118,29 +120,29 @@ extra:
   generator: false
 
 theme:
-  name: 'material'
+  name: "material"
   custom_dir: docs/.overrides
   palette:
-    - media: '(prefers-color-scheme)'
+    - media: "(prefers-color-scheme)"
       primary: pink
       accent: pink
       toggle:
         icon: material/brightness-auto
-        name: 'Switch to light mode'
-    - media: '(prefers-color-scheme: light)'
+        name: "Switch to light mode"
+    - media: "(prefers-color-scheme: light)"
       scheme: default
       primary: pink
       accent: pink
       toggle:
         icon: material/brightness-7
-        name: 'Switch to dark mode'
-    - media: '(prefers-color-scheme: dark)'
+        name: "Switch to dark mode"
+    - media: "(prefers-color-scheme: dark)"
       scheme: slate
       primary: pink
       accent: pink
       toggle:
         icon: material/brightness-4
-        name: 'Switch to system preference'
+        name: "Switch to system preference"
   features:
     - search.suggest
     - search.highlight
@@ -153,8 +155,8 @@ theme:
     - navigation.sections
     - navigation.tracking
     - toc.follow
-  logo: 'img/logo-white.svg'
-  favicon: 'favicon.ico'
+  logo: "img/logo-white.svg"
+  favicon: "favicon.ico"
 
 # https://www.mkdocs.org/user-guide/configuration/#validation
 validation:
@@ -164,13 +166,13 @@ validation:
   anchors: warn
 
 extra_css:
-  - 'extra/tweaks.css'
+  - "extra/tweaks.css"
 # used for analytics
 extra_javascript:
-  - '/flarelytics/client.js'
-  - 'https://cdn.jsdelivr.net/npm/[email protected]/dist/lite/builds/browser.umd.js'
-  - 'https://cdn.jsdelivr.net/npm/[email protected]/dist/instantsearch.production.min.js'
-  - '/javascripts/algolia-search.js'
+  - "/flarelytics/client.js"
+  - "https://cdn.jsdelivr.net/npm/[email protected]/dist/lite/builds/browser.umd.js"
+  - "https://cdn.jsdelivr.net/npm/[email protected]/dist/instantsearch.production.min.js"
+  - "/javascripts/algolia-search.js"
 
 markdown_extensions:
   - tables
@@ -272,5 +274,5 @@ plugins:
           - examples/*.md
 
 hooks:
-  - 'docs/.hooks/main.py'
-  - 'docs/.hooks/algolia.py'
+  - "docs/.hooks/main.py"
+  - "docs/.hooks/algolia.py"

pydantic_ai_slim/pydantic_ai/__init__.py

@@ -1,6 +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 .exceptions import (
     AgentRunError,
     FallbackExceptionGroup,
@@ -41,6 +42,10 @@
     # tools
     'Tool',
     'RunContext',
+    # builtin_tools
+    'WebSearchTool',
+    'WebSearchUserLocation',
+    'CodeExecutionTool',
     # output
     'ToolOutput',
     'NativeOutput',

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -16,6 +16,7 @@
 from pydantic_ai._function_schema import _takes_ctx as is_takes_ctx  # type: ignore
 from pydantic_ai._tool_manager import ToolManager
 from pydantic_ai._utils import is_async_callable, run_in_executor
+from pydantic_ai.builtin_tools import AbstractBuiltinTool
 from pydantic_graph import BaseNode, Graph, GraphRunContext
 from pydantic_graph.nodes import End, NodeRunEndT
 
@@ -112,6 +113,7 @@ class GraphAgentDeps(Generic[DepsT, OutputDataT]):
 
     history_processors: Sequence[HistoryProcessor[DepsT]]
 
+    builtin_tools: list[AbstractBuiltinTool] = dataclasses.field(repr=False)
     tool_manager: ToolManager[DepsT]
 
     tracer: Tracer
@@ -269,6 +271,7 @@ async def _prepare_request_parameters(
 
     return models.ModelRequestParameters(
         function_tools=function_tools,
+        builtin_tools=ctx.deps.builtin_tools,
         output_mode=output_schema.mode,
         output_tools=output_tools,
         output_object=output_object,
@@ -443,6 +446,10 @@ async def _run_stream() -> AsyncIterator[_messages.HandleResponseEvent]:
                             texts.append(part.content)
                     elif isinstance(part, _messages.ToolCallPart):
                         tool_calls.append(part)
+                    elif isinstance(part, _messages.BuiltinToolCallPart):
+                        yield _messages.BuiltinToolCallEvent(part)
+                    elif isinstance(part, _messages.BuiltinToolReturnPart):
+                        yield _messages.BuiltinToolResultEvent(part)
                     elif isinstance(part, _messages.ThinkingPart):
                         # We don't need to do anything with thinking parts in this tool-calling node.
                         # We need to handle text parts in case there are no tool calls and/or the desired output comes

pydantic_ai_slim/pydantic_ai/_utils.py

@@ -227,7 +227,13 @@ def now_utc() -> datetime:
     return datetime.now(tz=timezone.utc)
 
 
-def guard_tool_call_id(t: _messages.ToolCallPart | _messages.ToolReturnPart | _messages.RetryPromptPart) -> str:
+def guard_tool_call_id(
+    t: _messages.ToolCallPart
+    | _messages.ToolReturnPart
+    | _messages.RetryPromptPart
+    | _messages.BuiltinToolCallPart
+    | _messages.BuiltinToolReturnPart,
+) -> str:
     """Type guard that either returns the tool call id or generates a new one if it's None."""
     return t.tool_call_id or generate_tool_call_id()
 

pydantic_ai_slim/pydantic_ai/agent.py

@@ -16,6 +16,7 @@
 from pydantic.json_schema import GenerateJsonSchema
 from typing_extensions import Literal, Never, Self, TypeIs, TypeVar, deprecated
 
+from pydantic_ai.builtin_tools import AbstractBuiltinTool
 from pydantic_graph import End, Graph, GraphRun, GraphRunContext
 from pydantic_graph._utils import get_event_loop
 
@@ -188,6 +189,7 @@ def __init__(
         retries: int = 1,
         output_retries: int | None = None,
         tools: Sequence[Tool[AgentDepsT] | ToolFuncEither[AgentDepsT, ...]] = (),
+        builtin_tools: Sequence[AbstractBuiltinTool] = (),
         prepare_tools: ToolsPrepareFunc[AgentDepsT] | None = None,
         prepare_output_tools: ToolsPrepareFunc[AgentDepsT] | None = None,
         toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
@@ -215,6 +217,7 @@ def __init__(
         retries: int = 1,
         output_retries: int | None = None,
         tools: Sequence[Tool[AgentDepsT] | ToolFuncEither[AgentDepsT, ...]] = (),
+        builtin_tools: Sequence[AbstractBuiltinTool] = (),
         prepare_tools: ToolsPrepareFunc[AgentDepsT] | None = None,
         prepare_output_tools: ToolsPrepareFunc[AgentDepsT] | None = None,
         mcp_servers: Sequence[MCPServer] = (),
@@ -240,6 +243,7 @@ def __init__(
         retries: int = 1,
         output_retries: int | None = None,
         tools: Sequence[Tool[AgentDepsT] | ToolFuncEither[AgentDepsT, ...]] = (),
+        builtin_tools: Sequence[AbstractBuiltinTool] = (),
         prepare_tools: ToolsPrepareFunc[AgentDepsT] | None = None,
         prepare_output_tools: ToolsPrepareFunc[AgentDepsT] | None = None,
         toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
@@ -271,6 +275,8 @@ def __init__(
             output_retries: The maximum number of retries to allow for output validation, defaults to `retries`.
             tools: Tools to register with the agent, you can also register tools via the decorators
                 [`@agent.tool`][pydantic_ai.Agent.tool] and [`@agent.tool_plain`][pydantic_ai.Agent.tool_plain].
+            builtin_tools: The builtin tools that the agent will use. This depends on the model, as some models may not
+                support certain tools. If the model doesn't support the builtin tools, an error will be raised.
             prepare_tools: Custom function to prepare the tool definition of all tools for each step, except output tools.
                 This is useful if you want to customize the definition of multiple tools or you want to register
                 a subset of tools for a given step. See [`ToolsPrepareFunc`][pydantic_ai.tools.ToolsPrepareFunc]
@@ -340,6 +346,8 @@ def __init__(
         self._system_prompt_dynamic_functions = {}
 
         self._max_result_retries = output_retries if output_retries is not None else retries
+        self._builtin_tools = builtin_tools
+
         self._prepare_tools = prepare_tools
         self._prepare_output_tools = prepare_output_tools
 
@@ -700,6 +708,7 @@ async def get_instructions(run_context: RunContext[AgentDepsT]) -> str | None:
                 output_schema=output_schema,
                 output_validators=output_validators,
                 history_processors=self.history_processors,
+                builtin_tools=list(self._builtin_tools),
                 tool_manager=run_toolset,
                 tracer=tracer,
                 get_instructions=get_instructions,