Skip to content

pydantic_ai.builtin_tools

AbstractBuiltinTool dataclass

Bases: ABC

A builtin tool that can be used by an agent.

This class is abstract and cannot be instantiated directly.

The builtin tools are passed to the model as part of the ModelRequestParameters.

Source code in pydantic_ai_slim/pydantic_ai/builtin_tools.py 
12
13
14
15
16
17
18
19
@dataclass
class AbstractBuiltinTool(ABC):
    """A builtin tool that can be used by an agent.

    This class is abstract and cannot be instantiated directly.

    The builtin tools are passed to the model as part of the `ModelRequestParameters`.
    """

WebSearchTool dataclass

Bases: AbstractBuiltinTool

A builtin tool that allows your agent to search the web for information.

The parameters that PydanticAI passes depend on the model, as some parameters may not be supported by certain models.

Supported by: * Anthropic * OpenAI * Groq

Source code in pydantic_ai_slim/pydantic_ai/builtin_tools.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
@dataclass
class WebSearchTool(AbstractBuiltinTool):
    """A builtin tool that allows your agent to search the web for information.

    The parameters that PydanticAI passes depend on the model, as some parameters may not be supported by certain models.

    Supported by:
    * Anthropic
    * OpenAI
    * Groq
    """

    search_context_size: Literal['low', 'medium', 'high'] = 'medium'
    """The `search_context_size` parameter controls how much context is retrieved from the web to help the tool formulate a response.

    Supported by:
    * OpenAI
    """

    user_location: WebSearchUserLocation | None = None
    """The `user_location` parameter allows you to localize search results based on a user's location.

    Supported by:
    * Anthropic
    * OpenAI
    """

    blocked_domains: list[str] | None = None
    """If provided, these domains will never appear in results.

    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)
    """

    allowed_domains: list[str] | None = None
    """If provided, only these domains will be included in results.

    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)
    """

    max_uses: int | None = None
    """If provided, the tool will stop searching the web after the given number of uses.

    Supported by:
    * Anthropic
    """

search_context_size class-attribute instance-attribute 

search_context_size: Literal["low", "medium", "high"] = (
    "medium"
)

The search_context_size parameter controls how much context is retrieved from the web to help the tool formulate a response.

Supported by: * OpenAI

user_location class-attribute instance-attribute 

user_location: WebSearchUserLocation | None = None

The user_location parameter allows you to localize search results based on a user's location.

Supported by: * Anthropic * OpenAI

blocked_domains class-attribute instance-attribute 

blocked_domains: list[str] | None = None

If provided, these domains will never appear in results.

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)

allowed_domains class-attribute instance-attribute 

allowed_domains: list[str] | None = None

If provided, only these domains will be included in results.

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)

max_uses class-attribute instance-attribute 

max_uses: int | None = None

If provided, the tool will stop searching the web after the given number of uses.

Supported by: * Anthropic

WebSearchUserLocation

Bases: TypedDict

Allows you to localize search results based on a user's location.

Supported by: * Anthropic * OpenAI

Source code in pydantic_ai_slim/pydantic_ai/builtin_tools.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
class WebSearchUserLocation(TypedDict, total=False):
    """Allows you to localize search results based on a user's location.

    Supported by:
    * Anthropic
    * OpenAI
    """

    city: str
    """The city where the user is located."""

    country: str
    """The country where the user is located. For OpenAI, this must be a 2-letter country code (e.g., 'US', 'GB')."""

    region: str
    """The region or state where the user is located."""

    timezone: str
    """The timezone of the user's location."""

city instance-attribute 

city: str

The city where the user is located.

country instance-attribute 

country: str

The country where the user is located. For OpenAI, this must be a 2-letter country code (e.g., 'US', 'GB').

region instance-attribute 

region: str

The region or state where the user is located.

timezone instance-attribute 

timezone: str

The timezone of the user's location.

CodeExecutionTool dataclass

Bases: AbstractBuiltinTool

A builtin tool that allows your agent to execute code.

Supported by: * Anthropic * OpenAI * Google

Source code in pydantic_ai_slim/pydantic_ai/builtin_tools.py 
 98
 99
100
101
102
103
104
105
class CodeExecutionTool(AbstractBuiltinTool):
    """A builtin tool that allows your agent to execute code.

    Supported by:
    * Anthropic
    * OpenAI
    * Google
    """