pydantic_ai.tools
Bases: Generic[RunContextAgentDepsT]
Information about the current call.
Dependencies for the agent.
Type: RunContextAgentDepsT
The model used in this run.
Type: Model
LLM usage associated with the run.
Type: RunUsage
The agent running this context, or None if not set.
Type: AbstractAgent[RunContextAgentDepsT, Any] | None Default: field(default=None, repr=False)
The original user prompt passed to the run.
Type: str | Sequence[_messages.UserContent] | None Default: None
Messages exchanged in the conversation so far.
Type: list[_messages.ModelMessage] Default: field(default_factory=(list[_messages.ModelMessage]))
Pydantic validation context for tool args and run outputs.
Type: Any Default: None
The tracer to use for tracing the run.
Type: Tracer Default: field(default_factory=NoOpTracer)
Whether to include the content of the messages in the trace.
Type: bool Default: False
Instrumentation settings version, if instrumentation is enabled.
Type: int Default: DEFAULT_INSTRUMENTATION_VERSION
Number of retries for each tool so far.
Type: dict[str, int] Default: field(default_factory=(dict[str, int]))
The ID of the tool call.
Type: str | None Default: None
Name of the tool being called.
Type: str | None Default: None
Number of retries so far.
For tool calls, this is the number of retries of the specific tool. For output validation, this is the number of output validation retries.
Type: int Default: 0
The maximum number of retries allowed.
For tool calls, this is the maximum retries for the specific tool. For output validation, this is the maximum output validation retries.
Type: int Default: 0
The current step in the run.
Type: int Default: 0
Whether a tool call that required approval has now been approved.
Type: bool Default: False
Metadata from DeferredToolResults.metadata[tool_call_id], available when tool_call_approved=True.
Type: Any Default: None
Whether the output passed to an output validator is partial.
Type: bool Default: False
“Unique identifier for the agent run.
Type: str | None Default: None
Metadata associated with this agent run, if configured.
Type: dict[str, Any] | None Default: None
The resolved model settings for the current run step.
Populated before each model request, after all model settings layers
(model defaults, agent-level, capability, and run-level) have been merged.
Available in model request hooks (before_model_request, wrap_model_request,
after_model_request). Currently None in tool hooks, output validators,
and during agent construction.
Type: ModelSettings | None Default: None
Whether this is the last attempt at running this tool before an error is raised.
Type: bool
Tool calls that require approval or external execution.
This can be used as an agent’s output_type and will be used as the output of the agent run if the model called any deferred tools.
Results can be passed to the next agent run using a DeferredToolResults object with the same tool call IDs.
See deferred tools docs for more information.
Tool calls that require external execution.
Type: list[ToolCallPart] Default: field(default_factory=(list[ToolCallPart]))
Tool calls that require human-in-the-loop approval.
Type: list[ToolCallPart] Default: field(default_factory=(list[ToolCallPart]))
Metadata for deferred tool calls, keyed by tool_call_id.
Type: dict[str, dict[str, Any]] Default: field(default_factory=(dict[str, dict[str, Any]]))
Indicates that a tool call has been approved and that the tool function should be executed.
Optional tool call arguments to use instead of the original arguments.
Type: dict[str, Any] | None Default: None
Indicates that a tool call has been denied and that a denial message should be returned to the model.
The message to return to the model.
Type: str Default: 'The tool call was denied.'
Results for deferred tool calls from a previous run that required approval or external execution.
The tool call IDs need to match those from the DeferredToolRequests output object from the previous run.
See deferred tools docs for more information.
Map of tool call IDs to results for tool calls that required external execution.
Type: dict[str, DeferredToolCallResult | Any] Default: field(default_factory=(dict[str, DeferredToolCallResult | Any]))
Map of tool call IDs to results for tool calls that required human-in-the-loop approval.
Type: dict[str, bool | DeferredToolApprovalResult] Default: field(default_factory=(dict[str, bool | DeferredToolApprovalResult]))
Metadata for deferred tool calls, keyed by tool_call_id. Each value will be available in the tool’s RunContext as tool_call_metadata.
Type: dict[str, dict[str, Any]] Default: field(default_factory=(dict[str, dict[str, Any]]))
Bases: Generic[ToolAgentDepsT]
A tool function for an agent.
The base JSON schema for the tool’s parameters.
This schema may be modified by the prepare function or by the Model class prior to including it in an API request.
Type: _function_schema.FunctionSchema Default: function_schema or _function_schema.function_schema(function, schema_generator, takes_ctx=takes_ctx, docstring_format=docstring_format, require_parameter_descriptions=require_parameter_descriptions)
def __init__(
function: ToolFuncEither[ToolAgentDepsT, ToolParams],
takes_ctx: bool | None = None,
max_retries: int | None = None,
name: str | None = None,
description: str | None = None,
prepare: ToolPrepareFunc[ToolAgentDepsT] | None = None,
args_validator: ArgsValidatorFunc[ToolAgentDepsT, ToolParams] | None = None,
docstring_format: DocstringFormat = 'auto',
require_parameter_descriptions: bool = False,
schema_generator: type[GenerateJsonSchema] = GenerateToolJsonSchema,
strict: bool | None = None,
sequential: bool = False,
requires_approval: bool = False,
metadata: dict[str, Any] | None = None,
timeout: float | None = None,
defer_loading: bool = False,
function_schema: _function_schema.FunctionSchema | None = None,
)
Create a new tool instance.
Example usage:
from pydantic_ai import Agent, RunContext, Tool
async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
return f'{ctx.deps} {x} {y}'
agent = Agent('test', tools=[Tool(my_tool)])
or with a custom prepare method:
from pydantic_ai import Agent, RunContext, Tool
from pydantic_ai.tools import ToolDefinition
async def my_tool(ctx: RunContext[int], x: int, y: int) -> str:
return f'{ctx.deps} {x} {y}'
async def prep_my_tool(
ctx: RunContext[int], tool_def: ToolDefinition
) -> ToolDefinition | None:
# only register the tool if `deps == 42`
if ctx.deps == 42:
return tool_def
agent = Agent('test', tools=[Tool(my_tool, prepare=prep_my_tool)])
The Python function to call as the tool.
Whether the function takes a RunContext first argument,
this is inferred if unset.
Maximum number of retries allowed for this tool, set to the agent default if None.
Name of the tool, inferred from the function if None.
Description of the tool, inferred from the function if None.
prepare : ToolPrepareFunc[ToolAgentDepsT] | None Default: None
custom method to prepare the tool definition for each step, return None to omit this
tool from a given step. This is useful if you want to customise a tool at call time,
or omit it completely from a step. See ToolPrepareFunc.
args_validator : ArgsValidatorFunc[ToolAgentDepsT, ToolParams] | None Default: None
custom method to validate tool arguments after schema validation has passed,
before execution. The validator receives the already-validated and type-converted parameters,
with RunContext as the first argument.
Should raise ModelRetry on validation failure,
return None on success.
See ArgsValidatorFunc.
The format of the docstring, see DocstringFormat.
Defaults to 'auto', such that the format is inferred from the structure of the docstring.
require_parameter_descriptions : bool Default: False
If True, raise an error if a parameter description is missing. Defaults to False.
schema_generator : type[GenerateJsonSchema] Default: GenerateToolJsonSchema
The JSON schema generator class to use. Defaults to GenerateToolJsonSchema.
Whether to enforce JSON schema compliance (only affects OpenAI).
See ToolDefinition for more info.
sequential : bool Default: False
Whether the function requires a sequential/serial execution environment. Defaults to False.
requires_approval : bool Default: False
Whether this tool requires human-in-the-loop approval. Defaults to False. See the tools documentation for more info.
Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
Timeout in seconds for tool execution. If the tool takes longer, a retry prompt is returned to the model. Defaults to None (no timeout).
defer_loading : bool Default: False
Whether to hide this tool until it’s discovered via tool search. Defaults to False. See Tool Search for more info.
function_schema : _function_schema.FunctionSchema | None Default: None
The function schema to use for the tool. If not provided, it will be generated.
@classmethod
def from_schema(
cls,
function: Callable[..., Any],
name: str,
description: str | None,
json_schema: JsonSchemaValue,
takes_ctx: bool = False,
sequential: bool = False,
args_validator: ArgsValidatorFunc[Any, ...] | None = None,
) -> Self
Creates a Pydantic tool from a function and a JSON schema.
Self — A Pydantic tool that calls the function
The function to call.
This will be called with keywords only. Schema validation of
the arguments is skipped, but a custom args_validator will
still run if provided.
name : str
The unique name of the tool that clearly communicates its purpose
Used to tell the model how/when/why to use the tool. You can provide few-shot examples as a part of the description.
The schema for the function arguments
takes_ctx : bool Default: False
An optional boolean parameter indicating whether the function accepts the context object as an argument.
sequential : bool Default: False
Whether the function requires a sequential/serial execution environment. Defaults to False.
custom method to validate tool arguments after schema validation has passed,
before execution. The validator receives the already-validated and type-converted parameters,
with RunContext as the first argument.
Should raise ModelRetry on validation failure,
return None on success.
See ArgsValidatorFunc.
@async
def prepare_tool_def(ctx: RunContext[ToolAgentDepsT]) -> ToolDefinition | None
Get the tool definition.
By default, this method creates a tool definition, then either returns it, or calls self.prepare
if it’s set.
ToolDefinition | None — return a ToolDefinition or None if the tools should not be registered for this run.
Definition of a tool passed to a model.
This is used for both function tools and output tools.
The name of the tool.
Type: str
The JSON schema for the tool’s parameters.
Type: ObjectJsonSchema Default: field(default_factory=(lambda: \{'type': 'object', 'properties': \{\}\}))
The description of the tool.
Type: str | None Default: None
The key in the outer [TypedDict] that wraps an output tool.
This will only be set for output tools which don’t have an object JSON schema.
Type: str | None Default: None
Whether to enforce (vendor-specific) strict JSON schema validation for tool calls.
Setting this to True while using a supported model generally imposes some restrictions on the tool’s JSON schema
in exchange for guaranteeing the API responses strictly match that schema.
When False, the model may be free to generate other properties or types (depending on the vendor).
When None (the default), the value will be inferred based on the compatibility of the parameters_json_schema.
Note: this is currently supported by OpenAI and Anthropic models.
Type: bool | None Default: None
Whether this tool requires a sequential/serial execution environment.
Type: bool Default: False
The kind of tool:
'function': a tool that will be executed by Pydantic AI during an agent run and has its result returned to the model'output': a tool that passes through an output value that ends the run'external': a tool whose result will be produced outside of the Pydantic AI agent run in which it was called, because it depends on an upstream service (or user) or could take longer to generate than it’s reasonable to keep the agent process running. See the tools documentation for more info.'unapproved': a tool that requires human-in-the-loop approval. See the tools documentation for more info.
Type: ToolKind Default: field(default='function')
Tool metadata that can be set by the toolset this tool came from. It is not sent to the model, but can be used for filtering and tool behavior customization.
For MCP tools, this contains the meta, annotations, and output_schema fields from the tool definition.
Type: dict[str, Any] | None Default: None
Timeout in seconds for tool execution.
If the tool takes longer than this, a retry prompt is returned to the model. Defaults to None (no timeout).
Type: float | None Default: None
Whether this tool should be hidden from the model until discovered via tool search.
See Tool Search for more info.
Type: bool Default: False
If set, this function tool is a local fallback for the builtin tool with the given unique_id.
When the model supports the corresponding builtin tool natively, this function tool is removed from the request. When the model does not support the builtin, the builtin is removed and this function tool stays.
Type: str | None Default: None
Whether calls to this tool will be deferred.
See the tools documentation for more info.
Type: bool
Type variable for agent dependencies.
Default: TypeVar('AgentDepsT', default=None, contravariant=True)
Retrieval function param spec.
Default: ParamSpec('ToolParams', default=...)
A function that may or maybe not take RunContext as an argument, and may or may not be async.
Functions which return None are excluded from model requests.
Usage SystemPromptFunc[AgentDepsT].
Type: TypeAlias Default: Callable[[RunContext[AgentDepsT]], str | None] | Callable[[RunContext[AgentDepsT]], Awaitable[str | None]] | Callable[[], str | None] | Callable[[], Awaitable[str | None]]
A tool function that takes RunContext as the first argument.
Usage ToolContextFunc[AgentDepsT, ToolParams].
Type: TypeAlias Default: Callable[Concatenate[RunContext[AgentDepsT], ToolParams], Any]
A tool function that does not take RunContext as the first argument.
Usage ToolPlainFunc[ToolParams].
Type: TypeAlias Default: Callable[ToolParams, Any]
Either kind of tool function.
This is just a union of ToolFuncContext and
ToolFuncPlain.
Usage ToolFuncEither[AgentDepsT, ToolParams].
Type: TypeAlias Default: ToolFuncContext[AgentDepsT, ToolParams] | ToolFuncPlain[ToolParams]
A function that validates tool arguments before execution.
The validator receives the same typed parameters as the tool function,
with RunContext as the first argument for dependency access.
Should raise ModelRetry on validation failure.
Type: TypeAlias Default: Callable[Concatenate[RunContext[AgentDepsT], ToolParams], Awaitable[None]] | Callable[Concatenate[RunContext[AgentDepsT], ToolParams], None]
Definition of a function that can prepare a tool definition at call time. Both sync and async functions are accepted.
See tool docs for more information.
Example — here only_if_42 is valid as a ToolPrepareFunc:
from pydantic_ai import RunContext, Tool
from pydantic_ai.tools import ToolDefinition
def only_if_42(
ctx: RunContext[int], tool_def: ToolDefinition
) -> ToolDefinition | None:
if ctx.deps == 42:
return tool_def
def hitchhiker(ctx: RunContext[int], answer: str) -> str:
return f'{ctx.deps} {answer}'
hitchhiker = Tool(hitchhiker, prepare=only_if_42)
Usage ToolPrepareFunc[AgentDepsT].
Type: TypeAlias Default: Callable[[RunContext[AgentDepsT], 'ToolDefinition'], Union[Awaitable['ToolDefinition | None'], 'ToolDefinition', None]]
Definition of a function that can prepare the tool definition of all tools for each step. 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. Both sync and async functions are accepted.
Example — here turn_on_strict_if_openai is valid as a ToolsPrepareFunc:
from dataclasses import replace
from pydantic_ai import Agent, RunContext
from pydantic_ai.tools import ToolDefinition
def turn_on_strict_if_openai(
ctx: RunContext[None], tool_defs: list[ToolDefinition]
) -> list[ToolDefinition] | None:
if ctx.model.system == 'openai':
return [replace(tool_def, strict=True) for tool_def in tool_defs]
return tool_defs
agent = Agent('openai:gpt-5.2', prepare_tools=turn_on_strict_if_openai)
Usage ToolsPrepareFunc[AgentDepsT].
Type: TypeAlias Default: Callable[[RunContext[AgentDepsT], list['ToolDefinition']], Awaitable['list[ToolDefinition] | None'] | list['ToolDefinition'] | None]
Definition of a function that can prepare a builtin tool at call time.
This is useful if you want to customize the builtin tool based on the run context (e.g. user dependencies), or omit it completely from a step.
Type: TypeAlias Default: Callable[[RunContext[AgentDepsT]], Awaitable[AbstractBuiltinTool | None] | AbstractBuiltinTool | None]
A builtin tool or a function that dynamically produces one.
This is a convenience alias for AbstractBuiltinTool | BuiltinToolFunc[AgentDepsT].
Type: TypeAlias Default: AbstractBuiltinTool | BuiltinToolFunc[AgentDepsT]
Supported docstring formats.
'google'— Google-style docstrings.'numpy'— Numpy-style docstrings.'sphinx'— Sphinx-style docstrings.'auto'— Automatically infer the format based on the structure of the docstring.
Type: TypeAlias Default: Literal['google', 'numpy', 'sphinx', 'auto']
Result for a tool call that required human-in-the-loop approval.
Type: TypeAlias Default: Annotated[ToolApproved | ToolDenied, Discriminator('kind')]
Result for a tool call that required external execution.
Type: TypeAlias Default: Annotated[Annotated[ToolReturn, Tag('tool-return')] | Annotated[ModelRetry, Tag('model-retry')] | Annotated[RetryPromptPart, Tag('retry-prompt')], Discriminator(_deferred_tool_call_result_discriminator)]
Result for a tool call that required approval or external execution.
Default: DeferredToolApprovalResult | DeferredToolCallResult
Type variable for agent dependencies for a tool.
Default: TypeVar('ToolAgentDepsT', default=object, contravariant=True)
Type representing JSON schema of an object, e.g. where "type": "object".
This type is used to define tools parameters (aka arguments) in ToolDefinition.
With PEP-728 this should be a TypedDict with type: Literal['object'], and extra_parts=Any
Type: TypeAlias Default: dict[str, Any]
Kind of tool.
Type: TypeAlias Default: Literal['function', 'output', 'external', 'unapproved']