From 51b32ed1ac919a6a0864c8c6f3cefd3668d6e72c Mon Sep 17 00:00:00 2001 From: Eduard van Valkenburg Date: Wed, 5 Nov 2025 09:33:19 +0100 Subject: [PATCH] Python: Updates to Tools (#1835) * updated tool samples * mypy and readme fixes * updated call logic * added function invocation config * added include detailed error * added tests * updated FRC exception handling * updated tests * fix oai test * fix name in sample * imporoved tests coverage and removed some dead code paths --- .../packages/core/agent_framework/_clients.py | 6 +- .../packages/core/agent_framework/_tools.py | 448 +++-- .../openai/_assistants_client.py | 2 - .../agent_framework/openai/_chat_client.py | 5 - .../openai/_responses_client.py | 2 - .../core/test_function_invocation_logic.py | 1449 ++++++++++++++++- python/packages/core/tests/core/test_tools.py | 20 + .../tests/openai/test_openai_chat_client.py | 7 +- python/samples/README.md | 11 +- .../samples/getting_started/tools/README.md | 119 ++ .../tools/ai_function_declaration_only.py | 75 + ...on_from_dict_with_dependency_injection.py} | 0 ...y => ai_function_recover_from_failures.py} | 0 ...proval.py => ai_function_with_approval.py} | 0 ... ai_function_with_approval_and_threads.py} | 0 .../tools/ai_function_with_max_exceptions.py | 188 +++ .../tools/ai_function_with_max_invocations.py | 89 + .../tools/ai_functions_in_class.py | 100 ++ .../function_invocation_configuration.py | 58 + 19 files changed, 2460 insertions(+), 119 deletions(-) create mode 100644 python/samples/getting_started/tools/ai_function_declaration_only.py rename python/samples/getting_started/tools/{tool_with_injected_func.py => ai_function_from_dict_with_dependency_injection.py} (100%) rename python/samples/getting_started/tools/{failing_tools.py => ai_function_recover_from_failures.py} (100%) rename python/samples/getting_started/tools/{ai_tool_with_approval.py => ai_function_with_approval.py} (100%) rename python/samples/getting_started/tools/{ai_tool_with_approval_and_threads.py => ai_function_with_approval_and_threads.py} (100%) create mode 100644 python/samples/getting_started/tools/ai_function_with_max_exceptions.py create mode 100644 python/samples/getting_started/tools/ai_function_with_max_invocations.py create mode 100644 python/samples/getting_started/tools/ai_functions_in_class.py create mode 100644 python/samples/getting_started/tools/function_invocation_configuration.py diff --git a/python/packages/core/agent_framework/_clients.py b/python/packages/core/agent_framework/_clients.py index e4b2d53cc6..3cac845ed3 100644 --- a/python/packages/core/agent_framework/_clients.py +++ b/python/packages/core/agent_framework/_clients.py @@ -19,7 +19,7 @@ from ._middleware import ( ) from ._serialization import SerializationMixin from ._threads import ChatMessageStoreProtocol -from ._tools import ToolProtocol +from ._tools import FUNCTION_INVOKING_CHAT_CLIENT_MARKER, FunctionInvocationConfiguration, ToolProtocol from ._types import ChatMessage, ChatOptions, ChatResponse, ChatResponseUpdate, ToolMode, prepare_messages if TYPE_CHECKING: @@ -357,6 +357,10 @@ class BaseChatClient(SerializationMixin, ABC): self.middleware = middleware + self.function_invocation_configuration = ( + FunctionInvocationConfiguration() if hasattr(self.__class__, FUNCTION_INVOKING_CHAT_CLIENT_MARKER) else None + ) + def to_dict(self, *, exclude: set[str] | None = None, exclude_none: bool = True) -> dict[str, Any]: """Convert the instance to a dictionary. diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 22b9921e49..83df62e29d 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -71,6 +71,7 @@ logger = get_logger() __all__ = [ "FUNCTION_INVOKING_CHAT_CLIENT_MARKER", "AIFunction", + "FunctionInvocationConfiguration", "HostedCodeInterpreterTool", "HostedFileSearchTool", "HostedMCPSpecificApproval", @@ -84,7 +85,8 @@ __all__ = [ logger = get_logger() FUNCTION_INVOKING_CHAT_CLIENT_MARKER: Final[str] = "__function_invoking_chat_client__" -DEFAULT_MAX_ITERATIONS: Final[int] = 10 +DEFAULT_MAX_ITERATIONS: Final[int] = 40 +DEFAULT_MAX_CONSECUTIVE_ERRORS_PER_REQUEST: Final[int] = 3 TChatClient = TypeVar("TChatClient", bound="ChatClientProtocol") # region Helpers @@ -156,34 +158,19 @@ def _parse_inputs( # region Tools @runtime_checkable class ToolProtocol(Protocol): - """Represents a generic tool that can be specified to an AI service. + """Represents a generic tool. This protocol defines the interface that all tools must implement to be compatible - with the agent framework. + with the agent framework. It is implemented by various tool classes such as HostedMCPTool, + HostedWebSearchTool, and AIFunction's. A AIFunction is usually created by the `ai_function` decorator. + + Since each connector needs to parse tools differently, users can pass a dict to + specify a service-specific tool when no abstraction is available. Attributes: name: The name of the tool. description: A description of the tool, suitable for use in describing the purpose to a model. additional_properties: Additional properties associated with the tool. - - Examples: - .. code-block:: python - - from agent_framework import ToolProtocol - - - class CustomTool: - def __init__(self, name: str, description: str) -> None: - self.name = name - self.description = description - self.additional_properties = None - - def __str__(self) -> str: - return f"CustomTool(name={self.name})" - - - # Tool now implements ToolProtocol - tool: ToolProtocol = CustomTool("my_tool", "Does something useful") """ name: str @@ -201,22 +188,11 @@ class ToolProtocol(Protocol): class BaseTool(SerializationMixin): """Base class for AI tools, providing common attributes and methods. - This class provides the foundation for creating custom tools with serialization support. + Used as the base class for the various tools in the agent framework, such as HostedMCPTool, + HostedWebSearchTool, and AIFunction. - Examples: - .. code-block:: python - - from agent_framework import BaseTool - - - class MyCustomTool(BaseTool): - def __init__(self, name: str, custom_param: str) -> None: - super().__init__(name=name, description="My custom tool") - self.custom_param = custom_param - - - tool = MyCustomTool(name="custom", custom_param="value") - print(tool) # MyCustomTool(name=custom, description=My custom tool) + Since each connector needs to parse tools differently, this class is not exposed directly to end users. + In most cases, users can pass a dict to specify a service-specific tool when no abstraction is available. """ DEFAULT_EXCLUDE: ClassVar[set[str]] = {"additional_properties"} @@ -551,6 +527,10 @@ def _default_histogram() -> Histogram: TClass = TypeVar("TClass", bound="SerializationMixin") +class EmptyInputModel(BaseModel): + """An empty input model for functions with no parameters.""" + + class AIFunction(BaseTool, Generic[ArgsT, ReturnT]): """A tool that wraps a Python function to make it callable by AI models. @@ -602,8 +582,10 @@ class AIFunction(BaseTool, Generic[ArgsT, ReturnT]): name: str, description: str = "", approval_mode: Literal["always_require", "never_require"] | None = None, + max_invocations: int | None = None, + max_invocation_exceptions: int | None = None, additional_properties: dict[str, Any] | None = None, - func: Callable[..., Awaitable[ReturnT] | ReturnT], + func: Callable[..., Awaitable[ReturnT] | ReturnT] | None = None, input_model: type[ArgsT] | Mapping[str, Any] | None = None, **kwargs: Any, ) -> None: @@ -614,6 +596,10 @@ class AIFunction(BaseTool, Generic[ArgsT, ReturnT]): description: A description of the function. approval_mode: Whether or not approval is required to run this tool. Default is that approval is not needed. + max_invocations: The maximum number of times this function can be invoked. + If None, there is no limit. Should be at least 1. + max_invocation_exceptions: The maximum number of exceptions allowed during invocations. + If None, there is no limit. Should be at least 1. additional_properties: Additional properties to set on the function. func: The function to wrap. input_model: The Pydantic model that defines the input parameters for the function. @@ -630,21 +616,56 @@ class AIFunction(BaseTool, Generic[ArgsT, ReturnT]): self.func = func self.input_model = self._resolve_input_model(input_model) self.approval_mode = approval_mode or "never_require" + if max_invocations is not None and max_invocations < 1: + raise ValueError("max_invocations must be at least 1 or None.") + if max_invocation_exceptions is not None and max_invocation_exceptions < 1: + raise ValueError("max_invocation_exceptions must be at least 1 or None.") + self.max_invocations = max_invocations + self.invocation_count = 0 + self.max_invocation_exceptions = max_invocation_exceptions + self.invocation_exception_count = 0 self._invocation_duration_histogram = _default_histogram() self.type: Literal["ai_function"] = "ai_function" + @property + def declaration_only(self) -> bool: + """Indicate whether the function is declaration only (i.e., has no implementation).""" + return self.func is None + def _resolve_input_model(self, input_model: type[ArgsT] | Mapping[str, Any] | None) -> type[ArgsT]: - if input_model: - if inspect.isclass(input_model) and issubclass(input_model, BaseModel): - return input_model - if isinstance(input_model, Mapping): - return cast(type[ArgsT], _create_model_from_json_schema(self.name, input_model)) - raise TypeError("input_model must be a Pydantic BaseModel subclass or a JSON schema dict.") - return cast(type[ArgsT], _create_input_model_from_func(self.func, self.name)) + """Resolve the input model for the function.""" + if input_model is None: + if self.func is None: + return cast(type[ArgsT], EmptyInputModel) + return cast(type[ArgsT], _create_input_model_from_func(func=self.func, name=self.name)) + if inspect.isclass(input_model) and issubclass(input_model, BaseModel): + return input_model + if isinstance(input_model, Mapping): + return cast(type[ArgsT], _create_model_from_json_schema(self.name, input_model)) + raise TypeError("input_model must be a Pydantic BaseModel subclass or a JSON schema dict.") def __call__(self, *args: Any, **kwargs: Any) -> ReturnT | Awaitable[ReturnT]: """Call the wrapped function with the provided arguments.""" - return self.func(*args, **kwargs) + if self.func is None: + raise ToolException(f"Function '{self.name}' is declaration only and cannot be invoked.") + if self.max_invocations is not None and self.invocation_count >= self.max_invocations: + raise ToolException( + f"Function '{self.name}' has reached its maximum invocation limit, you can no longer use this tool." + ) + if ( + self.max_invocation_exceptions is not None + and self.invocation_exception_count >= self.max_invocation_exceptions + ): + raise ToolException( + f"Function '{self.name}' has reached its maximum exception limit, " + f"you tried to use this tool too many times and it kept failing." + ) + self.invocation_count += 1 + try: + return self.func(*args, **kwargs) + except Exception: + self.invocation_exception_count += 1 + raise async def invoke( self, @@ -664,6 +685,8 @@ class AIFunction(BaseTool, Generic[ArgsT, ReturnT]): Raises: TypeError: If arguments is not an instance of the expected input model. """ + if self.declaration_only: + raise ToolException(f"Function '{self.name}' is declaration only and cannot be invoked.") global OBSERVABILITY_SETTINGS from .observability import OBSERVABILITY_SETTINGS @@ -833,7 +856,7 @@ def _parse_annotation(annotation: Any) -> Any: return annotation -def _create_input_model_from_func(func: Callable[..., Any], tool_name: str) -> type[BaseModel]: +def _create_input_model_from_func(func: Callable[..., Any], name: str) -> type[BaseModel]: """Create a Pydantic model from a function's signature.""" sig = inspect.signature(func) fields = { @@ -844,7 +867,7 @@ def _create_input_model_from_func(func: Callable[..., Any], tool_name: str) -> t for pname, param in sig.parameters.items() if pname not in {"self", "cls"} } - return create_model(f"{tool_name}_input", **fields) # type: ignore[call-overload, no-any-return] + return create_model(f"{name}_input", **fields) # type: ignore[call-overload, no-any-return] # Map JSON Schema types to Pydantic types @@ -907,6 +930,8 @@ def ai_function( name: str | None = None, description: str | None = None, approval_mode: Literal["always_require", "never_require"] | None = None, + max_invocations: int | None = None, + max_invocation_exceptions: int | None = None, additional_properties: dict[str, Any] | None = None, ) -> AIFunction[Any, ReturnT]: ... @@ -918,6 +943,8 @@ def ai_function( name: str | None = None, description: str | None = None, approval_mode: Literal["always_require", "never_require"] | None = None, + max_invocations: int | None = None, + max_invocation_exceptions: int | None = None, additional_properties: dict[str, Any] | None = None, ) -> Callable[[Callable[..., ReturnT | Awaitable[ReturnT]]], AIFunction[Any, ReturnT]]: ... @@ -928,6 +955,8 @@ def ai_function( name: str | None = None, description: str | None = None, approval_mode: Literal["always_require", "never_require"] | None = None, + max_invocations: int | None = None, + max_invocation_exceptions: int | None = None, additional_properties: dict[str, Any] | None = None, ) -> AIFunction[Any, ReturnT] | Callable[[Callable[..., ReturnT | Awaitable[ReturnT]]], AIFunction[Any, ReturnT]]: """Decorate a function to turn it into a AIFunction that can be passed to models and executed automatically. @@ -940,6 +969,22 @@ def ai_function( with a string description as the second argument. You can also use Pydantic's ``Field`` class for more advanced configuration. + Args: + func: The function to decorate. + + Keyword Args: + name: The name of the function. If not provided, the function's ``__name__`` + attribute will be used. + description: A description of the function. If not provided, the function's + docstring will be used. + approval_mode: Whether or not approval is required to run this tool. + Default is that approval is not needed. + max_invocations: The maximum number of times this function can be invoked. + If None, there is no limit, should be at least 1. + max_invocation_exceptions: The maximum number of exceptions allowed during invocations. + If None, there is no limit, should be at least 1. + additional_properties: Additional properties to set on the function. + Note: When approval_mode is set to "always_require", the function will not be executed until explicit approval is given, this only applies to the auto-invocation flow. @@ -997,6 +1042,8 @@ def ai_function( name=tool_name, description=tool_desc, approval_mode=approval_mode, + max_invocations=max_invocations, + max_invocation_exceptions=max_invocation_exceptions, additional_properties=additional_properties or {}, func=f, ) @@ -1009,10 +1056,123 @@ def ai_function( # region Function Invoking Chat Client +class FunctionInvocationConfiguration(SerializationMixin): + """Configuration for function invocation in chat clients. + + This class is created automatically on every chat client that supports function invocation. + This means that for most cases you can just alter the attributes on the instance, rather then creating a new one. + + Example: + .. code-block:: python + from agent_framework.openai import OpenAIChatClient + + # Create an OpenAI chat client + client = OpenAIChatClient(api_key="your_api_key") + + # Disable function invocation + client.function_invocation_config.enabled = False + + # Set maximum iterations to 10 + client.function_invocation_config.max_iterations = 10 + + # Enable termination on unknown function calls + client.function_invocation_config.terminate_on_unknown_calls = True + + # Add additional tools for function execution + client.function_invocation_config.additional_tools = [my_custom_tool] + + # Enable detailed error information in function results + client.function_invocation_config.include_detailed_errors = True + + # You can also create a new configuration instance if needed + new_config = FunctionInvocationConfiguration( + enabled=True, + max_iterations=20, + terminate_on_unknown_calls=False, + additional_tools=[another_tool], + include_detailed_errors=False, + ) + + # and then assign it to the client + client.function_invocation_config = new_config + + + Attributes: + enabled: Whether function invocation is enabled. + When this is set to False, the client will not attempt to invoke any functions, + because the tool mode will be set to None. + max_iterations: Maximum number of function invocation iterations. + Each request to this client might end up making multiple requests to the model. Each time the model responds + with a function call request, this client might perform that invocation and send the results back to the + model in a new request. This property limits the number of times such a roundtrip is performed. The value + must be at least one, as it includes the initial request. + If you want to fully disable function invocation, use the ``enabled`` property. + The default is 40. + max_consecutive_errors_per_request: Maximum consecutive errors allowed per request. + The maximum number of consecutive function call errors allowed before stopping + further function calls for the request. + The default is 3. + terminate_on_unknown_calls: Whether to terminate on unknown function calls. + When False, call requests to any tools that aren't available to the client + will result in a response message automatically being created and returned to the inner client stating that + the tool couldn't be found. This behavior can help in cases where a model hallucinates a function, but it's + problematic if the model has been made aware of the existence of tools outside of the normal mechanisms, and + requests one of those. ``additional_tools`` can be used to help with that. But if instead the consumer wants + to know about all function call requests that the client can't handle, this can be set to True. Upon + receiving a request to call a function that the client doesn't know about, it will terminate the function + calling loop and return the response, leaving the handling of the function call requests to the consumer of + the client. + additional_tools: Additional tools to include for function execution. + These will not impact the requests sent by the client, which will pass through the + ``tools`` unmodified. However, if the inner client requests the invocation of a tool + that was not in ``ChatOptions.tools``, this ``additional_tools`` collection will also be consulted to look + for a corresponding tool. This is useful when the service might have been pre-configured to be aware of + certain tools that aren't also sent on each individual request. These tools are treated the same as + ``declaration_only`` tools and will be returned to the user. + include_detailed_errors: Whether to include detailed error information in function results. + When set to True, detailed error information such as exception type and message + will be included in the function result content when a function invocation fails. + When False, only a generic error message will be included. + + + """ + + def __init__( + self, + enabled: bool = True, + max_iterations: int = DEFAULT_MAX_ITERATIONS, + max_consecutive_errors_per_request: int = DEFAULT_MAX_CONSECUTIVE_ERRORS_PER_REQUEST, + terminate_on_unknown_calls: bool = False, + additional_tools: Sequence[ToolProtocol] | None = None, + include_detailed_errors: bool = False, + ) -> None: + """Initialize FunctionInvocationConfiguration. + + Args: + enabled: Whether function invocation is enabled. + max_iterations: Maximum number of function invocation iterations. + max_consecutive_errors_per_request: Maximum consecutive errors allowed per request. + terminate_on_unknown_calls: Whether to terminate on unknown function calls. + additional_tools: Additional tools to include for function execution. + include_detailed_errors: Whether to include detailed error information in function results. + """ + self.enabled = enabled + if max_iterations < 1: + raise ValueError("max_iterations must be at least 1.") + self.max_iterations = max_iterations + if max_consecutive_errors_per_request < 0: + raise ValueError("max_consecutive_errors_per_request must be 0 or more.") + self.max_consecutive_errors_per_request = max_consecutive_errors_per_request + self.terminate_on_unknown_calls = terminate_on_unknown_calls + self.additional_tools = additional_tools or [] + self.include_detailed_errors = include_detailed_errors + + async def _auto_invoke_function( function_call_content: "FunctionCallContent | FunctionApprovalResponseContent", custom_args: dict[str, Any] | None = None, *, + config: FunctionInvocationConfiguration, tool_map: dict[str, AIFunction[BaseModel, Any]], sequence_index: int | None = None, request_index: int | None = None, @@ -1025,6 +1185,7 @@ async def _auto_invoke_function( custom_args: Additional custom arguments to merge with parsed arguments. Keyword Args: + config: The function invocation configuration. tool_map: A mapping of tool names to AIFunction instances. sequence_index: The index of the function call in the sequence. request_index: The index of the request iteration. @@ -1037,29 +1198,33 @@ async def _auto_invoke_function( KeyError: If the requested function is not found in the tool map. """ from ._types import ( - FunctionApprovalRequestContent, - FunctionApprovalResponseContent, - FunctionCallContent, FunctionResultContent, ) + # Note: The scenarios for approval_mode="always_require", declaration_only, and + # terminate_on_unknown_calls are all handled in _try_execute_function_calls before + # this function is called. This function only handles the actual execution of approved, + # non-declaration-only functions. + tool: AIFunction[BaseModel, Any] | None = None - if isinstance(function_call_content, FunctionCallContent): + if function_call_content.type == "function_call": tool = tool_map.get(function_call_content.name) + # Tool should exist because _try_execute_function_calls validates this if tool is None: - raise KeyError(f"No tool or function named '{function_call_content.name}'") - if tool.approval_mode == "always_require": - return FunctionApprovalRequestContent(id=function_call_content.call_id, function_call=function_call_content) + exc = KeyError(f'Function "{function_call_content.name}" not found.') + return FunctionResultContent( + call_id=function_call_content.call_id, + result=f'Error: Requested function "{function_call_content.name}" not found.', + exception=exc, + ) else: - if isinstance(function_call_content, FunctionApprovalResponseContent): - if function_call_content.approved: - tool = tool_map.get(function_call_content.function_call.name) - if tool is None: - # we assume it is a hosted tool - return function_call_content - function_call_content = function_call_content.function_call - else: - raise ToolException("Unapproved tool cannot be executed.") + # Note: Unapproved tools (approved=False) are handled in _replace_approval_contents_with_results + # and never reach this function, so we only handle approved=True cases here. + tool = tool_map.get(function_call_content.function_call.name) + if tool is None: + # we assume it is a hosted tool + return function_call_content + function_call_content = function_call_content.function_call parsed_args: dict[str, Any] = dict(function_call_content.parse_arguments() or {}) @@ -1068,10 +1233,10 @@ async def _auto_invoke_function( try: args = tool.input_model.model_validate(merged_args) except ValidationError as exc: - return FunctionResultContent( - call_id=function_call_content.call_id, - exception=exc, - ) + message = "Error: Argument parsing failed." + if config.include_detailed_errors: + message = f"{message} Exception: {exc}" + return FunctionResultContent(call_id=function_call_content.call_id, result=message, exception=exc) if not middleware_pipeline or ( not hasattr(middleware_pipeline, "has_middlewares") and not middleware_pipeline.has_middlewares ): @@ -1086,10 +1251,10 @@ async def _auto_invoke_function( result=function_result, ) except Exception as exc: - return FunctionResultContent( - call_id=function_call_content.call_id, - exception=exc, - ) + message = "Error: Function failed." + if config.include_detailed_errors: + message = f"{message} Exception: {exc}" + return FunctionResultContent(call_id=function_call_content.call_id, result=message, exception=exc) # Execute through middleware pipeline if available from ._middleware import FunctionInvocationContext @@ -1117,10 +1282,10 @@ async def _auto_invoke_function( result=function_result, ) except Exception as exc: - return FunctionResultContent( - call_id=function_call_content.call_id, - exception=exc, - ) + message = "Error: Function failed." + if config.include_detailed_errors: + message = f"{message} Exception: {exc}" + return FunctionResultContent(call_id=function_call_content.call_id, result=message, exception=exc) def _get_tool_map( @@ -1141,7 +1306,7 @@ def _get_tool_map( return ai_function_list -async def _execute_function_calls( +async def _try_execute_function_calls( custom_args: dict[str, Any], attempt_idx: int, function_calls: Sequence["FunctionCallContent"] | Sequence["FunctionApprovalResponseContent"], @@ -1149,6 +1314,7 @@ async def _execute_function_calls( | Callable[..., Any] \ | MutableMapping[str, Any] \ | Sequence[ToolProtocol | Callable[..., Any] | MutableMapping[str, Any]]", + config: FunctionInvocationConfiguration, middleware_pipeline: Any = None, # Optional MiddlewarePipeline to avoid circular imports ) -> Sequence["Contents"]: """Execute multiple function calls concurrently. @@ -1158,22 +1324,33 @@ async def _execute_function_calls( attempt_idx: The index of the current attempt iteration. function_calls: A sequence of FunctionCallContent to execute. tools: The tools available for execution. + config: Configuration for function invocation. middleware_pipeline: Optional middleware pipeline to apply during execution. Returns: - A list of Contents containing the results of each function call. + A list of Contents containing the results of each function call, + or the approval requests if any function requires approval, + or the original function calls if any are declaration only. """ from ._types import FunctionApprovalRequestContent, FunctionCallContent tool_map = _get_tool_map(tools) approval_tools = [tool_name for tool_name, tool in tool_map.items() if tool.approval_mode == "always_require"] + declaration_only = [tool_name for tool_name, tool in tool_map.items() if tool.declaration_only] + additional_tool_names = [tool.name for tool in config.additional_tools] if config.additional_tools else [] # check if any are calling functions that need approval # if so, we return approval request for all approval_needed = False + declaration_only_flag = False for fcc in function_calls: if isinstance(fcc, FunctionCallContent) and fcc.name in approval_tools: approval_needed = True break + if isinstance(fcc, FunctionCallContent) and (fcc.name in declaration_only or fcc.name in additional_tool_names): + declaration_only_flag = True + break + if config.terminate_on_unknown_calls and isinstance(fcc, FunctionCallContent) and fcc.name not in tool_map: + raise KeyError(f'Error: Requested function "{fcc.name}" not found.') if approval_needed: # approval can only be needed for Function Call Contents, not Approval Responses. return [ @@ -1181,6 +1358,9 @@ async def _execute_function_calls( for fcc in function_calls if isinstance(fcc, FunctionCallContent) ] + if declaration_only_flag: + # return the declaration only tools to the user, since we cannot execute them. + return [fcc for fcc in function_calls if isinstance(fcc, FunctionCallContent)] # Run all function calls concurrently return await asyncio.gather(*[ @@ -1191,6 +1371,7 @@ async def _execute_function_calls( sequence_index=seq_idx, request_index=attempt_idx, middleware_pipeline=middleware_pipeline, + config=config, ) for seq_idx, function_call in enumerate(function_calls) ]) @@ -1334,17 +1515,17 @@ def _handle_function_calls_response( # because the underlying function may not preserve it in kwargs stored_middleware_pipeline = kwargs.get("_function_middleware_pipeline") - # Get max_iterations from instance additional_properties or class attribute - instance_max_iterations: int = DEFAULT_MAX_ITERATIONS - if hasattr(self, "additional_properties") and self.additional_properties: - instance_max_iterations = self.additional_properties.get("max_iterations", DEFAULT_MAX_ITERATIONS) - elif hasattr(self.__class__, "MAX_ITERATIONS"): - instance_max_iterations = getattr(self.__class__, "MAX_ITERATIONS", DEFAULT_MAX_ITERATIONS) + # Get the config for function invocation (not part of ChatClientProtocol, hence getattr) + config: FunctionInvocationConfiguration | None = getattr(self, "function_invocation_configuration", None) + if not config: + # Default config if not set + config = FunctionInvocationConfiguration() + errors_in_a_row: int = 0 prepped_messages = prepare_messages(messages) response: "ChatResponse | None" = None fcc_messages: "list[ChatMessage]" = [] - for attempt_idx in range(instance_max_iterations): + for attempt_idx in range(config.max_iterations if config.enabled else 0): fcc_todo = _collect_approval_responses(prepped_messages) if fcc_todo: tools = _extract_tools(kwargs) @@ -1352,13 +1533,29 @@ def _handle_function_calls_response( approved_responses = [resp for resp in fcc_todo.values() if resp.approved] approved_function_results: list[Contents] = [] if approved_responses: - approved_function_results = await _execute_function_calls( + approved_function_results = await _try_execute_function_calls( custom_args=kwargs, attempt_idx=attempt_idx, function_calls=approved_responses, tools=tools, # type: ignore middleware_pipeline=stored_middleware_pipeline, + config=config, ) + if any( + fcr.exception is not None + for fcr in approved_function_results + if isinstance(fcr, FunctionResultContent) + ): + errors_in_a_row += 1 + # no need to reset the counter here, since this is the start of a new attempt. + if errors_in_a_row >= config.max_consecutive_errors_per_request: + logger.warning( + "Maximum consecutive function call errors reached (%d). " + "Stopping further function calls for this request.", + config.max_consecutive_errors_per_request, + ) + # break out of the loop and do the fallback response + break _replace_approval_contents_with_results(prepped_messages, fcc_todo, approved_function_results) response = await func(self, messages=prepped_messages, **kwargs) @@ -1381,15 +1578,15 @@ def _handle_function_calls_response( if function_calls and tools: # Use the stored middleware pipeline instead of extracting from kwargs # because kwargs may have been modified by the underlying function - function_call_results: list[Contents] = await _execute_function_calls( + function_call_results: list[Contents] = await _try_execute_function_calls( custom_args=kwargs, attempt_idx=attempt_idx, function_calls=function_calls, tools=tools, # type: ignore middleware_pipeline=stored_middleware_pipeline, + config=config, ) - - # Check if we have approval requests in the results + # Check if we have approval requests or function calls (not results) in the results if any(isinstance(fccr, FunctionApprovalRequestContent) for fccr in function_call_results): # Add approval requests to the existing assistant message (with tool_calls) # instead of creating a separate tool message @@ -1402,6 +1599,26 @@ def _handle_function_calls_response( result_message = ChatMessage(role="assistant", contents=function_call_results) response.messages.append(result_message) return response + if any(isinstance(fccr, FunctionCallContent) for fccr in function_call_results): + # the function calls are already in the response, so we just continue + return response + + if any( + fcr.exception is not None + for fcr in function_call_results + if isinstance(fcr, FunctionResultContent) + ): + errors_in_a_row += 1 + if errors_in_a_row >= config.max_consecutive_errors_per_request: + logger.warning( + "Maximum consecutive function call errors reached (%d). " + "Stopping further function calls for this request.", + config.max_consecutive_errors_per_request, + ) + # break out of the loop and do the fallback response + break + else: + errors_in_a_row = 0 # add a single ChatMessage to the response with the results result_message = ChatMessage(role="tool", contents=function_call_results) @@ -1482,16 +1699,16 @@ def _handle_function_calls_streaming_response( # because the underlying function may not preserve it in kwargs stored_middleware_pipeline = kwargs.get("_function_middleware_pipeline") - # Get max_iterations from instance additional_properties or class attribute - instance_max_iterations: int = DEFAULT_MAX_ITERATIONS - if hasattr(self, "additional_properties") and self.additional_properties: - instance_max_iterations = self.additional_properties.get("max_iterations", DEFAULT_MAX_ITERATIONS) - elif hasattr(self.__class__, "MAX_ITERATIONS"): - instance_max_iterations = getattr(self.__class__, "MAX_ITERATIONS", DEFAULT_MAX_ITERATIONS) + # Get the config for function invocation (not part of ChatClientProtocol, hence getattr) + config: FunctionInvocationConfiguration | None = getattr(self, "function_invocation_configuration", None) + if not config: + # Default config if not set + config = FunctionInvocationConfiguration() + errors_in_a_row: int = 0 prepped_messages = prepare_messages(messages) fcc_messages: "list[ChatMessage]" = [] - for attempt_idx in range(instance_max_iterations): + for attempt_idx in range(config.max_iterations if config.enabled else 0): fcc_todo = _collect_approval_responses(prepped_messages) if fcc_todo: tools = _extract_tools(kwargs) @@ -1499,13 +1716,21 @@ def _handle_function_calls_streaming_response( approved_responses = [resp for resp in fcc_todo.values() if resp.approved] approved_function_results: list[Contents] = [] if approved_responses: - approved_function_results = await _execute_function_calls( + approved_function_results = await _try_execute_function_calls( custom_args=kwargs, attempt_idx=attempt_idx, function_calls=approved_responses, tools=tools, # type: ignore middleware_pipeline=stored_middleware_pipeline, + config=config, ) + if any( + fcr.exception is not None + for fcr in approved_function_results + if isinstance(fcr, FunctionResultContent) + ): + errors_in_a_row += 1 + # no need to reset the counter here, since this is the start of a new attempt. _replace_approval_contents_with_results(prepped_messages, fcc_todo, approved_function_results) all_updates: list["ChatResponseUpdate"] = [] @@ -1551,15 +1776,16 @@ def _handle_function_calls_streaming_response( if function_calls and tools: # Use the stored middleware pipeline instead of extracting from kwargs # because kwargs may have been modified by the underlying function - function_call_results: list[Contents] = await _execute_function_calls( + function_call_results: list[Contents] = await _try_execute_function_calls( custom_args=kwargs, attempt_idx=attempt_idx, function_calls=function_calls, tools=tools, # type: ignore middleware_pipeline=stored_middleware_pipeline, + config=config, ) - # Check if we have approval requests in the results + # Check if we have approval requests or function calls (not results) in the results if any(isinstance(fccr, FunctionApprovalRequestContent) for fccr in function_call_results): # Add approval requests to the existing assistant message (with tool_calls) # instead of creating a separate tool message @@ -1575,6 +1801,26 @@ def _handle_function_calls_streaming_response( yield ChatResponseUpdate(contents=function_call_results, role="assistant") response.messages.append(result_message) return + if any(isinstance(fccr, FunctionCallContent) for fccr in function_call_results): + # the function calls were already yielded. + return + + if any( + fcr.exception is not None + for fcr in function_call_results + if isinstance(fcr, FunctionResultContent) + ): + errors_in_a_row += 1 + if errors_in_a_row >= config.max_consecutive_errors_per_request: + logger.warning( + "Maximum consecutive function call errors reached (%d). " + "Stopping further function calls for this request.", + config.max_consecutive_errors_per_request, + ) + # break out of the loop and do the fallback response + break + else: + errors_in_a_row = 0 # add a single ChatMessage to the response with the results result_message = ChatMessage(role="tool", contents=function_call_results) @@ -1648,10 +1894,6 @@ def use_function_invocation( if getattr(chat_client, FUNCTION_INVOKING_CHAT_CLIENT_MARKER, False): return chat_client - # Set MAX_ITERATIONS as a class variable if not already set - if not hasattr(chat_client, "MAX_ITERATIONS"): - chat_client.MAX_ITERATIONS = DEFAULT_MAX_ITERATIONS # type: ignore - try: chat_client.get_response = _handle_function_calls_response( # type: ignore func=chat_client.get_response, # type: ignore diff --git a/python/packages/core/agent_framework/openai/_assistants_client.py b/python/packages/core/agent_framework/openai/_assistants_client.py index 239efb76e3..8a28075e62 100644 --- a/python/packages/core/agent_framework/openai/_assistants_client.py +++ b/python/packages/core/agent_framework/openai/_assistants_client.py @@ -502,8 +502,6 @@ class OpenAIAssistantsClient(OpenAIConfigMixin, BaseChatClient): tool_outputs = [] if function_result_content.result: output = prepare_function_call_results(function_result_content.result) - elif function_result_content.exception: - output = "Error: " + str(function_result_content.exception) else: output = "No output received." tool_outputs.append(ToolOutput(tool_call_id=call_id, output=output)) diff --git a/python/packages/core/agent_framework/openai/_chat_client.py b/python/packages/core/agent_framework/openai/_chat_client.py index 70a37894d4..e6a4087508 100644 --- a/python/packages/core/agent_framework/openai/_chat_client.py +++ b/python/packages/core/agent_framework/openai/_chat_client.py @@ -380,11 +380,6 @@ class OpenAIBaseChatClient(OpenAIBase, BaseChatClient): args["tool_call_id"] = content.call_id if content.result is not None: args["content"] = prepare_function_call_results(content.result) - elif content.exception is not None: - # Send the exception message to the model - # Otherwise we won't have any channels to talk to OpenAI - # TODO(yuge): This should ideally be customizable - args["content"] = "Error: " + str(content.exception) case _: if "content" not in args: args["content"] = [] diff --git a/python/packages/core/agent_framework/openai/_responses_client.py b/python/packages/core/agent_framework/openai/_responses_client.py index 0d422f33bc..279180e0ee 100644 --- a/python/packages/core/agent_framework/openai/_responses_client.py +++ b/python/packages/core/agent_framework/openai/_responses_client.py @@ -501,8 +501,6 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient): } if content.result: args["output"] = prepare_function_call_results(content.result) - if content.exception: - args["output"] = "Error: " + str(content.exception) return args case FunctionApprovalRequestContent(): return { diff --git a/python/packages/core/tests/core/test_function_invocation_logic.py b/python/packages/core/tests/core/test_function_invocation_logic.py index 2812f19c9d..77b95d98a2 100644 --- a/python/packages/core/tests/core/test_function_invocation_logic.py +++ b/python/packages/core/tests/core/test_function_invocation_logic.py @@ -605,7 +605,7 @@ async def test_max_iterations_limit(chat_client_base: ChatClientProtocol): ] # Set max_iterations to 1 in additional_properties - chat_client_base.additional_properties = {"max_iterations": 1} + chat_client_base.function_invocation_configuration.max_iterations = 1 response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[ai_func]) @@ -615,3 +615,1450 @@ async def test_max_iterations_limit(chat_client_base: ChatClientProtocol): # 3. Fall back to asking for a plain answer with tool_choice="none" assert exec_counter == 1 # Only first function executed assert response.messages[-1].text == "I broke out of the function invocation loop..." # Failsafe response + + +async def test_function_invocation_config_enabled_false(chat_client_base: ChatClientProtocol): + """Test that setting enabled=False disables function invocation.""" + exec_counter = 0 + + @ai_function(name="test_function") + def ai_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Processed {arg1}" + + chat_client_base.run_responses = [ + ChatResponse(messages=ChatMessage(role="assistant", text="response without function calling")), + ] + + # Disable function invocation + chat_client_base.function_invocation_configuration.enabled = False + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[ai_func]) + + # Function should not be executed - when enabled=False, the loop doesn't run + assert exec_counter == 0 + # The response should be from the mock client + assert len(response.messages) > 0 + + +async def test_function_invocation_config_max_consecutive_errors(chat_client_base: ChatClientProtocol): + """Test that max_consecutive_errors_per_request limits error retries.""" + + @ai_function(name="error_function") + def error_func(arg1: str) -> str: + raise ValueError("Function error") + + # Set up multiple function call responses that will all error + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="error_function", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="2", name="error_function", arguments='{"arg1": "value2"}')], + ) + ), + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="3", name="error_function", arguments='{"arg1": "value3"}')], + ) + ), + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="4", name="error_function", arguments='{"arg1": "value4"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="final response")), + ] + + # Set max_consecutive_errors to 2 + chat_client_base.function_invocation_configuration.max_consecutive_errors_per_request = 2 + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[error_func]) + + # Should stop after 2 consecutive errors and force a non-tool response + error_results = [ + content + for msg in response.messages + for content in msg.contents + if isinstance(content, FunctionResultContent) and content.exception + ] + # The first call errors, then the second call errors, hitting the limit + # So we get 2 function calls with errors, but the responses show the behavior stopped + assert len(error_results) >= 1 # At least one error occurred + # Should have stopped making new function calls after hitting the error limit + function_calls = [ + content for msg in response.messages for content in msg.contents if isinstance(content, FunctionCallContent) + ] + # Should have made at most 2 function calls before stopping + assert len(function_calls) <= 2 + + +async def test_function_invocation_config_terminate_on_unknown_calls_false(chat_client_base: ChatClientProtocol): + """Test that terminate_on_unknown_calls=False returns error message for unknown functions.""" + exec_counter = 0 + + @ai_function(name="known_function") + def known_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Processed {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="unknown_function", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Set terminate_on_unknown_calls to False (default) + chat_client_base.function_invocation_configuration.terminate_on_unknown_calls = False + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[known_func]) + + # Should have a result message indicating the tool wasn't found + assert len(response.messages) == 3 + assert isinstance(response.messages[1].contents[0], FunctionResultContent) + result_str = response.messages[1].contents[0].result or response.messages[1].contents[0].exception or "" + assert "not found" in result_str.lower() + assert exec_counter == 0 # Known function not executed + + +async def test_function_invocation_config_terminate_on_unknown_calls_true(chat_client_base: ChatClientProtocol): + """Test that terminate_on_unknown_calls=True stops execution on unknown functions.""" + exec_counter = 0 + + @ai_function(name="known_function") + def known_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Processed {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="unknown_function", arguments='{"arg1": "value1"}')], + ) + ), + ] + + # Set terminate_on_unknown_calls to True + chat_client_base.function_invocation_configuration.terminate_on_unknown_calls = True + + # Should raise an exception when encountering an unknown function + with pytest.raises(KeyError, match='Error: Requested function "unknown_function" not found'): + await chat_client_base.get_response("hello", tool_choice="auto", tools=[known_func]) + + assert exec_counter == 0 + + +async def test_function_invocation_config_additional_tools(chat_client_base: ChatClientProtocol): + """Test that additional_tools are available but treated as declaration_only.""" + exec_counter_visible = 0 + exec_counter_hidden = 0 + + @ai_function(name="visible_function") + def visible_func(arg1: str) -> str: + nonlocal exec_counter_visible + exec_counter_visible += 1 + return f"Visible {arg1}" + + @ai_function(name="hidden_function") + def hidden_func(arg1: str) -> str: + nonlocal exec_counter_hidden + exec_counter_hidden += 1 + return f"Hidden {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="hidden_function", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Add hidden_func to additional_tools + chat_client_base.function_invocation_configuration.additional_tools = [hidden_func] + + # Only pass visible_func in the tools parameter + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[visible_func]) + + # Additional tools are treated as declaration_only, so not executed + # The function call should be in the messages but not executed + assert exec_counter_hidden == 0 + assert exec_counter_visible == 0 + # Should have the function call in messages (declaration_only behavior) + function_calls = [ + content + for msg in response.messages + for content in msg.contents + if isinstance(content, FunctionCallContent) and content.name == "hidden_function" + ] + assert len(function_calls) >= 1 + + +async def test_function_invocation_config_include_detailed_errors_false(chat_client_base: ChatClientProtocol): + """Test that include_detailed_errors=False returns generic error messages.""" + + @ai_function(name="error_function") + def error_func(arg1: str) -> str: + raise ValueError("Specific error message that should not appear") + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="error_function", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Set include_detailed_errors to False (default) + chat_client_base.function_invocation_configuration.include_detailed_errors = False + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[error_func]) + + # Should have a generic error message + error_result = next( + content for msg in response.messages for content in msg.contents if isinstance(content, FunctionResultContent) + ) + assert error_result.result is not None + assert error_result.exception is not None + assert "Specific error message" not in error_result.result + assert "Error:" in error_result.result # Generic error prefix + + +async def test_function_invocation_config_include_detailed_errors_true(chat_client_base: ChatClientProtocol): + """Test that include_detailed_errors=True returns detailed error information.""" + + @ai_function(name="error_function") + def error_func(arg1: str) -> str: + raise ValueError("Specific error message that should appear") + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="error_function", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Set include_detailed_errors to True + chat_client_base.function_invocation_configuration.include_detailed_errors = True + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[error_func]) + + # Should have detailed error message + error_result = next( + content for msg in response.messages for content in msg.contents if isinstance(content, FunctionResultContent) + ) + assert error_result.result is not None + assert error_result.exception is not None + assert "Specific error message that should appear" in error_result.result + # The error format includes "Function failed. Exception:" prefix + assert "Exception:" in error_result.result + + +async def test_function_invocation_config_validation_max_iterations(): + """Test that max_iterations validation works correctly.""" + from agent_framework import FunctionInvocationConfiguration + + # Valid values + config = FunctionInvocationConfiguration(max_iterations=1) + assert config.max_iterations == 1 + + config = FunctionInvocationConfiguration(max_iterations=100) + assert config.max_iterations == 100 + + # Invalid value (less than 1) + with pytest.raises(ValueError, match="max_iterations must be at least 1"): + FunctionInvocationConfiguration(max_iterations=0) + + with pytest.raises(ValueError, match="max_iterations must be at least 1"): + FunctionInvocationConfiguration(max_iterations=-1) + + +async def test_function_invocation_config_validation_max_consecutive_errors(): + """Test that max_consecutive_errors_per_request validation works correctly.""" + from agent_framework import FunctionInvocationConfiguration + + # Valid values + config = FunctionInvocationConfiguration(max_consecutive_errors_per_request=0) + assert config.max_consecutive_errors_per_request == 0 + + config = FunctionInvocationConfiguration(max_consecutive_errors_per_request=5) + assert config.max_consecutive_errors_per_request == 5 + + # Invalid value (less than 0) + with pytest.raises(ValueError, match="max_consecutive_errors_per_request must be 0 or more"): + FunctionInvocationConfiguration(max_consecutive_errors_per_request=-1) + + +async def test_argument_validation_error_with_detailed_errors(chat_client_base: ChatClientProtocol): + """Test that argument validation errors include details when include_detailed_errors=True.""" + + @ai_function(name="typed_function") + def typed_func(arg1: int) -> str: # Expects int, not str + return f"Got {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="typed_function", arguments='{"arg1": "not_an_int"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Set include_detailed_errors to True + chat_client_base.function_invocation_configuration.include_detailed_errors = True + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[typed_func]) + + # Should have detailed validation error + error_result = next( + content for msg in response.messages for content in msg.contents if isinstance(content, FunctionResultContent) + ) + assert error_result.result is not None + assert error_result.exception is not None + assert "Argument parsing failed" in error_result.result + assert "Exception:" in error_result.result # Detailed error included + + +async def test_argument_validation_error_without_detailed_errors(chat_client_base: ChatClientProtocol): + """Test that argument validation errors are generic when include_detailed_errors=False.""" + + @ai_function(name="typed_function") + def typed_func(arg1: int) -> str: # Expects int, not str + return f"Got {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="typed_function", arguments='{"arg1": "not_an_int"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Set include_detailed_errors to False (default) + chat_client_base.function_invocation_configuration.include_detailed_errors = False + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[typed_func]) + + # Should have generic validation error + error_result = next( + content for msg in response.messages for content in msg.contents if isinstance(content, FunctionResultContent) + ) + assert error_result.result is not None + assert error_result.exception is not None + assert "Argument parsing failed" in error_result.result + assert "Exception:" not in error_result.result # No detailed error + + +async def test_hosted_tool_approval_response(chat_client_base: ChatClientProtocol): + """Test handling of approval responses for hosted tools (tools not in tool_map).""" + from agent_framework import FunctionApprovalResponseContent + + @ai_function(name="local_function") + def local_func(arg1: str) -> str: + return f"Local {arg1}" + + # Create an approval response for a hosted tool that's not in our tool_map + hosted_function_call = FunctionCallContent( + call_id="hosted_1", name="hosted_function", arguments='{"arg1": "value"}' + ) + approval_response = FunctionApprovalResponseContent( + id="approval_1", + function_call=hosted_function_call, + approved=True, + ) + + chat_client_base.run_responses = [ + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Send the approval response + response = await chat_client_base.get_response( + [ChatMessage(role="user", contents=[approval_response])], + tool_choice="auto", + tools=[local_func], + ) + + # The hosted tool approval should be returned as-is (not executed) + # Check that we got a response without errors + assert response is not None + + +async def test_unapproved_tool_execution_raises_exception(chat_client_base: ChatClientProtocol): + """Test that attempting to execute an unapproved tool raises ToolException.""" + from agent_framework import FunctionApprovalResponseContent + + @ai_function(name="test_function", approval_mode="always_require") + def test_func(arg1: str) -> str: + return f"Result {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[ + FunctionCallContent(call_id="1", name="test_function", arguments='{"arg1": "value1"}'), + ], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Get approval request + response1 = await chat_client_base.get_response("hello", tool_choice="auto", tools=[test_func]) + + approval_req = [c for c in response1.messages[0].contents if isinstance(c, FunctionApprovalRequestContent)][0] + + # Create a rejection response (approved=False) + rejection_response = FunctionApprovalResponseContent( + id=approval_req.id, + function_call=approval_req.function_call, + approved=False, + ) + + # Continue conversation with rejection + all_messages = response1.messages + [ChatMessage(role="user", contents=[rejection_response])] + + # This should handle the rejection gracefully (not raise ToolException to user) + await chat_client_base.get_response(all_messages, tool_choice="auto", tools=[test_func]) + + # Should have a rejection result + rejection_result = next( + ( + content + for msg in all_messages + for content in msg.contents + if isinstance(content, FunctionResultContent) + and "rejected" in (content.result or content.exception or "").lower() + ), + None, + ) + assert rejection_result is not None + + +async def test_approved_function_call_with_error_without_detailed_errors(chat_client_base: ChatClientProtocol): + """Test that approved functions that raise errors return generic error messages. + + When include_detailed_errors=False. + """ + from agent_framework import FunctionApprovalResponseContent + + exec_counter = 0 + + @ai_function(name="error_func", approval_mode="always_require") + def error_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + raise ValueError("Specific error from approved function") + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="error_func", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Set include_detailed_errors to False (default) + chat_client_base.function_invocation_configuration.include_detailed_errors = False + + # Get approval request + response1 = await chat_client_base.get_response("hello", tool_choice="auto", tools=[error_func]) + + approval_req = [c for c in response1.messages[0].contents if isinstance(c, FunctionApprovalRequestContent)][0] + + # Approve the function + approval_response = FunctionApprovalResponseContent( + id=approval_req.id, + function_call=approval_req.function_call, + approved=True, + ) + + all_messages = response1.messages + [ChatMessage(role="user", contents=[approval_response])] + + # Execute the approved function (which will error) + await chat_client_base.get_response(all_messages, tool_choice="auto", tools=[error_func]) + + # Should have executed the function + assert exec_counter == 1 + + # Should have an error result with generic message + error_result = next( + ( + content + for msg in all_messages + for content in msg.contents + if isinstance(content, FunctionResultContent) and content.exception is not None + ), + None, + ) + assert error_result is not None + assert error_result.result is not None + assert "Error: Function failed." in error_result.result + assert "Specific error from approved function" not in error_result.result # Detail not included + + +async def test_approved_function_call_with_error_with_detailed_errors(chat_client_base: ChatClientProtocol): + """Test that approved functions that raise errors return detailed error messages. + + When include_detailed_errors=True. + """ + from agent_framework import FunctionApprovalResponseContent + + exec_counter = 0 + + @ai_function(name="error_func", approval_mode="always_require") + def error_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + raise ValueError("Specific error from approved function") + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="error_func", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Set include_detailed_errors to True + chat_client_base.function_invocation_configuration.include_detailed_errors = True + + # Get approval request + response1 = await chat_client_base.get_response("hello", tool_choice="auto", tools=[error_func]) + + approval_req = [c for c in response1.messages[0].contents if isinstance(c, FunctionApprovalRequestContent)][0] + + # Approve the function + approval_response = FunctionApprovalResponseContent( + id=approval_req.id, + function_call=approval_req.function_call, + approved=True, + ) + + all_messages = response1.messages + [ChatMessage(role="user", contents=[approval_response])] + + # Execute the approved function (which will error) + await chat_client_base.get_response(all_messages, tool_choice="auto", tools=[error_func]) + + # Should have executed the function + assert exec_counter == 1 + + # Should have an error result with detailed message + error_result = next( + ( + content + for msg in all_messages + for content in msg.contents + if isinstance(content, FunctionResultContent) and content.exception is not None + ), + None, + ) + assert error_result is not None + assert error_result.result is not None + assert "Error: Function failed." in error_result.result + assert "Exception:" in error_result.result + assert "Specific error from approved function" in error_result.result # Detail included + + +async def test_approved_function_call_with_validation_error(chat_client_base: ChatClientProtocol): + """Test that approved functions with validation errors are handled correctly.""" + from agent_framework import FunctionApprovalResponseContent + + exec_counter = 0 + + @ai_function(name="typed_func", approval_mode="always_require") + def typed_func(arg1: int) -> str: # Expects int, not str + nonlocal exec_counter + exec_counter += 1 + return f"Got {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="typed_func", arguments='{"arg1": "not_an_int"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Set include_detailed_errors to True to see validation details + chat_client_base.function_invocation_configuration.include_detailed_errors = True + + # Get approval request + response1 = await chat_client_base.get_response("hello", tool_choice="auto", tools=[typed_func]) + + approval_req = [c for c in response1.messages[0].contents if isinstance(c, FunctionApprovalRequestContent)][0] + + # Approve the function (even though it will fail validation) + approval_response = FunctionApprovalResponseContent( + id=approval_req.id, + function_call=approval_req.function_call, + approved=True, + ) + + all_messages = response1.messages + [ChatMessage(role="user", contents=[approval_response])] + + # Execute the approved function (which will fail validation) + await chat_client_base.get_response(all_messages, tool_choice="auto", tools=[typed_func]) + + # Should NOT have executed the function (validation failed before execution) + assert exec_counter == 0 + + # Should have a validation error result + error_result = next( + ( + content + for msg in all_messages + for content in msg.contents + if isinstance(content, FunctionResultContent) and content.exception is not None + ), + None, + ) + assert error_result is not None + assert error_result.result is not None + assert "Argument parsing failed" in error_result.result + + +async def test_approved_function_call_successful_execution(chat_client_base: ChatClientProtocol): + """Test that approved functions execute successfully when no errors occur.""" + from agent_framework import FunctionApprovalResponseContent + + exec_counter = 0 + + @ai_function(name="success_func", approval_mode="always_require") + def success_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Success {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="success_func", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Get approval request + response1 = await chat_client_base.get_response("hello", tool_choice="auto", tools=[success_func]) + + approval_req = [c for c in response1.messages[0].contents if isinstance(c, FunctionApprovalRequestContent)][0] + + # Approve the function + approval_response = FunctionApprovalResponseContent( + id=approval_req.id, + function_call=approval_req.function_call, + approved=True, + ) + + all_messages = response1.messages + [ChatMessage(role="user", contents=[approval_response])] + + # Execute the approved function + await chat_client_base.get_response(all_messages, tool_choice="auto", tools=[success_func]) + + # Should have executed successfully + assert exec_counter == 1 + + # Should have a success result + success_result = next( + ( + content + for msg in all_messages + for content in msg.contents + if isinstance(content, FunctionResultContent) and content.exception is None + ), + None, + ) + assert success_result is not None + assert success_result.result == "Success value1" + + +async def test_declaration_only_tool_not_executed(chat_client_base: ChatClientProtocol): + """Test that declaration_only tools are not executed.""" + exec_counter = 0 + + @ai_function(name="declaration_func") + def declaration_func_inner(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Result {arg1}" + + # Create a new AIFunction with declaration_only set + from agent_framework import AIFunction + + declaration_func = AIFunction( + name="declaration_func", + func=declaration_func_inner, + additional_properties={"declaration_only": True}, + ) + # Set declaration_only on the instance + object.__setattr__(declaration_func, "_declaration_only", True) + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="declaration_func", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[declaration_func]) + + # Function should NOT be executed + assert exec_counter == 0 + # Should have the function call in messages but not a result + function_calls = [ + content + for msg in response.messages + for content in msg.contents + if isinstance(content, FunctionCallContent) and content.name == "declaration_func" + ] + assert len(function_calls) >= 1 + + +async def test_multiple_function_calls_parallel_execution(chat_client_base: ChatClientProtocol): + """Test that multiple function calls are executed in parallel.""" + import asyncio + + exec_order = [] + + @ai_function(name="func1") + async def func1(arg1: str) -> str: + exec_order.append("func1_start") + await asyncio.sleep(0.01) # Small delay + exec_order.append("func1_end") + return f"Result1 {arg1}" + + @ai_function(name="func2") + async def func2(arg1: str) -> str: + exec_order.append("func2_start") + await asyncio.sleep(0.01) # Small delay + exec_order.append("func2_end") + return f"Result2 {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[ + FunctionCallContent(call_id="1", name="func1", arguments='{"arg1": "value1"}'), + FunctionCallContent(call_id="2", name="func2", arguments='{"arg1": "value2"}'), + ], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[func1, func2]) + + # Both functions should have been executed + assert "func1_start" in exec_order + assert "func1_end" in exec_order + assert "func2_start" in exec_order + assert "func2_end" in exec_order + + # Should have results for both + results = [ + content for msg in response.messages for content in msg.contents if isinstance(content, FunctionResultContent) + ] + assert len(results) == 2 + + +async def test_callable_function_converted_to_ai_function(chat_client_base: ChatClientProtocol): + """Test that plain callable functions are converted to AIFunction.""" + exec_counter = 0 + + def plain_function(arg1: str) -> str: + """A plain function without decorator.""" + nonlocal exec_counter + exec_counter += 1 + return f"Plain {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="plain_function", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + # Pass plain function (will be auto-converted) + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[plain_function]) + + # Function should be executed + assert exec_counter == 1 + result = next( + content for msg in response.messages for content in msg.contents if isinstance(content, FunctionResultContent) + ) + assert result.result == "Plain value1" + + +async def test_conversation_id_handling(chat_client_base: ChatClientProtocol): + """Test that conversation_id is properly handled and messages are cleared.""" + + @ai_function(name="test_function") + def test_func(arg1: str) -> str: + return f"Result {arg1}" + + # Return a response with a conversation_id + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="test_function", arguments='{"arg1": "value1"}')], + ), + conversation_id="conv_123", # Simulate service-side thread + ), + ChatResponse( + messages=ChatMessage(role="assistant", text="done"), + conversation_id="conv_123", + ), + ] + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[test_func]) + + # Should have executed the function + results = [ + content for msg in response.messages for content in msg.contents if isinstance(content, FunctionResultContent) + ] + assert len(results) >= 1 + assert response.conversation_id == "conv_123" + + +async def test_function_result_appended_to_existing_assistant_message(chat_client_base: ChatClientProtocol): + """Test that function results are appended to existing assistant message when appropriate.""" + + @ai_function(name="test_function") + def test_func(arg1: str) -> str: + return f"Result {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="test_function", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[test_func]) + + # Should have messages with both function call and function result + assert len(response.messages) >= 2 + # Check that we have both a function call and a function result + has_call = any(isinstance(content, FunctionCallContent) for msg in response.messages for content in msg.contents) + has_result = any( + isinstance(content, FunctionResultContent) for msg in response.messages for content in msg.contents + ) + assert has_call + assert has_result + + +async def test_error_recovery_resets_counter(chat_client_base: ChatClientProtocol): + """Test that error counter resets after a successful function call.""" + + call_count = 0 + + @ai_function(name="sometimes_fails") + def sometimes_fails(arg1: str) -> str: + nonlocal call_count + call_count += 1 + if call_count == 1: + raise ValueError("First call fails") + return f"Success {arg1}" + + chat_client_base.run_responses = [ + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="1", name="sometimes_fails", arguments='{"arg1": "value1"}')], + ) + ), + ChatResponse( + messages=ChatMessage( + role="assistant", + contents=[FunctionCallContent(call_id="2", name="sometimes_fails", arguments='{"arg1": "value2"}')], + ) + ), + ChatResponse(messages=ChatMessage(role="assistant", text="done")), + ] + + response = await chat_client_base.get_response("hello", tool_choice="auto", tools=[sometimes_fails]) + + # Should have both an error and a success + error_results = [ + content + for msg in response.messages + for content in msg.contents + if isinstance(content, FunctionResultContent) and content.exception + ] + success_results = [ + content + for msg in response.messages + for content in msg.contents + if isinstance(content, FunctionResultContent) and content.result + ] + + assert len(error_results) >= 1 + assert len(success_results) >= 1 + assert call_count == 2 # Both calls executed + + +# ==================== STREAMING SCENARIO TESTS ==================== + + +async def test_streaming_approval_request_generated(chat_client_base: ChatClientProtocol): + """Test that approval requests are generated correctly in streaming mode.""" + exec_counter = 0 + + @ai_function(name="test_func", approval_mode="always_require") + def func_with_approval(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Result {arg1}" + + # Setup: function call that requires approval, streamed + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="test_func", arguments='{"arg1": "value1"}')], + role="assistant", + ), + ], + ] + + # Get the streaming response with approval request + updates = [] + async for update in chat_client_base.get_streaming_response( + "hello", tool_choice="auto", tools=[func_with_approval] + ): + updates.append(update) + + # Should have function call update and approval request + approval_requests = [ + content + for update in updates + for content in update.contents + if isinstance(content, FunctionApprovalRequestContent) + ] + assert len(approval_requests) == 1 + assert approval_requests[0].function_call.name == "test_func" + assert exec_counter == 0 # Function not executed yet due to approval requirement + + +async def test_streaming_max_iterations_limit(chat_client_base: ChatClientProtocol): + """Test that MAX_ITERATIONS in streaming mode limits function call loops.""" + exec_counter = 0 + + @ai_function(name="test_function") + def ai_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Processed {arg1}" + + # Set up multiple function call responses to create a loop + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="test_function", arguments='{"arg1":')], + role="assistant", + ), + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="test_function", arguments='"value1"}')], + role="assistant", + ), + ], + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="2", name="test_function", arguments='{"arg1":')], + role="assistant", + ), + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="2", name="test_function", arguments='"value2"}')], + role="assistant", + ), + ], + # Failsafe response when tool_choice is set to "none" + [ChatResponseUpdate(contents=[TextContent(text="giving up on tools")], role="assistant")], + ] + + # Set max_iterations to 1 in additional_properties + chat_client_base.function_invocation_configuration.max_iterations = 1 + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[ai_func]): + updates.append(update) + + # With max_iterations=1, we should only execute first function + assert exec_counter == 1 # Only first function executed + # Should have the failsafe message + last_text = "".join(u.text or "" for u in updates if u.text) + assert "I broke out of the function invocation loop..." in last_text + + +async def test_streaming_function_invocation_config_enabled_false(chat_client_base: ChatClientProtocol): + """Test that setting enabled=False disables function invocation in streaming mode.""" + exec_counter = 0 + + @ai_function(name="test_function") + def ai_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Processed {arg1}" + + chat_client_base.streaming_responses = [ + [ChatResponseUpdate(contents=[TextContent(text="response without function calling")], role="assistant")], + ] + + # Disable function invocation + chat_client_base.function_invocation_configuration.enabled = False + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[ai_func]): + updates.append(update) + + # Function should not be executed - when enabled=False, the loop doesn't run + assert exec_counter == 0 + # The response should be from the mock client + assert len(updates) > 0 + + +async def test_streaming_function_invocation_config_max_consecutive_errors(chat_client_base: ChatClientProtocol): + """Test that max_consecutive_errors_per_request limits error retries in streaming mode.""" + + @ai_function(name="error_function") + def error_func(arg1: str) -> str: + raise ValueError("Function error") + + # Set up multiple function call responses that will all error + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="error_function", arguments='{"arg1": "value1"}')], + role="assistant", + ), + ], + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="2", name="error_function", arguments='{"arg1": "value2"}')], + role="assistant", + ), + ], + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="3", name="error_function", arguments='{"arg1": "value3"}')], + role="assistant", + ), + ], + [ChatResponseUpdate(contents=[TextContent(text="final response")], role="assistant")], + ] + + # Set max_consecutive_errors to 2 + chat_client_base.function_invocation_configuration.max_consecutive_errors_per_request = 2 + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[error_func]): + updates.append(update) + + # Should stop after 2 consecutive errors + error_results = [ + content + for update in updates + for content in update.contents + if isinstance(content, FunctionResultContent) and content.exception + ] + # At least one error occurred + assert len(error_results) >= 1 + # Should have stopped making new function calls after hitting the error limit + function_calls = [ + content for update in updates for content in update.contents if isinstance(content, FunctionCallContent) + ] + # Should have made at most 2 function calls before stopping + assert len(function_calls) <= 2 + + +async def test_streaming_function_invocation_config_terminate_on_unknown_calls_false( + chat_client_base: ChatClientProtocol, +): + """Test that terminate_on_unknown_calls=False returns error message for unknown functions in streaming mode.""" + exec_counter = 0 + + @ai_function(name="known_function") + def known_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Processed {arg1}" + + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="unknown_function", arguments='{"arg1": "value1"}')], + role="assistant", + ), + ], + [ChatResponseUpdate(contents=[TextContent(text="done")], role="assistant")], + ] + + # Set terminate_on_unknown_calls to False (default) + chat_client_base.function_invocation_configuration.terminate_on_unknown_calls = False + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[known_func]): + updates.append(update) + + # Should have a result message indicating the tool wasn't found + result_contents = [ + content for update in updates for content in update.contents if isinstance(content, FunctionResultContent) + ] + assert len(result_contents) >= 1 + result_str = result_contents[0].result or result_contents[0].exception or "" + assert "not found" in result_str.lower() + assert exec_counter == 0 # Known function not executed + + +async def test_streaming_function_invocation_config_terminate_on_unknown_calls_true( + chat_client_base: ChatClientProtocol, +): + """Test that terminate_on_unknown_calls=True stops execution on unknown functions in streaming mode.""" + exec_counter = 0 + + @ai_function(name="known_function") + def known_func(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Processed {arg1}" + + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="unknown_function", arguments='{"arg1": "value1"}')], + role="assistant", + ), + ], + ] + + # Set terminate_on_unknown_calls to True + chat_client_base.function_invocation_configuration.terminate_on_unknown_calls = True + + # Should raise an exception when encountering an unknown function + with pytest.raises(KeyError, match='Error: Requested function "unknown_function" not found'): + async for _ in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[known_func]): + pass + + assert exec_counter == 0 + + +async def test_streaming_function_invocation_config_include_detailed_errors_true(chat_client_base: ChatClientProtocol): + """Test that include_detailed_errors=True returns detailed error information in streaming mode.""" + + @ai_function(name="error_function") + def error_func(arg1: str) -> str: + raise ValueError("Specific error message that should appear") + + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="error_function", arguments='{"arg1": "value1"}')], + role="assistant", + ), + ], + [ChatResponseUpdate(contents=[TextContent(text="done")], role="assistant")], + ] + + # Set include_detailed_errors to True + chat_client_base.function_invocation_configuration.include_detailed_errors = True + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[error_func]): + updates.append(update) + + # Should have detailed error message + error_result = next( + content for update in updates for content in update.contents if isinstance(content, FunctionResultContent) + ) + assert error_result.result is not None + assert error_result.exception is not None + assert "Specific error message that should appear" in error_result.result + assert "Exception:" in error_result.result + + +async def test_streaming_function_invocation_config_include_detailed_errors_false( + chat_client_base: ChatClientProtocol, +): + """Test that include_detailed_errors=False returns generic error messages in streaming mode.""" + + @ai_function(name="error_function") + def error_func(arg1: str) -> str: + raise ValueError("Specific error message that should not appear") + + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="error_function", arguments='{"arg1": "value1"}')], + role="assistant", + ), + ], + [ChatResponseUpdate(contents=[TextContent(text="done")], role="assistant")], + ] + + # Set include_detailed_errors to False (default) + chat_client_base.function_invocation_configuration.include_detailed_errors = False + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[error_func]): + updates.append(update) + + # Should have a generic error message + error_result = next( + content for update in updates for content in update.contents if isinstance(content, FunctionResultContent) + ) + assert error_result.result is not None + assert error_result.exception is not None + assert "Specific error message" not in error_result.result + assert "Error:" in error_result.result # Generic error prefix + + +async def test_streaming_argument_validation_error_with_detailed_errors(chat_client_base: ChatClientProtocol): + """Test that argument validation errors include details when include_detailed_errors=True in streaming mode.""" + + @ai_function(name="typed_function") + def typed_func(arg1: int) -> str: # Expects int, not str + return f"Got {arg1}" + + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="typed_function", arguments='{"arg1": "not_an_int"}')], + role="assistant", + ), + ], + [ChatResponseUpdate(contents=[TextContent(text="done")], role="assistant")], + ] + + # Set include_detailed_errors to True + chat_client_base.function_invocation_configuration.include_detailed_errors = True + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[typed_func]): + updates.append(update) + + # Should have detailed validation error + error_result = next( + content for update in updates for content in update.contents if isinstance(content, FunctionResultContent) + ) + assert error_result.result is not None + assert error_result.exception is not None + assert "Argument parsing failed" in error_result.result + assert "Exception:" in error_result.result # Detailed error included + + +async def test_streaming_argument_validation_error_without_detailed_errors(chat_client_base: ChatClientProtocol): + """Test that argument validation errors are generic when include_detailed_errors=False in streaming mode.""" + + @ai_function(name="typed_function") + def typed_func(arg1: int) -> str: # Expects int, not str + return f"Got {arg1}" + + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="typed_function", arguments='{"arg1": "not_an_int"}')], + role="assistant", + ), + ], + [ChatResponseUpdate(contents=[TextContent(text="done")], role="assistant")], + ] + + # Set include_detailed_errors to False (default) + chat_client_base.function_invocation_configuration.include_detailed_errors = False + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[typed_func]): + updates.append(update) + + # Should have generic validation error + error_result = next( + content for update in updates for content in update.contents if isinstance(content, FunctionResultContent) + ) + assert error_result.result is not None + assert error_result.exception is not None + assert "Argument parsing failed" in error_result.result + assert "Exception:" not in error_result.result # No detailed error + + +async def test_streaming_multiple_function_calls_parallel_execution(chat_client_base: ChatClientProtocol): + """Test that multiple function calls are executed in parallel in streaming mode.""" + import asyncio + + exec_order = [] + + @ai_function(name="func1") + async def func1(arg1: str) -> str: + exec_order.append("func1_start") + await asyncio.sleep(0.01) # Small delay + exec_order.append("func1_end") + return f"Result1 {arg1}" + + @ai_function(name="func2") + async def func2(arg1: str) -> str: + exec_order.append("func2_start") + await asyncio.sleep(0.01) # Small delay + exec_order.append("func2_end") + return f"Result2 {arg1}" + + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="func1", arguments='{"arg1": "value1"}')], + role="assistant", + ), + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="2", name="func2", arguments='{"arg1": "value2"}')], + role="assistant", + ), + ], + [ChatResponseUpdate(contents=[TextContent(text="done")], role="assistant")], + ] + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[func1, func2]): + updates.append(update) + + # Both functions should have been executed + assert "func1_start" in exec_order + assert "func1_end" in exec_order + assert "func2_start" in exec_order + assert "func2_end" in exec_order + + # Should have results for both + results = [ + content for update in updates for content in update.contents if isinstance(content, FunctionResultContent) + ] + assert len(results) == 2 + + +async def test_streaming_approval_requests_in_assistant_message(chat_client_base: ChatClientProtocol): + """Approval requests should be added to assistant updates in streaming mode.""" + exec_counter = 0 + + @ai_function(name="test_func", approval_mode="always_require") + def func_with_approval(arg1: str) -> str: + nonlocal exec_counter + exec_counter += 1 + return f"Result {arg1}" + + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[ + FunctionCallContent(call_id="1", name="test_func", arguments='{"arg1": "value1"}'), + ], + role="assistant", + ), + ], + ] + + updates = [] + async for update in chat_client_base.get_streaming_response( + "hello", tool_choice="auto", tools=[func_with_approval] + ): + updates.append(update) + + # Should have updates containing both the call and approval request + approval_requests = [ + content + for update in updates + for content in update.contents + if isinstance(content, FunctionApprovalRequestContent) + ] + assert len(approval_requests) == 1 + assert exec_counter == 0 + + +async def test_streaming_error_recovery_resets_counter(chat_client_base: ChatClientProtocol): + """Test that error counter resets after a successful function call in streaming mode.""" + + call_count = 0 + + @ai_function(name="sometimes_fails") + def sometimes_fails(arg1: str) -> str: + nonlocal call_count + call_count += 1 + if call_count == 1: + raise ValueError("First call fails") + return f"Success {arg1}" + + chat_client_base.streaming_responses = [ + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="1", name="sometimes_fails", arguments='{"arg1": "value1"}')], + role="assistant", + ), + ], + [ + ChatResponseUpdate( + contents=[FunctionCallContent(call_id="2", name="sometimes_fails", arguments='{"arg1": "value2"}')], + role="assistant", + ), + ], + [ChatResponseUpdate(contents=[TextContent(text="done")], role="assistant")], + ] + + updates = [] + async for update in chat_client_base.get_streaming_response("hello", tool_choice="auto", tools=[sometimes_fails]): + updates.append(update) + + # Should have both an error and a success + error_results = [ + content + for update in updates + for content in update.contents + if isinstance(content, FunctionResultContent) and content.exception + ] + success_results = [ + content + for update in updates + for content in update.contents + if isinstance(content, FunctionResultContent) and content.result + ] + + assert len(error_results) >= 1 + assert len(success_results) >= 1 + assert call_count == 2 # Both calls executed diff --git a/python/packages/core/tests/core/test_tools.py b/python/packages/core/tests/core/test_tools.py index e2cf6b8d3d..acd9157363 100644 --- a/python/packages/core/tests/core/test_tools.py +++ b/python/packages/core/tests/core/test_tools.py @@ -63,6 +63,26 @@ def test_ai_function_decorator_without_args(): assert test_tool(1, 2) == 3 +def test_ai_function_without_args(): + """Test the ai_function decorator.""" + + @ai_function + def test_tool() -> int: + """A simple function that adds two numbers.""" + return 1 + 2 + + assert isinstance(test_tool, ToolProtocol) + assert isinstance(test_tool, AIFunction) + assert test_tool.name == "test_tool" + assert test_tool.description == "A simple function that adds two numbers." + assert test_tool.parameters() == { + "properties": {}, + "title": "test_tool_input", + "type": "object", + } + assert test_tool() == 3 + + async def test_ai_function_decorator_with_async(): """Test the ai_function decorator with an async function.""" diff --git a/python/packages/core/tests/openai/test_openai_chat_client.py b/python/packages/core/tests/openai/test_openai_chat_client.py index d159091311..8af3ed61aa 100644 --- a/python/packages/core/tests/openai/test_openai_chat_client.py +++ b/python/packages/core/tests/openai/test_openai_chat_client.py @@ -689,12 +689,15 @@ def test_function_result_exception_handling(openai_unit_test_env: dict[str, str] # Test with exception (no result) test_exception = ValueError("Test error message") message_with_exception = ChatMessage( - role="tool", contents=[FunctionResultContent(call_id="call-123", exception=test_exception)] + role="tool", + contents=[ + FunctionResultContent(call_id="call-123", result="Error: Function failed.", exception=test_exception) + ], ) openai_messages = client._openai_chat_message_parser(message_with_exception) assert len(openai_messages) == 1 - assert openai_messages[0]["content"] == "Error: Test error message" + assert openai_messages[0]["content"] == "Error: Function failed." assert openai_messages[0]["tool_call_id"] == "call-123" diff --git a/python/samples/README.md b/python/samples/README.md index f8602b3385..f70a390892 100644 --- a/python/samples/README.md +++ b/python/samples/README.md @@ -218,9 +218,14 @@ This directory contains samples demonstrating the capabilities of Microsoft Agen | File | Description | |------|-------------| -| [`getting_started/tools/ai_tool_with_approval.py`](./getting_started/tools/ai_tool_with_approval.py) | Demonstration of a tool with approvals | -| [`getting_started/tools/ai_tool_with_approval_and_threads.py`](./getting_started/tools/ai_tool_with_approval_and_threads.py) | Tool Approvals with Threads | -| [`getting_started/tools/failing_tools.py`](./getting_started/tools/failing_tools.py) | Tool exceptions handled by returning the error for the agent to recover from | +| [`getting_started/tools/ai_function_declaration_only.py`](./getting_started/tools/ai_function_declaration_only.py) | Function declarations without implementations for testing agent reasoning | +| [`getting_started/tools/ai_function_from_dict_with_dependency_injection.py`](./getting_started/tools/ai_function_from_dict_with_dependency_injection.py) | Creating AI functions from dictionary definitions using dependency injection | +| [`getting_started/tools/ai_function_recover_from_failures.py`](./getting_started/tools/ai_function_recover_from_failures.py) | Graceful error handling when tools raise exceptions | +| [`getting_started/tools/ai_function_with_approval.py`](./getting_started/tools/ai_function_with_approval.py) | User approval workflows for function calls without threads | +| [`getting_started/tools/ai_function_with_approval_and_threads.py`](./getting_started/tools/ai_function_with_approval_and_threads.py) | Tool approval workflows using threads for conversation history management | +| [`getting_started/tools/ai_function_with_max_exceptions.py`](./getting_started/tools/ai_function_with_max_exceptions.py) | Limiting tool failure exceptions using max_invocation_exceptions | +| [`getting_started/tools/ai_function_with_max_invocations.py`](./getting_started/tools/ai_function_with_max_invocations.py) | Limiting total tool invocations using max_invocations | +| [`getting_started/tools/ai_functions_in_class.py`](./getting_started/tools/ai_functions_in_class.py) | Using ai_function decorator with class methods for stateful tools | ## Workflows diff --git a/python/samples/getting_started/tools/README.md b/python/samples/getting_started/tools/README.md index e69de29bb2..66ca227da6 100644 --- a/python/samples/getting_started/tools/README.md +++ b/python/samples/getting_started/tools/README.md @@ -0,0 +1,119 @@ +# Tools Examples + +This folder contains examples demonstrating how to use AI functions (tools) with the Agent Framework. AI functions allow agents to interact with external systems, perform computations, and execute custom logic. + +## Examples + +| File | Description | +|------|-------------| +| [`ai_function_declaration_only.py`](ai_function_declaration_only.py) | Demonstrates how to create function declarations without implementations. Useful for testing agent reasoning about tool usage or when tools are defined elsewhere. Shows how agents request tool calls even when the tool won't be executed. | +| [`ai_function_from_dict_with_dependency_injection.py`](ai_function_from_dict_with_dependency_injection.py) | Shows how to create AI functions from dictionary definitions using dependency injection. The function implementation is injected at runtime during deserialization, enabling dynamic tool creation and configuration. Note: This serialization/deserialization feature is in active development. | +| [`ai_function_recover_from_failures.py`](ai_function_recover_from_failures.py) | Demonstrates graceful error handling when tools raise exceptions. Shows how agents receive error information and can recover from failures, deciding whether to retry or respond differently based on the exception. | +| [`ai_function_with_approval.py`](ai_function_with_approval.py) | Shows how to implement user approval workflows for function calls without using threads. Demonstrates both streaming and non-streaming approval patterns where users can approve or reject function executions before they run. | +| [`ai_function_with_approval_and_threads.py`](ai_function_with_approval_and_threads.py) | Demonstrates tool approval workflows using threads for automatic conversation history management. Shows how threads simplify approval workflows by automatically storing and retrieving conversation context. Includes both approval and rejection examples. | +| [`ai_function_with_max_exceptions.py`](ai_function_with_max_exceptions.py) | Shows how to limit the number of times a tool can fail with exceptions using `max_invocation_exceptions`. Useful for preventing expensive tools from being called repeatedly when they keep failing. | +| [`ai_function_with_max_invocations.py`](ai_function_with_max_invocations.py) | Demonstrates limiting the total number of times a tool can be invoked using `max_invocations`. Useful for rate-limiting expensive operations or ensuring tools are only called a specific number of times per conversation. | +| [`ai_functions_in_class.py`](ai_functions_in_class.py) | Shows how to use `ai_function` decorator with class methods to create stateful tools. Demonstrates how class state can control tool behavior dynamically, allowing you to adjust tool functionality at runtime by modifying class properties. | + +## Key Concepts + +### AI Function Features + +- **Function Declarations**: Define tool schemas without implementations for testing or external tools +- **Dependency Injection**: Create tools from configurations with runtime-injected implementations +- **Error Handling**: Gracefully handle and recover from tool execution failures +- **Approval Workflows**: Require user approval before executing sensitive or important operations +- **Invocation Limits**: Control how many times tools can be called or fail +- **Stateful Tools**: Use class methods as tools to maintain state and dynamically control behavior + +### Common Patterns + +#### Basic Tool Definition + +```python +from agent_framework import ai_function +from typing import Annotated + +@ai_function +def my_tool(param: Annotated[str, "Description"]) -> str: + """Tool description for the AI.""" + return f"Result: {param}" +``` + +#### Tool with Approval + +```python +@ai_function(approval_mode="always_require") +def sensitive_operation(data: Annotated[str, "Data to process"]) -> str: + """This requires user approval before execution.""" + return f"Processed: {data}" +``` + +#### Tool with Invocation Limits + +```python +@ai_function(max_invocations=3) +def limited_tool() -> str: + """Can only be called 3 times total.""" + return "Result" + +@ai_function(max_invocation_exceptions=2) +def fragile_tool() -> str: + """Can only fail 2 times before being disabled.""" + return "Result" +``` + +#### Stateful Tools with Classes + +```python +class MyTools: + def __init__(self, mode: str = "normal"): + self.mode = mode + + def process(self, data: Annotated[str, "Data to process"]) -> str: + """Process data based on current mode.""" + if self.mode == "safe": + return f"Safely processed: {data}" + return f"Processed: {data}" + +# Create instance and use methods as tools +tools = MyTools(mode="safe") +agent = client.create_agent(tools=tools.process) + +# Change behavior dynamically +tools.mode = "normal" +``` + +### Error Handling + +When tools raise exceptions: +1. The exception is captured and sent to the agent as a function result +2. The agent receives the error message and can reason about what went wrong +3. The agent can retry with different parameters, use alternative tools, or explain the issue to the user +4. With invocation limits, tools can be disabled after repeated failures + +### Approval Workflows + +Two approaches for handling approvals: + +1. **Without Threads**: Manually manage conversation context, including the query, approval request, and response in each iteration +2. **With Threads**: Thread automatically manages conversation history, simplifying the approval workflow + +## Usage Tips + +- Use **declaration-only** functions when you want to test agent reasoning without execution +- Use **dependency injection** for dynamic tool configuration and plugin architectures +- Implement **approval workflows** for operations that modify data, spend money, or require human oversight +- Set **invocation limits** to prevent runaway costs or infinite loops with expensive tools +- Handle **exceptions gracefully** to create robust agents that can recover from failures +- Use **class-based tools** when you need to maintain state or dynamically adjust tool behavior at runtime + +## Running the Examples + +Each example is a standalone Python script that can be run directly: + +```bash +uv run python ai_function_with_approval.py +``` + +Make sure you have the necessary environment variables configured (like `OPENAI_API_KEY` or Azure credentials) before running the examples. diff --git a/python/samples/getting_started/tools/ai_function_declaration_only.py b/python/samples/getting_started/tools/ai_function_declaration_only.py new file mode 100644 index 0000000000..03a2e8f8ed --- /dev/null +++ b/python/samples/getting_started/tools/ai_function_declaration_only.py @@ -0,0 +1,75 @@ +# Copyright (c) Microsoft. All rights reserved. + +from agent_framework import AIFunction +from agent_framework.openai import OpenAIResponsesClient + +""" +Example of how to create a function that only consists of a declaration without an implementation. +This is useful when you want the agent to use tools that are defined elsewhere or when you want +to test the agent's ability to reason about tool usage without executing them. + +The only difference is that you provide an AIFunction without a function. +If you need a input_model, you can still provide that as well. +""" + + +async def main(): + function_declaration = AIFunction[None, None]( + name="get_current_time", + description="Get the current time in ISO 8601 format.", + ) + + agent = OpenAIResponsesClient().create_agent( + name="DeclarationOnlyToolAgent", + instructions="You are a helpful agent that uses tools.", + tools=function_declaration, + ) + query = "What is the current time?" + print(f"User: {query}") + result = await agent.run(query) + print(f"Result: {result.to_json(indent=2)}\n") + + +""" +Expected result: +User: What is the current time? +Result: { + "type": "agent_run_response", + "messages": [ + { + "type": "chat_message", + "role": { + "type": "role", + "value": "assistant" + }, + "contents": [ + { + "type": "function_call", + "call_id": "call_0flN9rfGLK8LhORy4uMDiRSC", + "name": "get_current_time", + "arguments": "{}", + "fc_id": "fc_0fd5f269955c589f016904c46584348195b84a8736e61248de" + } + ], + "author_name": "DeclarationOnlyToolAgent", + "additional_properties": {} + } + ], + "response_id": "resp_0fd5f269955c589f016904c462d5cc819599d28384ba067edc", + "created_at": "2025-10-31T15:14:58.000000Z", + "usage_details": { + "type": "usage_details", + "input_token_count": 63, + "output_token_count": 145, + "total_token_count": 208, + "openai.reasoning_tokens": 128 + }, + "additional_properties": {} +} +""" + + +if __name__ == "__main__": + import asyncio + + asyncio.run(main()) diff --git a/python/samples/getting_started/tools/tool_with_injected_func.py b/python/samples/getting_started/tools/ai_function_from_dict_with_dependency_injection.py similarity index 100% rename from python/samples/getting_started/tools/tool_with_injected_func.py rename to python/samples/getting_started/tools/ai_function_from_dict_with_dependency_injection.py diff --git a/python/samples/getting_started/tools/failing_tools.py b/python/samples/getting_started/tools/ai_function_recover_from_failures.py similarity index 100% rename from python/samples/getting_started/tools/failing_tools.py rename to python/samples/getting_started/tools/ai_function_recover_from_failures.py diff --git a/python/samples/getting_started/tools/ai_tool_with_approval.py b/python/samples/getting_started/tools/ai_function_with_approval.py similarity index 100% rename from python/samples/getting_started/tools/ai_tool_with_approval.py rename to python/samples/getting_started/tools/ai_function_with_approval.py diff --git a/python/samples/getting_started/tools/ai_tool_with_approval_and_threads.py b/python/samples/getting_started/tools/ai_function_with_approval_and_threads.py similarity index 100% rename from python/samples/getting_started/tools/ai_tool_with_approval_and_threads.py rename to python/samples/getting_started/tools/ai_function_with_approval_and_threads.py diff --git a/python/samples/getting_started/tools/ai_function_with_max_exceptions.py b/python/samples/getting_started/tools/ai_function_with_max_exceptions.py new file mode 100644 index 0000000000..b1600b7299 --- /dev/null +++ b/python/samples/getting_started/tools/ai_function_with_max_exceptions.py @@ -0,0 +1,188 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import Annotated + +from agent_framework import FunctionCallContent, FunctionResultContent, ai_function +from agent_framework.openai import OpenAIResponsesClient + +""" +Some tools are very expensive to run, so you may want to limit the number of times +it tries to call them and fails. This sample shows a tool that can only raise exceptions a +limited number of times. +""" + + +# we trick the AI into calling this function with 0 as denominator to trigger the exception +@ai_function(max_invocation_exceptions=1) +def safe_divide( + a: Annotated[int, "Numerator"], + b: Annotated[int, "Denominator"], +) -> str: + """Divide two numbers can be used with 0 as denominator.""" + try: + result = a / b # Will raise ZeroDivisionError + except ZeroDivisionError as exc: + print(f" Tool failed with error: {exc}") + raise + + return f"{a} / {b} = {result}" + + +async def main(): + # tools = Tools() + agent = OpenAIResponsesClient().create_agent( + name="ToolAgent", + instructions="Use the provided tools.", + tools=[safe_divide], + ) + thread = agent.get_new_thread() + print("=" * 60) + print("Step 1: Call divide(10, 0) - tool raises exception") + response = await agent.run("Divide 10 by 0", thread=thread) + print(f"Response: {response.text}") + print("=" * 60) + print("Step 2: Call divide(100, 0) - will refuse to execute due to max_invocation_exceptions") + response = await agent.run("Divide 100 by 0", thread=thread) + print(f"Response: {response.text}") + print("=" * 60) + print(f"Number of tool calls attempted: {safe_divide.invocation_count}") + print(f"Number of tool calls failed: {safe_divide.invocation_exception_count}") + print("Replay the conversation:") + assert thread.message_store + assert thread.message_store.list_messages + for idx, msg in enumerate(await thread.message_store.list_messages()): + if msg.text: + print(f"{idx + 1} {msg.author_name or msg.role}: {msg.text} ") + for content in msg.contents: + if isinstance(content, FunctionCallContent): + print( + f"{idx + 1} {msg.author_name}: calling function: {content.name} with arguments: {content.arguments}" + ) + if isinstance(content, FunctionResultContent): + print(f"{idx + 1} {msg.role}: {content.result if content.result else content.exception}") + + +""" +Expected Output: +============================================================ +Step 1: Call divide(10, 0) - tool raises exception + Tool failed with error: division by zero +[2025-10-31 15:39:53 - /Users/edvan/Work/agent-framework/python/packages/core/agent_framework/_tools.py:718 - ERROR] +Function failed. Error: division by zero +Response: Division by zero is undefined in standard arithmetic. There is no finite value for 10 ÷ 0. + +If you want alternatives: +- A valid example: 10 ÷ 2 = 5. +- To handle safely in code, you can check the denominator first (e.g., in Python: if b == 0: + handle error else: compute a/b). +- If you’re curious about limits: as x → 0+, 10/x → +∞; as x → 0−, 10/x → −∞; there is no finite limit. + +Would you like me to show a safe division snippet in a specific language, or compute something else? +============================================================ +Step 2: Call divide(100, 0) - will refuse to execute due to max_invocations +[2025-10-31 15:40:09 - /Users/edvan/Work/agent-framework/python/packages/core/agent_framework/_tools.py:718 - ERROR] +Function failed. Error: Function 'safe_divide' has reached its maximum exception limit, you tried to use this +tool too many times and it kept failing. +Response: Division by zero is undefined in standard arithmetic, so 100 ÷ 0 has no finite value. + +If you’re coding and want safe handling, here are quick patterns in a few languages: + +- Python + def safe_divide(a, b): + if b == 0: + return None # or raise an exception + return a / b + + safe_divide(100, 0) # -> None + +- JavaScript + function safeDivide(a, b) { + if (b === 0) return undefined; // or throw + return a / b; + } + + safeDivide(100, 0) // -> undefined + +- Java + public static Double safeDivide(double a, double b) { + if (b == 0.0) throw new ArithmeticException("Divide by zero"); + return a / b; + } + + safeDivide(100, 0) // -> exception + +- C/C++ + double safeDivide(double a, double b) { + if (b == 0.0) return std::numeric_limits::infinity(); // or handle error + return a / b; + } + +Note: In many languages, dividing by zero with floating-point numbers yields Infinity (or -Infinity) or NaN, +but integer division typically raises an error. + +Would you like a snippet in a specific language or to see a math explanation (limits) for what happens as the +divisor approaches zero? +============================================================ +Number of tool calls attempted: 1 +Number of tool calls failed: 1 +Replay the conversation: +1 user: Divide 10 by 0 +2 ToolAgent: calling function: safe_divide with arguments: {"a":10,"b":0} +3 tool: division by zero +4 ToolAgent: Division by zero is undefined in standard arithmetic. There is no finite value for 10 ÷ 0. + +If you want alternatives: +- A valid example: 10 ÷ 2 = 5. +- To handle safely in code, you can check the denominator first (e.g., in Python: if b == 0: + handle error else: compute a/b). +- If you’re curious about limits: as x → 0+, 10/x → +∞; as x → 0−, 10/x → −∞; there is no finite limit. + +Would you like me to show a safe division snippet in a specific language, or compute something else? +5 user: Divide 100 by 0 +6 ToolAgent: calling function: safe_divide with arguments: {"a":100,"b":0} +7 tool: Function 'safe_divide' has reached its maximum exception limit, you tried to use this tool too many times + and it kept failing. +8 ToolAgent: Division by zero is undefined in standard arithmetic, so 100 ÷ 0 has no finite value. + +If you’re coding and want safe handling, here are quick patterns in a few languages: + +- Python + def safe_divide(a, b): + if b == 0: + return None # or raise an exception + return a / b + + safe_divide(100, 0) # -> None + +- JavaScript + function safeDivide(a, b) { + if (b === 0) return undefined; // or throw + return a / b; + } + + safeDivide(100, 0) // -> undefined + +- Java + public static Double safeDivide(double a, double b) { + if (b == 0.0) throw new ArithmeticException("Divide by zero"); + return a / b; + } + + safeDivide(100, 0) // -> exception + +- C/C++ + double safeDivide(double a, double b) { + if (b == 0.0) return std::numeric_limits::infinity(); // or handle error + return a / b; + } + +Note: In many languages, dividing by zero with floating-point numbers yields Infinity (or -Infinity) or NaN, +but integer division typically raises an error. + +Would you like a snippet in a specific language or to see a math explanation (limits) for what happens as the +divisor approaches zero? +""" + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/getting_started/tools/ai_function_with_max_invocations.py b/python/samples/getting_started/tools/ai_function_with_max_invocations.py new file mode 100644 index 0000000000..6a52e91329 --- /dev/null +++ b/python/samples/getting_started/tools/ai_function_with_max_invocations.py @@ -0,0 +1,89 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import Annotated + +from agent_framework import FunctionCallContent, FunctionResultContent, ai_function +from agent_framework.openai import OpenAIResponsesClient + +""" +For tools you can specify if there is a maximum number of invocations allowed. +This sample shows a tool that can only be invoked once. +""" + + +@ai_function(max_invocations=1) +def unicorn_function(times: Annotated[int, "The number of unicorns to return."]) -> str: + """This function returns precious unicorns!""" + return f"{'🦄' * times}✨" + + +async def main(): + # tools = Tools() + agent = OpenAIResponsesClient().create_agent( + name="ToolAgent", + instructions="Use the provided tools.", + tools=[unicorn_function], + ) + thread = agent.get_new_thread() + print("=" * 60) + print("Step 1: Call unicorn_function") + response = await agent.run("Call 5 unicorns!", thread=thread) + print(f"Response: {response.text}") + print("=" * 60) + print("Step 2: Call unicorn_function again - will refuse to execute due to max_invocations") + response = await agent.run("Call 10 unicorns and use the function to do it.", thread=thread) + print(f"Response: {response.text}") + print("=" * 60) + print(f"Number of tool calls attempted: {unicorn_function.invocation_count}") + print(f"Number of tool calls failed: {unicorn_function.invocation_exception_count}") + print("Replay the conversation:") + assert thread.message_store + assert thread.message_store.list_messages + for idx, msg in enumerate(await thread.message_store.list_messages()): + if msg.text: + print(f"{idx + 1} {msg.author_name or msg.role}: {msg.text} ") + for content in msg.contents: + if isinstance(content, FunctionCallContent): + print( + f"{idx + 1} {msg.author_name}: calling function: {content.name} with arguments: {content.arguments}" + ) + if isinstance(content, FunctionResultContent): + print(f"{idx + 1} {msg.role}: {content.result if content.result else content.exception}") + + +""" +Expected Output: +============================================================ +Step 1: Call unicorn_function +Response: Five unicorns summoned: 🦄🦄🦄🦄🦄✨ +============================================================ +Step 2: Call unicorn_function again - will refuse to execute due to max_invocations +[2025-10-31 15:54:40 - /Users/edvan/Work/agent-framework/python/packages/core/agent_framework/_tools.py:718 - ERROR] +Function failed. Error: Function 'unicorn_function' has reached its maximum invocation limit, +you can no longer use this tool. +Response: The unicorn function has reached its maximum invocation limit. I can’t call it again right now. + +Here are 10 unicorns manually: 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 + +Would you like me to try again later, or generate something else? +============================================================ +Number of tool calls attempted: 1 +Number of tool calls failed: 0 +Replay the conversation: +1 user: Call 5 unicorns! +2 ToolAgent: calling function: unicorn_function with arguments: {"times":5} +3 tool: 🦄🦄🦄🦄🦄✨ +4 ToolAgent: Five unicorns summoned: 🦄🦄🦄🦄🦄✨ +5 user: Call 10 unicorns and use the function to do it. +6 ToolAgent: calling function: unicorn_function with arguments: {"times":10} +7 tool: Function 'unicorn_function' has reached its maximum invocation limit, you can no longer use this tool. +8 ToolAgent: The unicorn function has reached its maximum invocation limit. I can’t call it again right now. + +Here are 10 unicorns manually: 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 🦄 + +Would you like me to try again later, or generate something else? +""" + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/getting_started/tools/ai_functions_in_class.py b/python/samples/getting_started/tools/ai_functions_in_class.py new file mode 100644 index 0000000000..995383cc70 --- /dev/null +++ b/python/samples/getting_started/tools/ai_functions_in_class.py @@ -0,0 +1,100 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import Annotated + +from agent_framework import ai_function +from agent_framework.openai import OpenAIResponsesClient + +""" +This sample demonstrates using ai_function within a class, +showing how to manage state within the class that affects tool behavior. + +And how to use ai_function-decorated methods as tools in an agent in order to adjust the behavior of a tool. +""" + + +class MyFunctionClass: + def __init__(self, safe: bool = False) -> None: + """Simple class with two ai_functions: divide and add. + + The safe parameter controls whether divide raises on division by zero or returns `infinity` for divide by zero. + """ + self.safe = safe + + def divide( + self, + a: Annotated[int, "Numerator"], + b: Annotated[int, "Denominator"], + ) -> str: + """Divide two numbers, safe to use also with 0 as denominator.""" + result = "∞" if b == 0 and self.safe else a / b + return f"{a} / {b} = {result}" + + def add( + self, + x: Annotated[int, "First number"], + y: Annotated[int, "Second number"], + ) -> str: + return f"{x} + {y} = {x + y}" + + +async def main(): + # Creating my function class with safe division enabled + tools = MyFunctionClass(safe=True) + # Applying the ai_function decorator to one of the methods of the class + add_function = ai_function(description="Add two numbers.")(tools.add) + + agent = OpenAIResponsesClient().create_agent( + name="ToolAgent", + instructions="Use the provided tools.", + ) + print("=" * 60) + print("Step 1: Call divide(10, 0) - tool returns infinity") + query = "Divide 10 by 0" + response = await agent.run( + query, + tools=[add_function, tools.divide], + ) + print(f"Response: {response.text}") + print("=" * 60) + print("Step 2: Call set safe to False and call again") + # Disabling safe mode to allow exceptions + tools.safe = False + response = await agent.run(query, tools=[add_function, tools.divide]) + print(f"Response: {response.text}") + print("=" * 60) + + +""" +Expected Output: +============================================================ +Step 1: Call divide(10, 0) - tool returns infinity +Response: Division by zero is undefined in standard arithmetic. There is no real number that equals 10 divided by 0. + +- If you look at limits: as x → 0+ (denominator approaches 0 from the positive side), 10/x → +∞; as x → 0−, 10/x → −∞. +- Some calculators may display "infinity" or give an error, but that's not a real number. + +If you want a numeric surrogate, you can use a small nonzero denominator, e.g., 10/0.001 = 10000. Would you like to +see more on limits or handle it with a tiny epsilon? +============================================================ +Step 2: Call set safe to False and call again +[2025-10-31 16:17:44 - /Users/edvan/Work/agent-framework/python/packages/core/agent_framework/_tools.py:718 - ERROR] +Function failed. Error: division by zero +Response: Division by zero is undefined in standard arithmetic. There is no number y such that 0 × y = 10. + +If you’re looking at limits: +- as x → 0+, 10/x → +∞ +- as x → 0−, 10/x → −∞ +So the limit does not exist. + +In programming, dividing by zero usually raises an error or results in special values (e.g., NaN or ∞) depending +on the language. + +If you want, tell me what you’d like to do instead (e.g., compute 10 divided by 2, or handle division by zero safely +in code), and I can help with examples. +============================================================ +""" + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/getting_started/tools/function_invocation_configuration.py b/python/samples/getting_started/tools/function_invocation_configuration.py new file mode 100644 index 0000000000..bb0e6b0798 --- /dev/null +++ b/python/samples/getting_started/tools/function_invocation_configuration.py @@ -0,0 +1,58 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import Annotated + +from agent_framework.openai import OpenAIResponsesClient + +""" +This sample demonstrates how to configure function invocation settings +for an client and use a simple ai_function as a tool in an agent. + +This behavior is the same for all chat client types. +""" + + +def add( + x: Annotated[int, "First number"], + y: Annotated[int, "Second number"], +) -> str: + return f"{x} + {y} = {x + y}" + + +async def main(): + client = OpenAIResponsesClient() + if client.function_invocation_configuration is not None: + client.function_invocation_configuration.include_detailed_errors = True + client.function_invocation_configuration.max_iterations = 40 + print(f"Function invocation configured as: \n{client.function_invocation_configuration.to_json(indent=2)}") + + agent = client.create_agent(name="ToolAgent", instructions="Use the provided tools.", tools=add) + + print("=" * 60) + print("Call add(239847293, 29834)") + query = "Add 239847293 and 29834" + response = await agent.run(query) + print(f"Response: {response.text}") + + +""" +Expected Output: +============================================================ +Function invocation configured as: +{ + "type": "function_invocation_configuration", + "enabled": true, + "max_iterations": 40, + "max_consecutive_errors_per_request": 3, + "terminate_on_unknown_calls": false, + "additional_tools": [], + "include_detailed_errors": true +} +============================================================ +Call add(239847293, 29834) +Response: 239,877,127 +""" + +if __name__ == "__main__": + asyncio.run(main())