内置工具

内置工具是由 LLM 提供商提供的原生工具，可用于增强智能体的能力。与通用工具（由 Pydantic AI 执行的自定义实现）不同，内置工具由模型提供商直接执行。

概述

Pydantic AI 支持以下内置工具：

WebSearchTool：允许智能体搜索网络
CodeExecutionTool：使智能体能够在安全的环境中执行代码
UrlContextTool：使智能体能够将 URL 内容拉取到其上下文中

这些工具通过 builtin_tools 参数传递给智能体，并由模型提供商的基础设施执行。

提供商支持

并非所有模型提供商都支持内置工具。如果您在不支持的提供商上使用内置工具，Pydantic AI 将在您尝试运行智能体时引发 UserError 错误。

如果某个提供商支持 Pydantic AI 当前不支持的内置工具，请提交一个 issue。

网络搜索工具

WebSearchTool 允许您的智能体搜索网络，非常适合需要最新数据的查询。

提供商支持

提供商	支持	备注
OpenAI	✅	完全功能支持
Anthropic	✅	完全功能支持
Groq	✅	有限的参数支持。要在 Groq 中使用网络搜索功能，您需要使用复合模型。
Google	✅	无参数支持。Google 不支持同时使用内置工具和用户工具（包括输出工具）。要使用结构化输出，请改用 `PromptedOutput`。
Bedrock	❌	不支持
Mistral	❌	不支持
Cohere	❌	不支持
HuggingFace	❌	不支持

用法

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.

配置选项

WebSearchTool 支持多个配置参数：

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.

各提供商的参数支持

参数	OpenAI	Anthropic	Groq
`search_context_size`	✅	❌	❌
`user_location`	✅	✅	❌
`blocked_domains`	❌	✅	✅
`allowed_domains`	❌	✅	✅
`max_uses`	❌	✅	❌

Anthropic 域名过滤

使用 Anthropic 时，您只能使用 blocked_domains 或 allowed_domains 中的一个，不能同时使用两者。

代码执行工具

CodeExecutionTool 使您的智能体能够在安全的环境中执行代码，非常适合计算任务、数据分析和数学运算。

提供商支持

提供商	支持	备注
OpenAI	✅
Anthropic	✅	Google 不支持同时使用内置工具和用户工具（包括输出工具）。要使用结构化输出，请改用 `PromptedOutput`。
Google	✅
Groq	❌
Bedrock	❌
Mistral	❌
Cohere	❌
HuggingFace	❌

用法

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**.

URL 上下文工具

UrlContextTool 使您的智能体能够将 URL 内容拉取到其上下文中，从而可以从网络上获取最新信息。

提供商支持

提供商	支持	备注
Google	✅	Google 不支持同时使用内置工具和用户工具（包括输出工具）。要使用结构化输出，请改用 `PromptedOutput`。
OpenAI	❌
Anthropic	❌
Groq	❌
Bedrock	❌
Mistral	❌
Cohere	❌
HuggingFace	❌

用法

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.org.cn')
# > A Python agent framework for building Generative AI applications.

API 参考

有关完整的 API 文档，请参阅 API 参考。