Skip to content

pydantic_ai.native_tools

NATIVE_TOOL_TYPES module-attribute 

NATIVE_TOOL_TYPES: dict[str, type[AbstractNativeTool]] = {}

Registry of all native tool types, keyed by their kind string.

This dict is populated automatically via __init_subclass__ when tool classes are defined.

ImageAspectRatio module-attribute 

ImageAspectRatio = Literal[
    "21:9",
    "16:9",
    "4:3",
    "3:2",
    "1:1",
    "9:16",
    "3:4",
    "2:3",
    "5:4",
    "4:5",
]

Supported aspect ratios for image generation tools.

ImageGenerationModelName module-attribute 

ImageGenerationModelName = (
    Literal[
        "gpt-image-2",
        "gpt-image-1.5",
        "gpt-image-1",
        "gpt-image-1-mini",
    ]
    | str
)

Known OpenAI image generation model names, or another OpenAI image model ID.

AbstractNativeTool dataclass

Bases: ABC

A native tool that can be used by an agent.

This class is abstract and cannot be instantiated directly.

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

Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
 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
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@dataclass(kw_only=True)
class AbstractNativeTool(ABC):
    """A native tool that can be used by an agent.

    This class is abstract and cannot be instantiated directly.

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

    kind: str = 'unknown_native_tool'
    """Native tool identifier, this should be available on all native tools as a discriminator."""

    optional: bool = False
    """Whether this instance is a best-effort upgrade rather than a hard requirement.

    When `True`, the instance is silently dropped from the request on a model that doesn't
    support it natively, instead of raising when no local fallback is provided. Use for
    native tools where a fallback path exists (e.g. a local function tool that takes over when
    the native one isn't available). When `False` (the default), the request errors on
    models that can't honor the native tool — the user explicitly asked for it, so fail loudly
    rather than silently substituting different behavior.
    """

    @property
    def unique_id(self) -> str:
        """A unique identifier for the native tool.

        If multiple instances of the same native tool can be passed to the model, subclasses should override this property to allow them to be distinguished.
        """
        return self.kind

    @property
    def label(self) -> str:
        """Human-readable label for UI display.

        Subclasses should override this to provide a meaningful label.
        """
        return self.kind.replace('_', ' ').title()

    def __init_subclass__(cls, **kwargs: Any) -> None:
        super().__init_subclass__(**kwargs)
        NATIVE_TOOL_TYPES[cls.kind] = cls

    @classmethod
    def __get_pydantic_core_schema__(
        cls, _source_type: Any, handler: pydantic.GetCoreSchemaHandler
    ) -> core_schema.CoreSchema:
        if cls is not AbstractNativeTool:
            return handler(cls)

        tools = NATIVE_TOOL_TYPES.values()
        if len(tools) == 1:  # pragma: no cover
            tools_type = next(iter(tools))
        else:
            tools_annotated = [Annotated[tool, pydantic.Tag(tool.kind)] for tool in tools]
            tools_type = Annotated[Union[tuple(tools_annotated)], pydantic.Discriminator(_tool_discriminator)]  # noqa: UP007

        return handler(tools_type)

kind class-attribute instance-attribute 

kind: str = 'unknown_native_tool'

Native tool identifier, this should be available on all native tools as a discriminator.

optional class-attribute instance-attribute 

optional: bool = False

Whether this instance is a best-effort upgrade rather than a hard requirement.

When True, the instance is silently dropped from the request on a model that doesn't support it natively, instead of raising when no local fallback is provided. Use for native tools where a fallback path exists (e.g. a local function tool that takes over when the native one isn't available). When False (the default), the request errors on models that can't honor the native tool — the user explicitly asked for it, so fail loudly rather than silently substituting different behavior.

unique_id property 

unique_id: str

A unique identifier for the native tool.

If multiple instances of the same native tool can be passed to the model, subclasses should override this property to allow them to be distinguished.

label property 

label: str

Human-readable label for UI display.

Subclasses should override this to provide a meaningful label.

WebSearchTool dataclass

Bases: AbstractNativeTool

A native 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 Responses
  • Groq
  • Google
  • xAI
  • OpenRouter
Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
@dataclass(kw_only=True)
class WebSearchTool(AbstractNativeTool):
    """A native 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 Responses
    * Groq
    * Google
    * xAI
    * OpenRouter
    """

    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 Responses
    * OpenRouter
    """

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

    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, see <https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool#domain-filtering>
    * Groq, see <https://console.groq.com/docs/agentic-tooling#search-settings>
    * xAI, see <https://docs.x.ai/docs/guides/tools/search-tools#web-search-parameters>
    """

    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, see <https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool#domain-filtering>
    * Groq, see <https://console.groq.com/docs/agentic-tooling#search-settings>
    * OpenAI Responses, see <https://platform.openai.com/docs/guides/tools-web-search>
    * xAI, see <https://docs.x.ai/docs/guides/tools/search-tools#web-search-parameters>
    """

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

    Supported by:

    * Anthropic
    """

    kind: str = 'web_search'
    """The kind of tool."""

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 Responses
  • OpenRouter

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 Responses

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:

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:

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

kind class-attribute instance-attribute 

kind: str = 'web_search'

The kind of tool.

WebSearchUserLocation

Bases: TypedDict

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

Supported by:

  • Anthropic
  • OpenAI Responses
Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
class WebSearchUserLocation(TypedDict, total=False):
    """Allows you to localize search results based on a user's location.

    Supported by:

    * Anthropic
    * OpenAI Responses
    """

    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.

XSearchTool dataclass

Bases: AbstractNativeTool

A native tool that allows your agent to search X/Twitter for posts and content.

This tool is exclusive to xAI models. See https://docs.x.ai/developers/tools/x-search for more details.

Supported by:

  • xAI
Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
@dataclass(kw_only=True)
class XSearchTool(AbstractNativeTool):
    """A native tool that allows your agent to search X/Twitter for posts and content.

    This tool is exclusive to xAI models. See <https://docs.x.ai/developers/tools/x-search> for more details.

    Supported by:

    * xAI
    """

    allowed_x_handles: list[str] | None = None
    """If provided, only posts from these X handles will be included (max 10).

    Supported by:

    * xAI, see <https://docs.x.ai/developers/tools/x-search>
    """

    excluded_x_handles: list[str] | None = None
    """If provided, posts from these X handles will be excluded (max 10).

    Supported by:

    * xAI, see <https://docs.x.ai/developers/tools/x-search>
    """

    from_date: datetime | None = None
    """If provided, only posts created on or after this datetime will be included.

    Naive datetimes are interpreted as UTC by the xAI API.

    Supported by:

    * xAI, see <https://docs.x.ai/developers/tools/x-search>
    """

    to_date: datetime | None = None
    """If provided, only posts created on or before this datetime will be included.

    Naive datetimes are interpreted as UTC by the xAI API.

    Supported by:

    * xAI, see <https://docs.x.ai/developers/tools/x-search>
    """

    enable_image_understanding: bool = False
    """Enable image analysis from X posts.

    Supported by:

    * xAI, see <https://docs.x.ai/developers/tools/x-search>
    """

    enable_video_understanding: bool = False
    """Enable video analysis from X content.

    Supported by:

    * xAI, see <https://docs.x.ai/developers/tools/x-search>
    """

    include_output: bool = False
    """Include raw X search results in the response as
    [`NativeToolReturnPart`][pydantic_ai.messages.NativeToolReturnPart].

    Without this, the model uses the search results internally but only returns
    its text summary. Enabling it gives programmatic access to searched posts,
    sources, and metadata.

    Can also be set via
    [`XaiModelSettings.xai_include_x_search_output`][pydantic_ai.models.xai.XaiModelSettings.xai_include_x_search_output].

    Supported by:

    * xAI, see <https://docs.x.ai/developers/tools/x-search>
    """

    kind: str = 'x_search'
    """The kind of tool."""

    def __post_init__(self) -> None:
        if self.allowed_x_handles is not None and self.excluded_x_handles is not None:
            raise ValueError('Cannot specify both allowed_x_handles and excluded_x_handles')
        if self.allowed_x_handles and len(self.allowed_x_handles) > 10:
            raise ValueError('allowed_x_handles cannot contain more than 10 handles')
        if self.excluded_x_handles and len(self.excluded_x_handles) > 10:
            raise ValueError('excluded_x_handles cannot contain more than 10 handles')

allowed_x_handles class-attribute instance-attribute 

allowed_x_handles: list[str] | None = None

If provided, only posts from these X handles will be included (max 10).

Supported by:

excluded_x_handles class-attribute instance-attribute 

excluded_x_handles: list[str] | None = None

If provided, posts from these X handles will be excluded (max 10).

Supported by:

from_date class-attribute instance-attribute 

from_date: datetime | None = None

If provided, only posts created on or after this datetime will be included.

Naive datetimes are interpreted as UTC by the xAI API.

Supported by:

to_date class-attribute instance-attribute 

to_date: datetime | None = None

If provided, only posts created on or before this datetime will be included.

Naive datetimes are interpreted as UTC by the xAI API.

Supported by:

enable_image_understanding class-attribute instance-attribute 

enable_image_understanding: bool = False

Enable image analysis from X posts.

Supported by:

enable_video_understanding class-attribute instance-attribute 

enable_video_understanding: bool = False

Enable video analysis from X content.

Supported by:

include_output class-attribute instance-attribute 

include_output: bool = False

Include raw X search results in the response as NativeToolReturnPart.

Without this, the model uses the search results internally but only returns its text summary. Enabling it gives programmatic access to searched posts, sources, and metadata.

Can also be set via XaiModelSettings.xai_include_x_search_output.

Supported by:

kind class-attribute instance-attribute 

kind: str = 'x_search'

The kind of tool.

CodeExecutionTool dataclass

Bases: AbstractNativeTool

A native tool that allows your agent to execute code.

Supported by:

  • Anthropic
  • OpenAI Responses
  • Google
  • Bedrock (Nova2.0)
  • xAI
Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
@dataclass(kw_only=True)
class CodeExecutionTool(AbstractNativeTool):
    """A native tool that allows your agent to execute code.

    Supported by:

    * Anthropic
    * OpenAI Responses
    * Google
    * Bedrock (Nova2.0)
    * xAI
    """

    kind: str = 'code_execution'
    """The kind of tool."""

kind class-attribute instance-attribute 

kind: str = 'code_execution'

The kind of tool.

WebFetchTool dataclass

Bases: AbstractNativeTool

Allows your agent to access contents from URLs.

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

Supported by:

  • Anthropic
  • Google
Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
@dataclass(kw_only=True)
class WebFetchTool(AbstractNativeTool):
    """Allows your agent to access contents from URLs.

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

    Supported by:

    * Anthropic
    * Google
    """

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

    Supported by:

    * Anthropic
    """

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

    With Anthropic, you can only use one of `blocked_domains` or `allowed_domains`, not both.

    Supported by:

    * Anthropic, see <https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-fetch-tool#domain-filtering>
    """

    blocked_domains: list[str] | None = None
    """If provided, these domains will never be fetched.

    With Anthropic, you can only use one of `blocked_domains` or `allowed_domains`, not both.

    Supported by:

    * Anthropic, see <https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-fetch-tool#domain-filtering>
    """

    enable_citations: bool = False
    """If True, enables citations for fetched content.

    Supported by:

    * Anthropic
    """

    max_content_tokens: int | None = None
    """Maximum content length in tokens for fetched content.

    Supported by:

    * Anthropic
    """

    kind: str = 'web_fetch'
    """The kind of tool."""

max_uses class-attribute instance-attribute 

max_uses: int | None = None

If provided, the tool will stop fetching URLs after the given number of uses.

Supported by:

  • Anthropic

allowed_domains class-attribute instance-attribute 

allowed_domains: list[str] | None = None

If provided, only these domains will be fetched.

With Anthropic, you can only use one of blocked_domains or allowed_domains, not both.

Supported by:

blocked_domains class-attribute instance-attribute 

blocked_domains: list[str] | None = None

If provided, these domains will never be fetched.

With Anthropic, you can only use one of blocked_domains or allowed_domains, not both.

Supported by:

enable_citations class-attribute instance-attribute 

enable_citations: bool = False

If True, enables citations for fetched content.

Supported by:

  • Anthropic

max_content_tokens class-attribute instance-attribute 

max_content_tokens: int | None = None

Maximum content length in tokens for fetched content.

Supported by:

  • Anthropic

kind class-attribute instance-attribute 

kind: str = 'web_fetch'

The kind of tool.

ImageGenerationTool dataclass

Bases: AbstractNativeTool

A native tool that allows your agent to generate images.

Supported by:

  • OpenAI Responses
  • Google
Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
@dataclass(kw_only=True)
class ImageGenerationTool(AbstractNativeTool):
    """A native tool that allows your agent to generate images.

    Supported by:

    * OpenAI Responses
    * Google
    """

    action: Literal['generate', 'edit', 'auto'] = 'auto'
    """Whether to generate a new image or edit an existing image.

    Supported by:

    * OpenAI Responses. Default: 'auto'.
    """

    background: Literal['transparent', 'opaque', 'auto'] = 'auto'
    """Background type for the generated image.

    Supported by:

    * OpenAI Responses. 'transparent' is only supported for 'png' and 'webp' output formats.
    """

    input_fidelity: Literal['high', 'low'] | None = None
    """
    Control how much effort the model will exert to match the style and features,
    especially facial features, of input images.

    Supported by:

    * OpenAI Responses. Default: 'low'.
    """

    moderation: Literal['auto', 'low'] = 'auto'
    """Moderation level for the generated image.

    Supported by:

    * OpenAI Responses
    """

    model: ImageGenerationModelName | None = None
    """The image generation model to use.

    Supported by:

    * OpenAI Responses. Defaults to the provider's image generation model selection.
      Known image generation models include `gpt-image-2`, `gpt-image-1.5`,
      `gpt-image-1`, and `gpt-image-1-mini`.

    This selects the underlying image generation model used by the tool; it does
    not change the agent's conversational model.
    """

    output_compression: int | None = None
    """Compression level for the output image.

    Supported by:

    * OpenAI Responses. Only supported for 'jpeg' and 'webp' output formats. Default: 100.
    * Google (Vertex AI only). Only supported for 'jpeg' output format. Default: 75.
      Setting this will default `output_format` to 'jpeg' if not specified.
    """

    output_format: Literal['png', 'webp', 'jpeg'] | None = None
    """The output format of the generated image.

    Supported by:

    * OpenAI Responses. Default: 'png'.
    * Google (Vertex AI only). Default: 'png', or 'jpeg' if `output_compression` is set.
    """

    partial_images: int = 0
    """
    Number of partial images to generate in streaming mode.

    Supported by:

    * OpenAI Responses. Supports 0 to 3.
    """

    quality: Literal['low', 'medium', 'high', 'auto'] = 'auto'
    """The quality of the generated image.

    Supported by:

    * OpenAI Responses
    """

    size: Literal['auto', '1024x1024', '1024x1536', '1536x1024', '512', '1K', '2K', '4K'] | None = None
    """The size of the generated image.

    * OpenAI Responses: 'auto' (default: model selects the size based on the prompt), '1024x1024', '1024x1536', '1536x1024'
    * Google (Gemini 3 Pro Image and later): '512' (Gemini 3.1 Flash Image only), '1K' (default), '2K', '4K'
    """

    aspect_ratio: ImageAspectRatio | None = None
    """The aspect ratio to use for generated images.

    Supported by:

    * Google image-generation models (Gemini)
    * OpenAI Responses (maps '1:1', '2:3', and '3:2' to supported sizes)
    """

    kind: str = 'image_generation'
    """The kind of tool."""

action class-attribute instance-attribute 

action: Literal['generate', 'edit', 'auto'] = 'auto'

Whether to generate a new image or edit an existing image.

Supported by:

  • OpenAI Responses. Default: 'auto'.

background class-attribute instance-attribute 

background: Literal["transparent", "opaque", "auto"] = (
    "auto"
)

Background type for the generated image.

Supported by:

  • OpenAI Responses. 'transparent' is only supported for 'png' and 'webp' output formats.

input_fidelity class-attribute instance-attribute 

input_fidelity: Literal['high', 'low'] | None = None

Control how much effort the model will exert to match the style and features, especially facial features, of input images.

Supported by:

  • OpenAI Responses. Default: 'low'.

moderation class-attribute instance-attribute 

moderation: Literal['auto', 'low'] = 'auto'

Moderation level for the generated image.

Supported by:

  • OpenAI Responses

model class-attribute instance-attribute 

model: ImageGenerationModelName | None = None

The image generation model to use.

Supported by:

  • OpenAI Responses. Defaults to the provider's image generation model selection. Known image generation models include gpt-image-2, gpt-image-1.5, gpt-image-1, and gpt-image-1-mini.

This selects the underlying image generation model used by the tool; it does not change the agent's conversational model.

output_compression class-attribute instance-attribute 

output_compression: int | None = None

Compression level for the output image.

Supported by:

  • OpenAI Responses. Only supported for 'jpeg' and 'webp' output formats. Default: 100.
  • Google (Vertex AI only). Only supported for 'jpeg' output format. Default: 75. Setting this will default output_format to 'jpeg' if not specified.

output_format class-attribute instance-attribute 

output_format: Literal['png', 'webp', 'jpeg'] | None = None

The output format of the generated image.

Supported by:

  • OpenAI Responses. Default: 'png'.
  • Google (Vertex AI only). Default: 'png', or 'jpeg' if output_compression is set.

partial_images class-attribute instance-attribute 

partial_images: int = 0

Number of partial images to generate in streaming mode.

Supported by:

  • OpenAI Responses. Supports 0 to 3.

quality class-attribute instance-attribute 

quality: Literal['low', 'medium', 'high', 'auto'] = 'auto'

The quality of the generated image.

Supported by:

  • OpenAI Responses

size class-attribute instance-attribute 

size: (
    Literal[
        "auto",
        "1024x1024",
        "1024x1536",
        "1536x1024",
        "512",
        "1K",
        "2K",
        "4K",
    ]
    | None
) = None

The size of the generated image.

  • OpenAI Responses: 'auto' (default: model selects the size based on the prompt), '1024x1024', '1024x1536', '1536x1024'
  • Google (Gemini 3 Pro Image and later): '512' (Gemini 3.1 Flash Image only), '1K' (default), '2K', '4K'

aspect_ratio class-attribute instance-attribute 

aspect_ratio: ImageAspectRatio | None = None

The aspect ratio to use for generated images.

Supported by:

  • Google image-generation models (Gemini)
  • OpenAI Responses (maps '1:1', '2:3', and '3:2' to supported sizes)

kind class-attribute instance-attribute 

kind: str = 'image_generation'

The kind of tool.

MemoryTool dataclass

Bases: AbstractNativeTool

A native tool that allows your agent to use memory.

Supported by:

  • Anthropic
Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
478
479
480
481
482
483
484
485
486
487
488
@dataclass(kw_only=True)
class MemoryTool(AbstractNativeTool):
    """A native tool that allows your agent to use memory.

    Supported by:

    * Anthropic
    """

    kind: str = 'memory'
    """The kind of tool."""

kind class-attribute instance-attribute 

kind: str = 'memory'

The kind of tool.

MCPServerTool dataclass

Bases: AbstractNativeTool

A native tool that allows your agent to use MCP servers.

Supported by:

  • OpenAI Responses
  • Anthropic
  • xAI
Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
@dataclass(kw_only=True)
class MCPServerTool(AbstractNativeTool):
    """A native tool that allows your agent to use MCP servers.

    Supported by:

    * OpenAI Responses
    * Anthropic
    * xAI
    """

    id: str
    """A unique identifier for the MCP server."""

    url: str
    """The URL of the MCP server to use.

    For OpenAI Responses, it is possible to use `connector_id` by providing it as `x-openai-connector:<connector_id>`.
    """

    authorization_token: str | None = None
    """Authorization header to use when making requests to the MCP server.

    Supported by:

    * OpenAI Responses
    * Anthropic
    * xAI
    """

    description: str | None = None
    """A description of the MCP server.

    Supported by:

    * OpenAI Responses
    * xAI
    """

    allowed_tools: list[str] | None = None
    """A list of tools that the MCP server can use.

    Supported by:

    * OpenAI Responses
    * Anthropic
    * xAI
    """

    headers: dict[str, str] | None = None
    """Optional HTTP headers to send to the MCP server.

    Use for authentication or other purposes.

    Supported by:

    * OpenAI Responses
    * xAI
    """

    kind: str = 'mcp_server'

    @property
    def unique_id(self) -> str:
        return ':'.join([self.kind, self.id])

    @property
    def label(self) -> str:
        return f'MCP: {self.id}'

id instance-attribute 

id: str

A unique identifier for the MCP server.

url instance-attribute 

url: str

The URL of the MCP server to use.

For OpenAI Responses, it is possible to use connector_id by providing it as x-openai-connector:<connector_id>.

authorization_token class-attribute instance-attribute 

authorization_token: str | None = None

Authorization header to use when making requests to the MCP server.

Supported by:

  • OpenAI Responses
  • Anthropic
  • xAI

description class-attribute instance-attribute 

description: str | None = None

A description of the MCP server.

Supported by:

  • OpenAI Responses
  • xAI

allowed_tools class-attribute instance-attribute 

allowed_tools: list[str] | None = None

A list of tools that the MCP server can use.

Supported by:

  • OpenAI Responses
  • Anthropic
  • xAI

headers class-attribute instance-attribute 

headers: dict[str, str] | None = None

Optional HTTP headers to send to the MCP server.

Use for authentication or other purposes.

Supported by:

  • OpenAI Responses
  • xAI

FileSearchTool dataclass

Bases: AbstractNativeTool

A native tool that allows your agent to search through uploaded files using vector search.

This tool provides a fully managed Retrieval-Augmented Generation (RAG) system that handles file storage, chunking, embedding generation, and context injection into prompts.

Supported by:

  • OpenAI Responses
  • Google (Gemini)
  • xAI (mapped to collections search)
Source code in pydantic_ai_slim/pydantic_ai/native_tools/__init__.py 
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
@dataclass(kw_only=True)
class FileSearchTool(AbstractNativeTool):
    """A native tool that allows your agent to search through uploaded files using vector search.

    This tool provides a fully managed Retrieval-Augmented Generation (RAG) system that handles
    file storage, chunking, embedding generation, and context injection into prompts.

    Supported by:

    * OpenAI Responses
    * Google (Gemini)
    * xAI (mapped to collections search)
    """

    file_store_ids: Sequence[str]
    """The file store IDs to search through.

    For OpenAI, these are the IDs of vector stores created via the OpenAI API.
    For Google, these are file search store names that have been uploaded and processed via the Gemini Files API.
    For xAI, these are collection IDs for the xAI collections search tool.
    """

    kind: str = 'file_search'
    """The kind of tool."""

file_store_ids instance-attribute 

file_store_ids: Sequence[str]

The file store IDs to search through.

For OpenAI, these are the IDs of vector stores created via the OpenAI API. For Google, these are file search store names that have been uploaded and processed via the Gemini Files API. For xAI, these are collection IDs for the xAI collections search tool.

kind class-attribute instance-attribute 

kind: str = 'file_search'

The kind of tool.

SUPPORTED_NATIVE_TOOLS module-attribute 

SUPPORTED_NATIVE_TOOLS = frozenset(values())

Set of all native tool types.