pydantic_ai.toolsets
Bases: ABC, Generic[AgentDepsT]
A toolset is a collection of tools that can be used by an agent.
It is responsible for:
- Listing the tools it contains
- Validating the arguments of the tools
- Calling the tools
See toolset docs for more information.
An ID for the toolset that is unique among all toolsets registered with the same agent.
If you’re implementing a concrete implementation that users can instantiate more than once, you should let them optionally pass a custom ID to the constructor and return that here.
A toolset needs to have an ID in order to be used in a durable execution environment like Temporal, in which case the ID will be used to identify the toolset’s activities within the workflow.
The name of the toolset for use in error messages.
Type: str
A hint for how to avoid name conflicts with other toolsets for use in error messages.
Type: str
@async
def for_run(ctx: RunContext[AgentDepsT]) -> AbstractToolset[AgentDepsT]
Return the toolset to use for this agent run.
Called once per run, before __aenter__. Override this to return a fresh instance
for per-run state isolation. Default: return self (shared across runs).
AbstractToolset[AgentDepsT]
@async
def for_run_step(ctx: RunContext[AgentDepsT]) -> AbstractToolset[AgentDepsT]
Return the toolset to use for this run step.
Called at the start of each run step. Override this to return a modified
instance for per-step state transitions. If returning a new instance,
you are responsible for managing any lifecycle transitions (exiting old
inner toolsets, entering new ones). Default: return self (no per-step changes).
AbstractToolset[AgentDepsT]
@async
def __aenter__() -> Self
Enter the toolset context.
This is where you can set up network connections in a concrete implementation.
@async
def __aexit__(args: Any = ()) -> bool | None
Exit the toolset context.
This is where you can tear down network connections in a concrete implementation.
@async
def get_instructions(
ctx: RunContext[AgentDepsT],
) -> str | InstructionPart | Sequence[str | InstructionPart] | None
Return instructions for how to use this toolset’s tools.
Override this method to provide instructions that help the agent understand how to use the tools in this toolset effectively.
Simple implementations can return a plain str; advanced implementations can return
InstructionPart objects to indicate whether
each instruction block is static or dynamic for caching purposes.
str | InstructionPart | Sequence[str | InstructionPart] | None — Instruction string, InstructionPart, list of either, or None.
str | InstructionPart | Sequence[str | InstructionPart] | None — Plain str values are treated as dynamic instructions by default.
ctx : RunContext[AgentDepsT]
The run context for this agent run.
@abstractmethod
@async
def get_tools(ctx: RunContext[AgentDepsT]) -> dict[str, ToolsetTool[AgentDepsT]]
The tools that are available in this toolset.
dict[str, ToolsetTool[AgentDepsT]]
@abstractmethod
@async
def call_tool(
name: str,
tool_args: dict[str, Any],
ctx: RunContext[AgentDepsT],
tool: ToolsetTool[AgentDepsT],
) -> Any
Call a tool with the given arguments.
name : str
The name of the tool to call.
The arguments to pass to the tool.
ctx : RunContext[AgentDepsT]
The run context.
The tool definition returned by get_tools that was called.
def apply(visitor: Callable[[AbstractToolset[AgentDepsT]], None]) -> None
Run a visitor function on all “leaf” toolsets (i.e. those that implement their own tool listing and calling).
def visit_and_replace(
visitor: Callable[[AbstractToolset[AgentDepsT]], AbstractToolset[AgentDepsT]],
) -> AbstractToolset[AgentDepsT]
Run a visitor function on all “leaf” toolsets (i.e. those that implement their own tool listing and calling) and replace them in the hierarchy with the result of the function.
AbstractToolset[AgentDepsT]
def filtered(
filter_func: Callable[[RunContext[AgentDepsT], ToolDefinition], bool],
) -> FilteredToolset[AgentDepsT]
Returns a new toolset that filters this toolset’s tools using a filter function that takes the agent context and the tool definition.
See toolset docs for more information.
FilteredToolset[AgentDepsT]
def prefixed(prefix: str) -> PrefixedToolset[AgentDepsT]
Returns a new toolset that prefixes the names of this toolset’s tools.
See toolset docs for more information.
PrefixedToolset[AgentDepsT]
def prepared(prepare_func: ToolsPrepareFunc[AgentDepsT]) -> PreparedToolset[AgentDepsT]
Returns a new toolset that prepares this toolset’s tools using a prepare function that takes the agent context and the original tool definitions.
See toolset docs for more information.
PreparedToolset[AgentDepsT]
def renamed(name_map: dict[str, str]) -> RenamedToolset[AgentDepsT]
Returns a new toolset that renames this toolset’s tools using a dictionary mapping new names to original names.
See toolset docs for more information.
RenamedToolset[AgentDepsT]
def approval_required(
approval_required_func: Callable[[RunContext[AgentDepsT], ToolDefinition, dict[str, Any]], bool] = lambda ctx, tool_def, tool_args: True,
) -> ApprovalRequiredToolset[AgentDepsT]
Returns a new toolset that requires (some) calls to tools it contains to be approved.
See toolset docs for more information.
ApprovalRequiredToolset[AgentDepsT]
def defer_loading(
tool_names: Sequence[str] | None = None,
) -> DeferredLoadingToolset[AgentDepsT]
Returns a new toolset that marks tools for deferred loading, hiding them until discovered via tool search.
See toolset docs for more information.
DeferredLoadingToolset[AgentDepsT]
Optional sequence of tool names to mark for deferred loading.
If None, all tools are marked for deferred loading.
Bases: AbstractToolset[AgentDepsT]
A toolset that combines multiple toolsets.
See toolset docs for more information.
Bases: AbstractToolset[AgentDepsT]
A toolset that holds tools whose results will be produced outside of the Pydantic AI agent run in which they were called.
See toolset docs for more information.
Bases: WrapperToolset[AgentDepsT]
A toolset that requires (some) calls to tools it contains to be approved.
See toolset docs for more information.
Bases: WrapperToolset[AgentDepsT]
A toolset that filters the tools it contains using a filter function that takes the agent context and the tool definition.
See toolset docs for more information.
Bases: AbstractToolset[AgentDepsT]
A toolset that lets Python functions be used as tools.
See toolset docs for more information.
def __init__(
tools: Sequence[Tool[AgentDepsT] | ToolFuncEither[AgentDepsT, ...]] = [],
max_retries: int = 1,
timeout: float | 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,
defer_loading: bool = False,
id: str | None = None,
instructions: str | SystemPromptFunc[AgentDepsT] | Sequence[str | SystemPromptFunc[AgentDepsT]] | None = None,
)
Build a new function toolset.
The tools to add to the toolset.
max_retries : int Default: 1
The maximum number of retries for each tool during a run. Applies to all tools, unless overridden when adding a tool.
Timeout in seconds for tool execution. If a tool takes longer than this, a retry prompt is returned to the model. Individual tools can override this with their own timeout. Defaults to None (no timeout).
Format of tool docstring, see DocstringFormat.
Defaults to 'auto', such that the format is inferred from the structure of the docstring.
Applies to all tools, unless overridden when adding a tool.
require_parameter_descriptions : bool Default: False
If True, raise an error if a parameter description is missing. Defaults to False. Applies to all tools, unless overridden when adding a tool.
schema_generator : type[GenerateJsonSchema] Default: GenerateToolJsonSchema
The JSON schema generator class to use for this tool. Defaults to GenerateToolJsonSchema.
Applies to all tools, unless overridden when adding a tool.
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. Applies to all tools, unless overridden when adding a tool.
requires_approval : bool Default: False
Whether this tool requires human-in-the-loop approval. Defaults to False. See the tools documentation for more info. Applies to all tools, unless overridden when adding a tool.
Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization. Applies to all tools, unless overridden when adding a tool, which will be merged with the toolset’s metadata.
defer_loading : bool Default: False
Whether to hide tools from the model until discovered via tool search. Defaults to False. See Tool Search for more info. Applies to all tools, unless overridden when adding a tool.
An optional unique ID for the toolset. A toolset needs to have an ID in order to be used in a durable execution environment like Temporal, in which case the ID will be used to identify the toolset’s activities within the workflow.
instructions : str | SystemPromptFunc[AgentDepsT] | Sequence[str | SystemPromptFunc[AgentDepsT]] | None Default: None
Instructions for this toolset that are automatically included in the model request.
Can be a string, a function (sync or async, with or without RunContext), or a sequence of these.
def tool(
func: ToolFuncContext[AgentDepsT, ToolParams],
) -> ToolFuncContext[AgentDepsT, ToolParams]
def tool(
name: str | None = None,
description: str | None = None,
retries: int | None = None,
prepare: ToolPrepareFunc[AgentDepsT] | None = None,
args_validator: ArgsValidatorFunc[AgentDepsT, ToolParams] | None = None,
docstring_format: DocstringFormat | None = None,
require_parameter_descriptions: bool | None = None,
schema_generator: type[GenerateJsonSchema] | None = None,
strict: bool | None = None,
sequential: bool | None = None,
requires_approval: bool | None = None,
metadata: dict[str, Any] | None = None,
timeout: float | None = None,
defer_loading: bool | None = None,
) -> Callable[[ToolFuncContext[AgentDepsT, ToolParams]], ToolFuncContext[AgentDepsT, ToolParams]]
Decorator to register a tool function which takes RunContext as its first argument.
Can decorate a sync or async functions.
The docstring is inspected to extract both the tool description and description of each parameter, learn more.
We can’t add overloads for every possible signature of tool, since the return type is a recursive union
so the signature of functions decorated with @toolset.tool is obscured.
Example:
from pydantic_ai import Agent, FunctionToolset, RunContext
toolset = FunctionToolset()
@toolset.tool
def foobar(ctx: RunContext[int], x: int) -> int:
return ctx.deps + x
@toolset.tool(retries=2)
async def spam(ctx: RunContext[str], y: float) -> float:
return ctx.deps + y
agent = Agent('test', toolsets=[toolset], deps_type=int)
result = agent.run_sync('foobar', deps=1)
print(result.output)
#> {"foobar":1,"spam":1.0}
func : ToolFuncContext[AgentDepsT, ToolParams] | None Default: None
The tool function to register.
The name of the tool, defaults to the function name.
The description of the tool,defaults to the function docstring.
The number of retries to allow for this tool, defaults to the agent’s default retries, which defaults to 1.
prepare : ToolPrepareFunc[AgentDepsT] | 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[AgentDepsT, 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.
docstring_format : DocstringFormat | None Default: None
The format of the docstring, see DocstringFormat.
If None, the default value is determined by the toolset.
If True, raise an error if a parameter description is missing.
If None, the default value is determined by the toolset.
The JSON schema generator class to use for this tool.
If None, the default value is determined by the toolset.
Whether to enforce JSON schema compliance (only affects OpenAI).
See ToolDefinition for more info.
If None, the default value is determined by the toolset.
Whether the function requires a sequential/serial execution environment. Defaults to False.
If None, the default value is determined by the toolset.
Whether this tool requires human-in-the-loop approval. Defaults to False.
See the tools documentation for more info.
If None, the default value is determined by the toolset.
Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
If None, the default value is determined by the toolset. If provided, it will be merged with the toolset’s metadata.
Timeout in seconds for tool execution. If the tool takes longer, a retry prompt is returned to the model. Defaults to None (no timeout).
Whether to hide this tool until it’s discovered via tool search.
See Tool Search for more info.
If None, the default value is determined by the toolset.
def tool_plain(func: ToolFuncPlain[ToolParams]) -> ToolFuncPlain[ToolParams]
def tool_plain(
name: str | None = None,
description: str | None = None,
retries: int | None = None,
prepare: ToolPrepareFunc[AgentDepsT] | None = None,
args_validator: ArgsValidatorFunc[AgentDepsT, ToolParams] | None = None,
docstring_format: DocstringFormat | None = None,
require_parameter_descriptions: bool | None = None,
schema_generator: type[GenerateJsonSchema] | None = None,
strict: bool | None = None,
sequential: bool | None = None,
requires_approval: bool | None = None,
metadata: dict[str, Any] | None = None,
timeout: float | None = None,
defer_loading: bool | None = None,
) -> Callable[[ToolFuncPlain[ToolParams]], ToolFuncPlain[ToolParams]]
Decorator to register a tool function which DOES NOT take RunContext as an argument.
Can decorate a sync or async functions.
The docstring is inspected to extract both the tool description and description of each parameter, learn more.
We can’t add overloads for every possible signature of tool, since the return type is a recursive union
so the signature of functions decorated with @toolset.tool_plain is obscured.
Example:
from pydantic_ai import Agent, FunctionToolset
toolset = FunctionToolset()
@toolset.tool_plain
def foobar(x: int) -> int:
return x + 1
@toolset.tool_plain(retries=2)
async def spam(y: float) -> float:
return y * 2.0
agent = Agent('test', toolsets=[toolset])
result = agent.run_sync('foobar')
print(result.output)
#> {"foobar":1,"spam":0.0}
func : ToolFuncPlain[ToolParams] | None Default: None
The tool function to register.
The name of the tool, defaults to the function name.
The description of the tool, defaults to the function docstring.
The number of retries to allow for this tool, defaults to the toolset’s default retries, which defaults to 1.
prepare : ToolPrepareFunc[AgentDepsT] | 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[AgentDepsT, 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 — even though the
tool function itself does not take RunContext when using tool_plain.
Should raise ModelRetry on validation failure,
return None on success.
See ArgsValidatorFunc.
docstring_format : DocstringFormat | None Default: None
The format of the docstring, see DocstringFormat.
If None, the default value is determined by the toolset.
If True, raise an error if a parameter description is missing.
If None, the default value is determined by the toolset.
The JSON schema generator class to use for this tool.
If None, the default value is determined by the toolset.
Whether to enforce JSON schema compliance (only affects OpenAI).
See ToolDefinition for more info.
If None, the default value is determined by the toolset.
Whether the function requires a sequential/serial execution environment. Defaults to False.
If None, the default value is determined by the toolset.
Whether this tool requires human-in-the-loop approval. Defaults to False.
See the tools documentation for more info.
If None, the default value is determined by the toolset.
Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
If None, the default value is determined by the toolset. If provided, it will be merged with the toolset’s metadata.
Timeout in seconds for tool execution. If the tool takes longer, a retry prompt is returned to the model. Defaults to None (no timeout).
Whether to hide this tool until it’s discovered via tool search.
See Tool Search for more info.
If None, the default value is determined by the toolset.
def instructions(func: SystemPromptFunc[AgentDepsT]) -> SystemPromptFunc[AgentDepsT]
Decorator to register an instructions function for this toolset.
The function can be sync or async, and can optionally take a
RunContext as its first argument.
Example:
from pydantic_ai import FunctionToolset, RunContext
toolset = FunctionToolset[int]()
@toolset.instructions
def my_instructions(ctx: RunContext[int]) -> str:
return 'Always use the search tool when looking for information.'
@toolset.tool
def search(ctx: RunContext[int], query: str) -> str:
return f'Results for: {query}'
SystemPromptFunc[AgentDepsT]
The instructions function to register.
def add_function(
func: ToolFuncEither[AgentDepsT, ToolParams],
takes_ctx: bool | None = None,
name: str | None = None,
description: str | None = None,
retries: int | None = None,
prepare: ToolPrepareFunc[AgentDepsT] | None = None,
args_validator: ArgsValidatorFunc[AgentDepsT, ToolParams] | None = None,
docstring_format: DocstringFormat | None = None,
require_parameter_descriptions: bool | None = None,
schema_generator: type[GenerateJsonSchema] | None = None,
strict: bool | None = None,
sequential: bool | None = None,
requires_approval: bool | None = None,
defer_loading: bool | None = None,
metadata: dict[str, Any] | None = None,
timeout: float | None = None,
) -> Tool[AgentDepsT]
Add a function as a tool to the toolset.
Can take a sync or async function.
The docstring is inspected to extract both the tool description and description of each parameter, learn more.
Tool[AgentDepsT]
The tool function to register.
Whether the function takes a RunContext as its first argument. If None, this is inferred from the function signature.
The name of the tool, defaults to the function name.
The description of the tool, defaults to the function docstring.
The number of retries to allow for this tool, defaults to the agent’s default retries, which defaults to 1.
prepare : ToolPrepareFunc[AgentDepsT] | 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[AgentDepsT, 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.
docstring_format : DocstringFormat | None Default: None
The format of the docstring, see DocstringFormat.
If None, the default value is determined by the toolset.
If True, raise an error if a parameter description is missing.
If None, the default value is determined by the toolset.
The JSON schema generator class to use for this tool.
If None, the default value is determined by the toolset.
Whether to enforce JSON schema compliance (only affects OpenAI).
See ToolDefinition for more info.
If None, the default value is determined by the toolset.
Whether the function requires a sequential/serial execution environment. Defaults to False.
If None, the default value is determined by the toolset.
Whether this tool requires human-in-the-loop approval. Defaults to False.
See the tools documentation for more info.
If None, the default value is determined by the toolset.
Whether to hide this tool until it’s discovered via tool search.
See Tool Search for more info.
If None, the default value is determined by the toolset.
Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
If None, the default value is determined by the toolset. If provided, it will be merged with the toolset’s metadata.
Timeout in seconds for tool execution. If the tool takes longer, a retry prompt is returned to the model. Defaults to None (no timeout).
def add_tool(tool: Tool[AgentDepsT]) -> None
Add a tool to the toolset.
tool : Tool[AgentDepsT]
The tool to add.
Bases: PreparedToolset[AgentDepsT]
A toolset that marks tools for deferred loading, hiding them from the model until discovered via tool search.
See toolset docs for more information.
Optional set of tool names to mark for deferred loading. If None, all tools are marked for deferred loading.
Type: frozenset[str] | None Default: tool_names
Bases: WrapperToolset[AgentDepsT]
A toolset that prefixes the names of the tools it contains.
See toolset docs for more information.
Bases: WrapperToolset[AgentDepsT]
A toolset that renames the tools it contains using a dictionary mapping new names to original names.
See toolset docs for more information.
Bases: WrapperToolset[AgentDepsT]
A toolset that prepares the tools it contains using a prepare function that takes the agent context and the original tool definitions.
See toolset docs for more information.
Bases: AbstractToolset[AgentDepsT]
A toolset that wraps another toolset and delegates to it.
See toolset docs for more information.
@async
def get_instructions(
ctx: RunContext[AgentDepsT],
) -> str | InstructionPart | Sequence[str | InstructionPart] | None
Delegate instructions to the wrapped toolset.
This explicit delegation ensures type safety and proper propagation of the instructions from wrapped toolsets to the agent’s system prompt.
str | InstructionPart | Sequence[str | InstructionPart] | None
A sync/async function which takes a run context and returns a toolset.
Type: TypeAlias Default: Callable[[RunContext[AgentDepsT]], AbstractToolset[AgentDepsT] | None | Awaitable[AbstractToolset[AgentDepsT] | None]]
Bases: AbstractToolset[AgentDepsT]
A FastMCP Toolset that uses the FastMCP Client to call tools from a local or remote MCP Server.
The Toolset can accept a FastMCP Client, a FastMCP Transport, or any other object which a FastMCP Transport can be created from.
See https://gofastmcp.com/clients/transports for a full list of transports available.
The FastMCP client to use.
Type: Client[Any]
The maximum number of retries to attempt if a tool call fails.
Type: int Default: max_retries
The behavior to take when a tool error occurs.
Type: Literal[‘model_retry’, ‘error’] Default: tool_error_behavior
Whether to include the server’s instructions in the agent’s instructions.
Defaults to False for backward compatibility.
Type: bool Default: include_instructions
Access the instructions sent by the FastMCP server during initialization.
@async
def get_instructions(ctx: RunContext[AgentDepsT]) -> messages.InstructionPart | None
Return the FastMCP server’s instructions for how to use its tools.
If include_instructions is True, returns
the instructions sent by the FastMCP server during
initialization. Otherwise, returns None.
Instructions from external servers are marked as dynamic since they may change between connections.
messages.InstructionPart | None — An InstructionPart with the server’s instructions if include_instructions is enabled, otherwise None.
ctx : RunContext[AgentDepsT]
The run context for this agent run.