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: Agent[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
Unique identifier for the conversation this run belongs to.
A conversation spans potentially multiple agent runs that share message history.
Resolved at the start of Agent.run (etc.) from the explicit conversation_id
argument, the most recent conversation_id on message_history, or a fresh UUID7.
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
The tool manager for the current run step.
Provides access to tool validation and execution, including tracing and capability hooks. Useful for toolsets that need to dispatch tool calls programmatically (e.g. code execution sandboxes).
Not available in TemporalRunContext — it is not serializable across
Temporal activity boundaries.
Type: ToolManager[RunContextAgentDepsT] | 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]]))
def build_results(
approvals: dict[str, bool | DeferredToolApprovalResult] | None = None,
calls: dict[str, DeferredToolCallResult | Any] | None = None,
metadata: dict[str, dict[str, Any]] | None = None,
approve_all: bool = False,
) -> DeferredToolResults
Create a DeferredToolResults for these requests.
Results for tool calls that required approval. Keys must match
tool_call_ids in self.approvals.
Results for tool calls that required external execution. Keys must
match tool_call_ids in self.calls.
Per-call metadata, keyed by tool_call_id.
approve_all : bool Default: False
If True, every approval-requesting call not already listed in
approvals is approved (with default ToolApproved()).
ValueError— If a key inapprovals/callsdoesn’t match a pending request of the appropriate kind.
def remaining(results: DeferredToolResults) -> DeferredToolRequests | None
Return unresolved requests after applying results, or None if all resolved.
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]]))
def update(other: DeferredToolResults) -> None
Update this DeferredToolResults with entries from another, in-place.
def to_tool_call_results() -> dict[str, DeferredToolResult]
Convert results into the internal per-call format used by the tool-execution pipeline.
Normalizes True/False approvals to ToolApproved/ToolDenied, and wraps
plain external-call values in ToolReturn.
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, tool_name=(self.name), 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,
include_return_schema: bool | None = None,
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.
Whether to include the return schema in the tool definition sent to the model.
If None, defaults to False unless the IncludeToolReturnSchemas capability is used.
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 something explicitly surfaces it.
Carries two meanings depending on where in the pipeline you observe it:
- User-input intent — set on
Tool(defer_loading=True)(or via a custom toolset) to opt this tool into deferred loading. This is whatprepare_toolshooks and other pre-toolset-wrapping consumers see, and is the value users persist onToolDefinition. - Current visibility state — after a toolset like
ToolSearchToolsetprocesses the corpus, it flips this field toFalsefor tools whose discovery shows up in message history, so downstreamModel.prepare_requestfiltering and adapter wire formatting can read “should this be on the wire?” off a single boolean.
The dual meaning is acknowledged tech debt: a future RunContext.loaded_tools /
equivalent will surface (2) as a derived view so this field cleanly stays a user-input
flag. Until then, the toolset-set value flows through agent-graph plumbing on a per-step
ToolDefinition instance built via replace(...); user-persisted definitions are not
mutated.
See Tool Search for more info.
Type: bool Default: False
If set, this tool is dropped from the wire when the named native tool is supported by the model.
Generic version of the old prefer_builtin flag: a function tool carrying
unless_native='web_search' is treated as a local fallback for the
WebSearchTool native tool and silently
removed from the request whenever the model handles WebSearchTool natively. It
stays in the request when the native tool isn’t supported.
Type: Annotated[str | None, Field(validation_alias=(AliasChoices(unless_native, prefer_native, prefer_builtin)))] Default: None
If set, this tool is kept on the wire when the named native tool is supported, with the
native tool’s adapter applying any wire-format adjustments (e.g. setting defer_loading=True
on the request param for the framework-managed tool-search native tool).
Symmetric pair with unless_native:
unless_native='X'— drop me from the wire when X is supported (local fallback).with_native='X'— keep me on the wire when X is supported, formatted via X’s adapter (corpus member managed by the native tool).
When the named native tool is unsupported, a tool with with_native and defer_loading=True
is dropped (the corpus member is currently undiscovered, so the model can’t call it on
this provider); otherwise it’s kept as a regular function tool.
Type: str | None Default: None
Discriminator for a cross-provider typed call/return shape (e.g. 'tool-search').
Set by the framework when a tool emits parts that should be promoted to a typed
subclass (such as ToolSearchCallPart
and ToolSearchReturnPart). Leave as
None for user-defined function tools — they go through the standard
ToolCallPart /
ToolReturnPart shapes.
To detect a tool-search part regardless of execution path (native server-side vs.
local fallback), check part.tool_kind == 'tool-search' — this works across both
call/return and both server/local variants.
Distinct from kind, which is about invocation
semantics ('function' / 'output' / 'external' / 'unapproved').
Type: ToolPartKind | None Default: None
The JSON schema for the tool’s return value.
For models that natively support return schemas (e.g. Google Gemini), this is passed as a
structured field in the API request. For other models, it is injected into the tool’s
description as JSON text. Only included when include_return_schema resolves to True.
Type: ObjectJsonSchema | None Default: None
Whether to include the return schema in the tool definition sent to the model.
When True, the return_schema will be preserved and sent to the model.
When False, the return_schema will be cleared before sending.
When None (default), defaults to False unless the
IncludeToolReturnSchemas capability is used.
Type: bool | None Default: None
The function signature shape for this tool.
Lazily computed from parameters_json_schema and return_schema on first access.
Name and description are not stored on the signature — pass them at render time
via sig.render(body, name=td.name, description=td.description).
Type: FunctionSignature
Whether calls to this tool will be deferred.
See the tools documentation for more info.
Type: bool
def render_signature(body: str, kwargs: Any = {}) -> str
Render the function signature with this tool’s name and description.
Convenience wrapper around self.function_signature.render() that
supplies name and description from this tool definition.
@async
def matches_tool_selector(
selector: ToolSelector[AgentDepsT],
ctx: RunContext[AgentDepsT],
tool_def: ToolDefinition,
) -> bool
Check whether a tool definition matches a ToolSelector.
bool — True if the tool matches the selector.
The selector to check against.
ctx : RunContext[AgentDepsT]
The current run context.
tool_def : ToolDefinition
The tool definition to test.
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.capabilities import PrepareTools
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', capabilities=[PrepareTools(turn_on_strict_if_openai)])
Usage ToolsPrepareFunc[AgentDepsT].
Type: TypeAlias Default: Callable[[RunContext[AgentDepsT], list['ToolDefinition']], Awaitable['list[ToolDefinition] | None'] | list['ToolDefinition'] | None]
A callable that decides whether a tool matches a selection criterion.
Receives the run context and a tool definition, returns True if the tool is selected.
Both sync and async functions are accepted.
Usage ToolSelectorFunc[AgentDepsT].
Type: TypeAlias Default: Callable[[RunContext[AgentDepsT], 'ToolDefinition'], bool | Awaitable[bool]]
Specifies which tools a capability or toolset wrapper should apply to.
'all': matches every tool (default for most capabilities).Sequence[str]: matches tools whose names are in the sequence.dict[str, Any]: matches tools whosemetadatacontains all the specified key-value pairs (deep inclusion check — nested dicts are compared recursively, and the tool’s metadata may have additional keys).Callable[[RunContext, ToolDefinition], bool | Awaitable[bool]]: custom sync or async predicate.
The first three forms are serializable for use in agent specs (YAML/JSON).
Usage ToolSelector[AgentDepsT].
Type: TypeAlias Default: Literal['all'] | Sequence[str] | dict[str, Any] | ToolSelectorFunc[AgentDepsT]
Definition of a function that can prepare a native tool at call time.
This is useful if you want to customize the native tool based on the run context (e.g. user dependencies), or omit it completely from a step.
Type: TypeAlias Default: Callable[[RunContext[AgentDepsT]], Awaitable[AbstractNativeTool | None] | AbstractNativeTool | None]
A native tool or a function that dynamically produces one.
This is a convenience alias for AbstractNativeTool | NativeToolFunc[AgentDepsT].
Type: TypeAlias Default: AbstractNativeTool | NativeToolFunc[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']