From 20f5abad8bc56c490c2d02c50af4099ee742ec9f Mon Sep 17 00:00:00 2001 From: Samuel Colvin Date: Sat, 6 Sep 2025 08:07:38 -0700 Subject: [PATCH 1/3] fix markdown in builtin tools api docs --- .gitignore | 1 + pydantic_ai_slim/pydantic_ai/builtin_tools.py | 17 +++++++++++++---- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index decf951689..c0f10dc973 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,4 @@ node_modules/ .coverage* /test_tmp/ .mcp.json +.claude/ diff --git a/pydantic_ai_slim/pydantic_ai/builtin_tools.py b/pydantic_ai_slim/pydantic_ai/builtin_tools.py index 12c2dbaaa2..d3060a13e3 100644 --- a/pydantic_ai_slim/pydantic_ai/builtin_tools.py +++ b/pydantic_ai_slim/pydantic_ai/builtin_tools.py @@ -26,6 +26,7 @@ class WebSearchTool(AbstractBuiltinTool): The parameters that PydanticAI passes depend on the model, as some parameters may not be supported by certain models. Supported by: + * Anthropic * OpenAI * Groq @@ -36,6 +37,7 @@ class WebSearchTool(AbstractBuiltinTool): """The `search_context_size` parameter controls how much context is retrieved from the web to help the tool formulate a response. Supported by: + * OpenAI """ @@ -43,6 +45,7 @@ class WebSearchTool(AbstractBuiltinTool): """The `user_location` parameter allows you to localize search results based on a user's location. Supported by: + * Anthropic * OpenAI """ @@ -53,8 +56,9 @@ class WebSearchTool(AbstractBuiltinTool): With Anthropic, you can only use one of `blocked_domains` or `allowed_domains`, not both. Supported by: - * Anthropic (https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool#domain-filtering) - * Groq (https://console.groq.com/docs/agentic-tooling#search-settings) + + * Anthropic, see + * Groq, see """ allowed_domains: list[str] | None = None @@ -63,14 +67,16 @@ class WebSearchTool(AbstractBuiltinTool): With Anthropic, you can only use one of `blocked_domains` or `allowed_domains`, not both. Supported by: - * Anthropic (https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool#domain-filtering) - * Groq (https://console.groq.com/docs/agentic-tooling#search-settings) + + * Anthropic, see + * Groq, see """ max_uses: int | None = None """If provided, the tool will stop searching the web after the given number of uses. Supported by: + * Anthropic """ @@ -79,6 +85,7 @@ class WebSearchUserLocation(TypedDict, total=False): """Allows you to localize search results based on a user's location. Supported by: + * Anthropic * OpenAI """ @@ -100,6 +107,7 @@ class CodeExecutionTool(AbstractBuiltinTool): """A builtin tool that allows your agent to execute code. Supported by: + * Anthropic * OpenAI * Google @@ -110,5 +118,6 @@ class UrlContextTool(AbstractBuiltinTool): """Allows your agent to access contents from URLs. Supported by: + * Google """ From 309c27514553eabf04efc9410c83d7b939bde8a5 Mon Sep 17 00:00:00 2001 From: Samuel Colvin Date: Sat, 6 Sep 2025 09:27:26 -0700 Subject: [PATCH 2/3] show clearly that you must use open ai responses --- docs/builtin-tools.md | 19 ++++++++++++++++--- pydantic_ai_slim/pydantic_ai/builtin_tools.py | 10 +++++----- 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/docs/builtin-tools.md b/docs/builtin-tools.md index 4714094b83..9d8afab4c2 100644 --- a/docs/builtin-tools.md +++ b/docs/builtin-tools.md @@ -26,10 +26,11 @@ making it ideal for queries that require up-to-date data. | Provider | Supported | Notes | |----------|-----------|-------| -| OpenAI | ✅ | Full feature support | +| OpenAI Responses | ✅ | Full feature support | | Anthropic | ✅ | Full feature support | | Groq | ✅ | Limited parameter support. To use web search capabilities with Groq, you need to use the [compound models](https://console.groq.com/docs/compound). | | Google | ✅ | No parameter support. Google does not support using built-in tools and user tools (including [output tools](output.md#tool-output)) at the same time. To use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. | +| OpenAI chat completions | ❌ | Not supported | | Bedrock | ❌ | Not supported | | Mistral | ❌ | Not supported | | Cohere | ❌ | Not supported | @@ -37,14 +38,26 @@ making it ideal for queries that require up-to-date data. ### Usage -```py title="web_search_basic.py" +```py title="web_search_anthropic.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. +print(result.output) +#> Scientists have developed a universal AI detector that can identify deepfake videos. +``` + +With OpenAI, you must use their responses API to access the web search tool. + +```py title="web_search_openai.py" +from pydantic_ai import Agent, WebSearchTool + +agent = Agent('openai-responses:gpt-4.1', builtin_tools=[WebSearchTool()]) +result = agent.run_sync('Give me a sentence with the biggest news in AI this week.') +print(result.output) +#> Scientists have developed a universal AI detector that can identify deepfake videos. ``` ### Configuration Options diff --git a/pydantic_ai_slim/pydantic_ai/builtin_tools.py b/pydantic_ai_slim/pydantic_ai/builtin_tools.py index d3060a13e3..2903edd9df 100644 --- a/pydantic_ai_slim/pydantic_ai/builtin_tools.py +++ b/pydantic_ai_slim/pydantic_ai/builtin_tools.py @@ -28,7 +28,7 @@ class WebSearchTool(AbstractBuiltinTool): Supported by: * Anthropic - * OpenAI + * OpenAI Responses * Groq * Google """ @@ -38,7 +38,7 @@ class WebSearchTool(AbstractBuiltinTool): Supported by: - * OpenAI + * OpenAI Responses """ user_location: WebSearchUserLocation | None = None @@ -47,7 +47,7 @@ class WebSearchTool(AbstractBuiltinTool): Supported by: * Anthropic - * OpenAI + * OpenAI Responses """ blocked_domains: list[str] | None = None @@ -87,7 +87,7 @@ class WebSearchUserLocation(TypedDict, total=False): Supported by: * Anthropic - * OpenAI + * OpenAI Responses """ city: str @@ -109,7 +109,7 @@ class CodeExecutionTool(AbstractBuiltinTool): Supported by: * Anthropic - * OpenAI + * OpenAI Responses * Google """ From 2815323b7cf5cf836d0b2045e6e108cb3d2f38ba Mon Sep 17 00:00:00 2001 From: Douwe Maan Date: Mon, 8 Sep 2025 11:44:15 -0600 Subject: [PATCH 3/3] Update docs/builtin-tools.md --- docs/builtin-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/builtin-tools.md b/docs/builtin-tools.md index 9d8afab4c2..2d888c4f4a 100644 --- a/docs/builtin-tools.md +++ b/docs/builtin-tools.md @@ -30,7 +30,7 @@ making it ideal for queries that require up-to-date data. | Anthropic | ✅ | Full feature support | | Groq | ✅ | Limited parameter support. To use web search capabilities with Groq, you need to use the [compound models](https://console.groq.com/docs/compound). | | Google | ✅ | No parameter support. Google does not support using built-in tools and user tools (including [output tools](output.md#tool-output)) at the same time. To use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. | -| OpenAI chat completions | ❌ | Not supported | +| OpenAI Chat Completions | ❌ | Not supported | | Bedrock | ❌ | Not supported | | Mistral | ❌ | Not supported | | Cohere | ❌ | Not supported |