Let FunctionToolset take default values for strict, sequential, requires_approval, metadata (#2909)

Author: DouweM

pydantic_ai_slim/pydantic_ai/agent/__init__.py

@@ -1005,6 +1005,7 @@ def tool(
         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,
     ) -> Callable[[ToolFuncContext[AgentDepsT, ToolParams]], ToolFuncContext[AgentDepsT, ToolParams]]: ...
@@ -1021,6 +1022,7 @@ def tool(
         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,
     ) -> Any:
@@ -1067,6 +1069,7 @@ async def spam(ctx: RunContext[str], y: float) -> float:
             schema_generator: The JSON schema generator class to use for this tool. Defaults to `GenerateToolJsonSchema`.
             strict: Whether to enforce JSON schema compliance (only affects OpenAI).
                 See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info.
+            sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
             requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
                 See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
             metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
@@ -1078,17 +1081,17 @@ def tool_decorator(
             # noinspection PyTypeChecker
             self._function_toolset.add_function(
                 func_,
-                True,
-                name,
-                retries,
-                prepare,
-                docstring_format,
-                require_parameter_descriptions,
-                schema_generator,
-                strict,
-                False,
-                requires_approval,
-                metadata,
+                takes_ctx=True,
+                name=name,
+                retries=retries,
+                prepare=prepare,
+                docstring_format=docstring_format,
+                require_parameter_descriptions=require_parameter_descriptions,
+                schema_generator=schema_generator,
+                strict=strict,
+                sequential=sequential,
+                requires_approval=requires_approval,
+                metadata=metadata,
             )
             return func_
 
@@ -1109,6 +1112,7 @@ def tool_plain(
         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,
     ) -> Callable[[ToolFuncPlain[ToolParams]], ToolFuncPlain[ToolParams]]: ...
@@ -1182,17 +1186,17 @@ def tool_decorator(func_: ToolFuncPlain[ToolParams]) -> ToolFuncPlain[ToolParams
             # noinspection PyTypeChecker
             self._function_toolset.add_function(
                 func_,
-                False,
-                name,
-                retries,
-                prepare,
-                docstring_format,
-                require_parameter_descriptions,
-                schema_generator,
-                strict,
-                sequential,
-                requires_approval,
-                metadata,
+                takes_ctx=False,
+                name=name,
+                retries=retries,
+                prepare=prepare,
+                docstring_format=docstring_format,
+                require_parameter_descriptions=require_parameter_descriptions,
+                schema_generator=schema_generator,
+                strict=strict,
+                sequential=sequential,
+                requires_approval=requires_approval,
+                metadata=metadata,
             )
             return func_
 

pydantic_ai_slim/pydantic_ai/toolsets/function.py

@@ -45,31 +45,49 @@ def __init__(
         tools: Sequence[Tool[AgentDepsT] | ToolFuncEither[AgentDepsT, ...]] = [],
         *,
         max_retries: int = 1,
-        id: str | 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,
+        id: str | None = None,
     ):
         """Build a new function toolset.
 
         Args:
             tools: The tools to add to the toolset.
             max_retries: The maximum number of retries for each tool during a run.
-            id: 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.
+                Applies to all tools, unless overridden when adding a tool.
             docstring_format: Format of tool docstring, see [`DocstringFormat`][pydantic_ai.tools.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: 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: The JSON schema generator class to use for this tool. Defaults to `GenerateToolJsonSchema`.
                 Applies to all tools, unless overridden when adding a tool.
+            strict: Whether to enforce JSON schema compliance (only affects OpenAI).
+                See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info.
+            sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
+                Applies to all tools, unless overridden when adding a tool.
+            requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
+                See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
+                Applies to all tools, unless overridden when adding a tool.
+            metadata: 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.
+            id: 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.
         """
         self.max_retries = max_retries
         self._id = id
         self.docstring_format = docstring_format
         self.require_parameter_descriptions = require_parameter_descriptions
         self.schema_generator = schema_generator
+        self.strict = strict
+        self.sequential = sequential
+        self.requires_approval = requires_approval
+        self.metadata = metadata
 
         self.tools = {}
         for tool in tools:
@@ -97,8 +115,8 @@ def tool(
         require_parameter_descriptions: bool | None = None,
         schema_generator: type[GenerateJsonSchema] | None = None,
         strict: bool | None = None,
-        sequential: bool = False,
-        requires_approval: bool = False,
+        sequential: bool | None = None,
+        requires_approval: bool | None = None,
         metadata: dict[str, Any] | None = None,
     ) -> Callable[[ToolFuncEither[AgentDepsT, ToolParams]], ToolFuncEither[AgentDepsT, ToolParams]]: ...
 
@@ -114,8 +132,8 @@ def tool(
         require_parameter_descriptions: bool | None = None,
         schema_generator: type[GenerateJsonSchema] | None = None,
         strict: bool | None = None,
-        sequential: bool = False,
-        requires_approval: bool = False,
+        sequential: bool | None = None,
+        requires_approval: bool | None = None,
         metadata: dict[str, Any] | None = None,
     ) -> Any:
         """Decorator to register a tool function which takes [`RunContext`][pydantic_ai.tools.RunContext] as its first argument.
@@ -165,10 +183,14 @@ async def spam(ctx: RunContext[str], y: float) -> float:
                 If `None`, the default value is determined by the toolset.
             strict: Whether to enforce JSON schema compliance (only affects OpenAI).
                 See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info.
+                If `None`, the default value is determined by the toolset.
             sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
+                If `None`, the default value is determined by the toolset.
             requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
                 See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
+                If `None`, the default value is determined by the toolset.
             metadata: 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.
         """
 
         def tool_decorator(
@@ -204,8 +226,8 @@ def add_function(
         require_parameter_descriptions: bool | None = None,
         schema_generator: type[GenerateJsonSchema] | None = None,
         strict: bool | None = None,
-        sequential: bool = False,
-        requires_approval: bool = False,
+        sequential: bool | None = None,
+        requires_approval: bool | None = None,
         metadata: dict[str, Any] | None = None,
     ) -> None:
         """Add a function as a tool to the toolset.
@@ -232,17 +254,27 @@ def add_function(
                 If `None`, the default value is determined by the toolset.
             strict: Whether to enforce JSON schema compliance (only affects OpenAI).
                 See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info.
+                If `None`, the default value is determined by the toolset.
             sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
+                If `None`, the default value is determined by the toolset.
             requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
                 See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
+                If `None`, the default value is determined by the toolset.
             metadata: 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.
         """
         if docstring_format is None:
             docstring_format = self.docstring_format
         if require_parameter_descriptions is None:
             require_parameter_descriptions = self.require_parameter_descriptions
         if schema_generator is None:
             schema_generator = self.schema_generator
+        if strict is None:
+            strict = self.strict
+        if sequential is None:
+            sequential = self.sequential
+        if requires_approval is None:
+            requires_approval = self.requires_approval
 
         tool = Tool[AgentDepsT](
             func,
@@ -270,6 +302,8 @@ def add_tool(self, tool: Tool[AgentDepsT]) -> None:
             raise UserError(f'Tool name conflicts with existing tool: {tool.name!r}')
         if tool.max_retries is None:
             tool.max_retries = self.max_retries
+        if self.metadata is not None:
+            tool.metadata = self.metadata | (tool.metadata or {})
         self.tools[tool.name] = tool
 
     async def get_tools(self, ctx: RunContext[AgentDepsT]) -> dict[str, ToolsetTool[AgentDepsT]]:

tests/test_tools.py

@@ -1919,19 +1919,26 @@ def plain_tool(z: int) -> int:
     assert plain_tool_def.metadata == {'type': 'plain'}
 
     # Test with FunctionToolset.tool decorator
-    toolset = FunctionToolset()
+    toolset = FunctionToolset(metadata={'foo': 'bar'})
+
+    @toolset.tool
+    def toolset_plain_tool(a: str) -> str:
+        return a.upper()  # pragma: no cover
+
+    toolset_plain_tool_def = toolset.tools['toolset_plain_tool']
+    assert toolset_plain_tool_def.metadata == {'foo': 'bar'}
 
     @toolset.tool(metadata={'toolset': 'function'})
     def toolset_tool(ctx: RunContext[None], a: str) -> str:
         return a.upper()  # pragma: no cover
 
     toolset_tool_def = toolset.tools['toolset_tool']
-    assert toolset_tool_def.metadata == {'toolset': 'function'}
+    assert toolset_tool_def.metadata == {'foo': 'bar', 'toolset': 'function'}
 
     # Test with FunctionToolset.add_function
     def standalone_func(ctx: RunContext[None], b: float) -> float:
         return b / 2  # pragma: no cover
 
     toolset.add_function(standalone_func, metadata={'method': 'add_function'})
     standalone_tool_def = toolset.tools['standalone_func']
-    assert standalone_tool_def.metadata == {'method': 'add_function'}
+    assert standalone_tool_def.metadata == {'foo': 'bar', 'method': 'add_function'}