From 4fabb35b7da012a21cc102d56df5816325ef3f9a Mon Sep 17 00:00:00 2001 From: barry <91018388+barry166@users.noreply.github.com> Date: Fri, 2 Oct 2026 00:13:29 +0800 Subject: [PATCH 1/4] Python: preserve method tool invocation limits --- .../packages/core/agent_framework/_tools.py | 22 ++++++++---- python/packages/core/tests/core/test_tools.py | 35 +++++++++++++++++++ 2 files changed, 50 insertions(+), 7 deletions(-) diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 602da9dc4cb..f50460f5d74 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -12,6 +12,7 @@ import sys import typing import warnings +import weakref from collections import deque from collections.abc import ( AsyncIterable, @@ -95,6 +96,8 @@ logger = logging.getLogger("agent_framework") +_BOUND_TOOL_CACHE: weakref.WeakKeyDictionary[Any, weakref.WeakKeyDictionary[Any, Any]] = weakref.WeakKeyDictionary() + def _generate_function_call_occurrence_id() -> str: """Generate an Agent Framework identity for one function-call occurrence.""" @@ -730,7 +733,7 @@ def __get__(self, obj: Any, objtype: type | None = None) -> FunctionTool: objtype: The type that owns the descriptor. Returns: - A new FunctionTool with the instance bound to the wrapped function. + A FunctionTool with the instance bound to the wrapped function. """ if obj is None: # Accessed from the class, not an instance @@ -741,12 +744,17 @@ def __get__(self, obj: Any, objtype: type | None = None) -> FunctionTool: sig = inspect.signature(self.func) params = list(sig.parameters.keys()) if params and params[0] in {"self", "cls"}: - # Create a new FunctionTool with the bound method - import copy - - bound_func = copy.copy(self) - bound_func._instance = obj - return bound_func + try: + bound_tools = _BOUND_TOOL_CACHE[self] + except KeyError: + bound_tools = _BOUND_TOOL_CACHE[self] = weakref.WeakKeyDictionary() + try: + return bound_tools[obj] + except KeyError: + bound_func = copy.copy(self) + bound_func._instance = obj + bound_tools[obj] = bound_func + return bound_func return self diff --git a/python/packages/core/tests/core/test_tools.py b/python/packages/core/tests/core/test_tools.py index 3071e191513..14cc19f63f0 100644 --- a/python/packages/core/tests/core/test_tools.py +++ b/python/packages/core/tests/core/test_tools.py @@ -709,6 +709,41 @@ def test_tool(self, x: int, y: int) -> int: assert test_tool(1, 2) == 3 +async def test_method_tool_max_invocations_persists_across_attribute_access() -> None: + """Method tool invocation limits apply across repeated attribute access.""" + from agent_framework.exceptions import ToolException + + class Tools: + @tool(max_invocations=1) + def ping(self) -> str: + return "pong" + + tools = Tools() + + assert await tools.ping.invoke(skip_parsing=True) == "pong" + assert tools.ping.invocation_count == 1 + with pytest.raises(ToolException, match="maximum invocation limit"): + await tools.ping.invoke(skip_parsing=True) + + +async def test_method_tool_max_invocation_exceptions_persists_across_attribute_access() -> None: + """Method tool exception limits apply across repeated attribute access.""" + from agent_framework.exceptions import ToolException + + class Tools: + @tool(max_invocation_exceptions=1) + def fail(self) -> None: + raise RuntimeError("boom") + + tools = Tools() + + with pytest.raises(RuntimeError, match="boom"): + await tools.fail.invoke(skip_parsing=True) + assert tools.fail.invocation_exception_count == 1 + with pytest.raises(ToolException, match="maximum exception limit"): + await tools.fail.invoke(skip_parsing=True) + + def test_tool_with_literal_type_parameter(): """Test tool decorator with Literal type parameter (issue #2891).""" From 556da45b33b8b2a6070f871fa4fbad949ec93b79 Mon Sep 17 00:00:00 2001 From: barry <91018388+barry166@users.noreply.github.com> Date: Fri, 9 Oct 2026 14:52:10 +0800 Subject: [PATCH 2/4] Fix method tool caching for valid owner types and serialization Keep bound tools on their owner so unhashable and equal instances remain isolated and the cache does not retain owners globally. Recreate runtime bindings after pickle or copying, and preserve slots-only compatibility. Tested: 590 related tests passed, 1 skipped; Ruff and Pyright passed Constraint: Slots-only owners must retain the returned tool for persistent limits --- .../packages/core/agent_framework/_tools.py | 49 +++-- python/packages/core/tests/core/test_tools.py | 168 ++++++++++++++++++ 2 files changed, 202 insertions(+), 15 deletions(-) diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index f50460f5d74..d412ab8fcb4 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -12,7 +12,6 @@ import sys import typing import warnings -import weakref from collections import deque from collections.abc import ( AsyncIterable, @@ -96,8 +95,6 @@ logger = logging.getLogger("agent_framework") -_BOUND_TOOL_CACHE: weakref.WeakKeyDictionary[Any, weakref.WeakKeyDictionary[Any, Any]] = weakref.WeakKeyDictionary() - def _generate_function_call_occurrence_id() -> str: """Generate an Agent Framework identity for one function-call occurrence.""" @@ -498,6 +495,21 @@ def _format_tool_parameters( # pyright: ignore[reportUnusedFunction] ClassT = TypeVar("ClassT", bound="SerializationMixin") +class _BoundToolCache: + """Keep bound tools on their owner without serializing runtime bindings.""" + + def __init__(self, owner: Any = None) -> None: + self.owner = owner + self.tools: dict[FunctionTool, FunctionTool] = {} + + def __reduce__(self) -> tuple[type[_BoundToolCache], tuple[()]]: + return type(self), () + + def to_dict(self) -> dict[str, Any]: + """Exclude runtime bindings when the owner is converted to JSON.""" + return {} + + class FunctionTool(SerializationMixin): """A tool that wraps a Python function to make it callable by AI models. @@ -726,7 +738,9 @@ def __get__(self, obj: Any, objtype: type | None = None) -> FunctionTool: """Implement the descriptor protocol to support bound methods. When a FunctionTool is accessed as an attribute of a class instance, - this method is called to bind the instance to the function. + this method is called to bind the instance to the function. Instances + with a ``__dict__`` cache their bound tools across attribute accesses. + For slots-only instances, retain the returned tool to preserve its counters. Args: obj: The instance that owns the descriptor, or None for class access. @@ -744,17 +758,22 @@ def __get__(self, obj: Any, objtype: type | None = None) -> FunctionTool: sig = inspect.signature(self.func) params = list(sig.parameters.keys()) if params and params[0] in {"self", "cls"}: - try: - bound_tools = _BOUND_TOOL_CACHE[self] - except KeyError: - bound_tools = _BOUND_TOOL_CACHE[self] = weakref.WeakKeyDictionary() - try: - return bound_tools[obj] - except KeyError: - bound_func = copy.copy(self) - bound_func._instance = obj - bound_tools[obj] = bound_func - return bound_func + instance_dict: dict[str, Any] | None = getattr(obj, "__dict__", None) + if isinstance(instance_dict, dict): + cache = instance_dict.get("_agent_framework_bound_tools") + # A shallow-copied owner must not reuse the original owner's bindings. + if not isinstance(cache, _BoundToolCache) or cache.owner is not obj: + cache = instance_dict["_agent_framework_bound_tools"] = _BoundToolCache(obj) + if self not in cache.tools: + bound_func = copy.copy(self) + bound_func._instance = obj + cache.tools[self] = bound_func + return cache.tools[self] + + # shortcut: slots-only owners cannot store bindings; retain the returned tool for persistent limits. + bound_func = copy.copy(self) + bound_func._instance = obj + return bound_func return self diff --git a/python/packages/core/tests/core/test_tools.py b/python/packages/core/tests/core/test_tools.py index 14cc19f63f0..b2544cfbd14 100644 --- a/python/packages/core/tests/core/test_tools.py +++ b/python/packages/core/tests/core/test_tools.py @@ -1,9 +1,13 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio import copy +import gc import logging +import pickle import threading +import weakref from contextvars import ContextVar +from dataclasses import dataclass, field from typing import Annotated, Any, Literal, get_args, get_origin from unittest.mock import Mock @@ -709,6 +713,16 @@ def test_tool(self, x: int, y: int) -> int: assert test_tool(1, 2) == 3 +def _pickleable_tool_value(self: Any) -> str: + return self.value + + +@dataclass(eq=False) +class _PickleableToolOwner: + value: str = "pong" + ping = FunctionTool(name="ping", func=_pickleable_tool_value, input_model={}, max_invocations=1) + + async def test_method_tool_max_invocations_persists_across_attribute_access() -> None: """Method tool invocation limits apply across repeated attribute access.""" from agent_framework.exceptions import ToolException @@ -744,6 +758,160 @@ def fail(self) -> None: await tools.fail.invoke(skip_parsing=True) +@pytest.mark.parametrize("hashable", [False, True]) +async def test_method_tool_equal_owners_have_independent_limits(hashable: bool) -> None: + from agent_framework.exceptions import ToolException + + @dataclass(unsafe_hash=hashable) # type: ignore[misc] + class Tools: + value: str = field(compare=False) + + @tool(max_invocations=1) + def ping(self) -> str: + return self.value + + first, second = Tools("first"), Tools("second") + assert first == second + assert first.ping is first.ping + assert first.ping is not second.ping + assert await first.ping.invoke(skip_parsing=True) == "first" + assert await second.ping.invoke(skip_parsing=True) == "second" + for owner in (first, second): + with pytest.raises(ToolException, match="maximum invocation limit"): + await owner.ping.invoke(skip_parsing=True) + + +@pytest.mark.parametrize("has_dict", [False, True]) +async def test_method_tool_owner_without_weakref_support(has_dict: bool) -> None: + from agent_framework.exceptions import ToolException + + class Tools: + __slots__ = ("__dict__",) if has_dict else () + + @tool(max_invocations=1) + def ping(self) -> str: + return "pong" + + owner = Tools() + with pytest.raises(TypeError): + weakref.ref(owner) + bound_tool = owner.ping + assert await bound_tool.invoke(skip_parsing=True) == "pong" + if has_dict: + assert owner.ping is bound_tool + with pytest.raises(ToolException, match="maximum invocation limit"): + await bound_tool.invoke(skip_parsing=True) + + +def test_method_tool_cache_releases_owner() -> None: + owner = _PickleableToolOwner() + owner_ref = weakref.ref(owner) + assert owner.ping is owner.ping + + del owner + gc.collect() + + assert owner_ref() is None + + +def test_method_tool_owner_json_serialization_excludes_bindings() -> None: + from agent_framework._serialization import make_json_safe + + class Tools: + def __init__(self) -> None: + self.value = "pong" + + @tool + def ping(self) -> str: + return self.value + + owner = Tools() + assert owner.ping() == "pong" + assert make_json_safe(owner) == {"value": "pong", "_agent_framework_bound_tools": {}} + + +async def test_retained_method_tool_keeps_owner_alive() -> None: + owner = _PickleableToolOwner() + owner_ref = weakref.ref(owner) + bound_tool = owner.ping + del owner + gc.collect() + + assert owner_ref() is not None + assert await bound_tool.invoke(skip_parsing=True) == "pong" + + del bound_tool + gc.collect() + assert owner_ref() is None + + +@pytest.mark.parametrize("copy_owner", [copy.copy, copy.deepcopy]) +async def test_method_tool_copied_owner_rebinds(copy_owner) -> None: + from agent_framework.exceptions import ToolException + + original = _PickleableToolOwner("original") + assert await original.ping.invoke(skip_parsing=True) == "original" + + copied = copy_owner(original) + copied.value = "copied" + assert copied.ping is not original.ping + assert copied.ping is copied.ping + assert await copied.ping.invoke(skip_parsing=True) == "copied" + with pytest.raises(ToolException, match="maximum invocation limit"): + await original.ping.invoke(skip_parsing=True) + with pytest.raises(ToolException, match="maximum invocation limit"): + await copied.ping.invoke(skip_parsing=True) + + +@pytest.mark.parametrize("bind_first", [False, True]) +async def test_function_tool_pickle_after_descriptor_access(bind_first: bool) -> None: + descriptor = FunctionTool(name="ping", func=_pickleable_tool_value, input_model={}, max_invocations=1) + owner = _PickleableToolOwner() + if bind_first: + assert await descriptor.__get__(owner).invoke(skip_parsing=True) == "pong" + + restored = pickle.loads(pickle.dumps(descriptor)) + + assert restored.name == descriptor.name + assert await restored.__get__(owner).invoke(skip_parsing=True) == "pong" + + +async def test_bound_function_tool_pickle_preserves_owner_and_count() -> None: + from agent_framework.exceptions import ToolException + + descriptor = FunctionTool(name="ping", func=_pickleable_tool_value, input_model={}, max_invocations=2) + owner = _PickleableToolOwner("original") + bound_tool = descriptor.__get__(owner) + assert await bound_tool.invoke(skip_parsing=True) == "original" + + restored = pickle.loads(pickle.dumps(bound_tool)) + owner.value = "changed" + + assert restored.invocation_count == 1 + assert await restored.invoke(skip_parsing=True) == "original" + assert restored.invocation_count == 2 + assert bound_tool.invocation_count == 1 + with pytest.raises(ToolException, match="maximum invocation limit"): + await restored.invoke(skip_parsing=True) + + +async def test_method_tool_pickled_owner_rebuilds_cache() -> None: + from agent_framework.exceptions import ToolException + + original = _PickleableToolOwner("original") + assert await original.ping.invoke(skip_parsing=True) == "original" + + restored = pickle.loads(pickle.dumps(original)) + restored.value = "restored" + + assert restored.ping is restored.ping + assert await restored.ping.invoke(skip_parsing=True) == "restored" + with pytest.raises(ToolException, match="maximum invocation limit"): + await original.ping.invoke(skip_parsing=True) + with pytest.raises(ToolException, match="maximum invocation limit"): + await restored.ping.invoke(skip_parsing=True) + + def test_tool_with_literal_type_parameter(): """Test tool decorator with Literal type parameter (issue #2891).""" From 00338c8bea9d3a6c3bad14f7ddda6d19db9218cd Mon Sep 17 00:00:00 2001 From: barry <91018388+barry166@users.noreply.github.com> Date: Fri, 23 Oct 2026 09:03:03 +0800 Subject: [PATCH 3/4] Preserve owner state when the method-tool cache name collides Fail explicitly before replacing an existing non-cache attribute, including None and empty dictionaries. Tested: 170 tool tests; Pyright 1.1.414; Ruff 0.16.7 lint and format Constraint: Ruff 0.17.0 was unavailable in the offline tool cache Scope-risk: narrow --- .../packages/core/agent_framework/_tools.py | 9 +++++++++ python/packages/core/tests/core/test_tools.py | 19 +++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 705d7eb5ce5..8cbd8451739 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -842,6 +842,10 @@ def __get__(self, obj: Any, objtype: type | None = None) -> FunctionTool: Returns: A FunctionTool with the instance bound to the wrapped function. + + Raises: + ValueError: If the instance already stores a non-cache value in + ``_agent_framework_bound_tools``. """ if obj is None: # Accessed from the class, not an instance @@ -855,6 +859,11 @@ def __get__(self, obj: Any, objtype: type | None = None) -> FunctionTool: instance_dict: dict[str, Any] | None = getattr(obj, "__dict__", None) if isinstance(instance_dict, dict): cache = instance_dict.get("_agent_framework_bound_tools") + if "_agent_framework_bound_tools" in instance_dict and not isinstance(cache, _BoundToolCache): + raise ValueError( + "Cannot cache bound tools: '_agent_framework_bound_tools' is already in use. " + "Rename the existing instance attribute to use method tools." + ) # A shallow-copied owner must not reuse the original owner's bindings. if not isinstance(cache, _BoundToolCache) or cache.owner is not obj: cache = instance_dict["_agent_framework_bound_tools"] = _BoundToolCache(obj) diff --git a/python/packages/core/tests/core/test_tools.py b/python/packages/core/tests/core/test_tools.py index f213e5a8a9e..95ea3a8b158 100644 --- a/python/packages/core/tests/core/test_tools.py +++ b/python/packages/core/tests/core/test_tools.py @@ -893,6 +893,25 @@ def ping(self) -> str: await bound_tool.invoke(skip_parsing=True) +@pytest.mark.parametrize("existing_value", [None, {}, {"application_state": "keep"}, "keep"]) +def test_method_tool_cache_preserves_existing_owner_attribute(existing_value: Any) -> None: + class Tools: + def __init__(self) -> None: + self._agent_framework_bound_tools = existing_value + + @tool + def ping(self) -> str: + return "pong" + + owner = Tools() + + with pytest.raises(ValueError, match="_agent_framework_bound_tools"): + owner.ping() + + assert owner._agent_framework_bound_tools is existing_value + assert vars(owner) == {"_agent_framework_bound_tools": existing_value} + + def test_method_tool_cache_releases_owner() -> None: owner = _PickleableToolOwner() owner_ref = weakref.ref(owner) From b8d448090f6e6783725d26141c431e22dc1a2a6a Mon Sep 17 00:00:00 2001 From: barry <91018388+barry166@users.noreply.github.com> Date: Sat, 7 Nov 2026 15:17:45 +0800 Subject: [PATCH 4/4] Resolve conflicts with main --- .../packages/core/agent_framework/_tools.py | 213 ++++++++++++--- python/packages/core/tests/core/test_tools.py | 258 +++++++++++++++++- 2 files changed, 420 insertions(+), 51 deletions(-) diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 8cbd8451739..c7fe0130025 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -17,11 +17,12 @@ AsyncIterable, Awaitable, Callable, + Generator, Iterable, Mapping, Sequence, ) -from contextlib import suppress +from contextlib import contextmanager, suppress from dataclasses import dataclass from datetime import date, datetime, timedelta, timezone, tzinfo from datetime import time as datetime_time @@ -47,6 +48,7 @@ from opentelemetry import trace from opentelemetry.metrics import Histogram, NoOpHistogram +from opentelemetry.util.types import AttributeValue from pydantic import BaseModel, Field, TypeAdapter, ValidationError, create_model from pydantic_core import to_jsonable_python @@ -108,6 +110,7 @@ def _generate_function_call_occurrence_id() -> str: DEFAULT_MAX_ITERATIONS: Final[int] = 40 DEFAULT_MAX_CONSECUTIVE_ERRORS_PER_REQUEST: Final[int] = 3 SHELL_TOOL_KIND_VALUE: Final[str] = "shell" +_LOCAL_TOOL_RESULT_KEY: Final[str] = "agent_framework.local_tool_result" _TOOL_APPROVAL_STATE_KEY: Final[str] = "tool_approval" _APPROVAL_SESSION_IS_AUTHORITATIVE_KEY: Final[str] = "_approval_session_is_authoritative" _PARENT_TOOL_APPROVAL_SOURCE_IDS_CONTEXT_KEY: Final[str] = "_parent_tool_approval_source_ids" @@ -137,12 +140,25 @@ def _has_authoritative_approval_session(invocation_session: AgentSession | None) _SECURITY_ARGUMENTS_SNAPSHOT_CONTEXT_KEY: Final[str] = "_security_function_arguments" _PREPARED_ARGUMENTS_CONTEXT_KEY: Final[str] = "_prepared_function_arguments" _AUTO_ARGUMENT_PREPARATION_CONTEXT_KEY: Final[str] = "_auto_prepare_function_arguments" +_SECURITY_ARGUMENT_MATERIALIZATION_CONTEXT: Final[ + contextvars.ContextVar[tuple[Any, Callable[[Any], None], asyncio.Task[Any] | None] | None] +] = contextvars.ContextVar("agent_framework_core_security_argument_materialization_context", default=None) _FUNCTION_INVOCATION_LIMIT_FALLBACK_TEXT: Final[str] = ( "Function invocation limit reached before a final answer could be produced." ) _USER_VISIBLE_CONTENT_TYPES: Final[set[str]] = {"data", "uri", "error", "hosted_file", "hosted_vector_store"} +@contextmanager +def _suspend_security_argument_materialization() -> Generator[None]: + """Prevent nested tool calls from inheriting one invocation's materialization capability.""" + token = _SECURITY_ARGUMENT_MATERIALIZATION_CONTEXT.set(None) + try: + yield + finally: + _SECURITY_ARGUMENT_MATERIALIZATION_CONTEXT.reset(token) + + class _FunctionArgumentValidationError(TypeError): """An argument-validation failure raised before the function body starts.""" @@ -415,9 +431,7 @@ def _parse_inputs( # pyright: ignore[reportUnusedFunction] if inputs is None: return [] - from ._types import ( - Content, - ) + from ._types import Content parsed_inputs: list[Content] = [] if not isinstance(inputs, list): @@ -524,6 +538,28 @@ def _normalize_tool_description_format( # pyright: ignore[reportUnusedFunction] return normalized +def _canonicalize_schema(schema: Any) -> Any: + """Recursively sort schema dictionary keys deterministically to preserve prompt cache stability. + + Sorts all object-level keyword keys alphabetically, and recursively canonicalizes nested + schemas in mappings (properties, patternProperties, $defs, definitions, dependentSchemas) + and sequences (items, allOf, anyOf, oneOf). Non-dict/list values are returned unmodified. + """ + if isinstance(schema, dict): + schema_dict = cast(dict[str, Any], schema) + result: dict[str, Any] = {} + for key, val in sorted(schema_dict.items(), key=lambda pair: pair[0]): + if isinstance(val, (dict, list)): + result[key] = _canonicalize_schema(val) + else: + result[key] = val + return result + if isinstance(schema, list): + schema_list = cast(list[Any], schema) + return [_canonicalize_schema(item) for item in schema_list] + return schema + + def _format_tool_parameters( # pyright: ignore[reportUnusedFunction] parameters: dict[str, Any], *, @@ -659,6 +695,8 @@ class WeatherArgs(BaseModel): "_invoke_sync_on_event_loop", } _PICKLE_OMIT_FIELDS = SerializationMixin._PICKLE_OMIT_FIELDS | {"_invocation_duration_histogram"} + # A tool that ``BaseAgent.as_tool()`` made keeps pointing at its agent when copied, as its function does. + _SHALLOW_COPY_FIELDS: ClassVar[set[str]] = {"raw_representation", "_wrapped_agent"} def __init__( self, @@ -1188,7 +1226,6 @@ async def invoke( direct_argument_kwargs = ( {key: value for key, value in kwargs.items() if key in parameter_names} if arguments is None else {} ) - runtime_kwargs = dict(context.kwargs) if context is not None else {} unexpected_kwargs = {key: value for key, value in kwargs.items() if key not in direct_argument_kwargs} if unexpected_kwargs: unexpected_names = ", ".join(sorted(unexpected_kwargs)) @@ -1201,6 +1238,23 @@ async def invoke( if arguments is None and context is not None: arguments = context.arguments + security_materialization = _SECURITY_ARGUMENT_MATERIALIZATION_CONTEXT.get() + if security_materialization is not None: + active_context, materialize, origin_task = security_materialization + if ( + asyncio.current_task() is origin_task + and active_context.function is self + and (context is None or context is active_context) + ): + direct_arguments = self._arguments_as_mapping(arguments) + if direct_arguments is not None: + active_context.arguments = direct_arguments + active_context.metadata[_AUTO_ARGUMENT_PREPARATION_CONTEXT_KEY] = True + materialize(active_context) + arguments = active_context.arguments + context = active_context + + runtime_kwargs = dict(context.kwargs) if context is not None else {} current_arguments = self._arguments_as_mapping(arguments) approval_visible_arguments = self._approval_visible_arguments(arguments, context) self._ensure_security_arguments_unchanged(context, current_arguments) @@ -1232,7 +1286,8 @@ async def invoke( if not OBSERVABILITY_SETTINGS.ENABLED: logger.info(f"Function name: {self.name}") logger.debug(f"Function arguments: {observable_kwargs}") - result = await self._invoke_function(call_kwargs) + with _suspend_security_argument_materialization(): + result = await self._invoke_function(call_kwargs) if skip_parsing: logger.info(f"Function {self.name} succeeded.") logger.debug(f"Function result: {type(result).__name__}") @@ -1273,8 +1328,13 @@ async def invoke( return parsed span_attributes = get_function_span_attributes(self, tool_call_id=tool_call_id) - metric_attributes = dict(span_attributes) - metric_attributes[OtelAttr.MEASUREMENT_FUNCTION_TAG_NAME] = self.name + # Keep metric dimensions explicit so span-only attributes cannot flow into the histogram. + metric_attributes: dict[str, AttributeValue] = { + OtelAttr.OPERATION: OtelAttr.TOOL_EXECUTION_OPERATION, + OtelAttr.TOOL_NAME: self.name, + OtelAttr.TOOL_TYPE: "function", + OtelAttr.MEASUREMENT_FUNCTION_TAG_NAME: self.name, + } # Filter out framework kwargs that are not JSON serializable. serializable_kwargs = { k: v @@ -1306,7 +1366,8 @@ async def invoke( start_time_stamp = perf_counter() end_time_stamp: float | None = None try: - result = await self._invoke_function(call_kwargs) + with _suspend_security_argument_materialization(): + result = await self._invoke_function(call_kwargs) end_time_stamp = perf_counter() except Exception as exception: end_time_stamp = perf_counter() @@ -1387,11 +1448,14 @@ def parameters(self) -> dict[str, Any]: """Create the JSON schema of the parameters. Returns: - A dictionary containing the JSON schema for the function's parameters. + A dictionary containing the JSON schema for the function's parameters, + with deterministic recursive sorting to preserve prompt cache stability. The result is cached after the first call for performance. """ if self._cached_parameters is None: - self._cached_parameters = self._input_schema + raw_schema = self._input_schema + canonical = _canonicalize_schema(raw_schema) if isinstance(raw_schema, dict) else raw_schema + self._cached_parameters = canonical if isinstance(canonical, dict) else {} return self._cached_parameters @staticmethod @@ -1399,8 +1463,8 @@ def _make_dumpable(value: Any) -> Any: """Recursively convert a value to a JSON-dumpable form.""" from ._types import Content - if isinstance(value, list): - list_value = cast(list[object], value) + if isinstance(value, (list, tuple)): + list_value = cast(list[object] | tuple[object, ...], value) return [FunctionTool._make_dumpable(item) for item in list_value] if isinstance(value, dict): dict_value = cast(dict[object, object], value) @@ -1442,7 +1506,7 @@ def parse_result(result: Any) -> list[Content]: return [Content.from_text(result)] if isinstance(result, Content): return [result] - if isinstance(result, list) and any(isinstance(item, Content) for item in result): # type: ignore[reportUnknownVariableType] + if isinstance(result, (list, tuple)) and any(isinstance(item, Content) for item in result): # type: ignore[reportUnknownVariableType] parsed_items: list[Content] = [] for item in result: # type: ignore[reportUnknownVariableType] if isinstance(item, Content): @@ -1637,7 +1701,11 @@ def _matches_json_schema_type(value: Any, schema_type: str) -> bool: case "string": return isinstance(value, str) case "integer": - return isinstance(value, int) and not isinstance(value, bool) + # JSON Schema "integer" is a number without a fraction, so 3.0 + # is valid (#9843). bool is not an integer here. + return (isinstance(value, int) and not isinstance(value, bool)) or ( + isinstance(value, float) and value.is_integer() + ) case "number": return (isinstance(value, int | float)) and not isinstance(value, bool) case "boolean": @@ -1652,6 +1720,21 @@ def _matches_json_schema_type(value: Any, schema_type: str) -> bool: return True +def _normalize_json_schema_value(value: Any, allowed_types: list[str]) -> Any: + """Coerce a value to the type the schema asked for, where JSON is looser. + + JSON has a single number type, so a model sends ``3.0`` for a parameter the + schema declares as ``integer``. Accepting it is only half the fix: a tool that + runs ``range(count)`` or indexes with it still raises on a float. Whole-number + floats become ``int`` when ``integer`` is the only numeric type allowed. When + ``number`` is allowed too the value's own type is the answer, so nothing is + narrowed to fit a declaration that also permits fractions. + """ + if isinstance(value, float) and value.is_integer() and "integer" in allowed_types and "number" not in allowed_types: + return int(value) + return value + + def _validate_arguments_against_schema( *, arguments: Mapping[str, Any], @@ -1672,7 +1755,7 @@ def _validate_arguments_against_schema( if unexpected_fields: raise TypeError(f"Unexpected argument(s) for '{tool_name}': {', '.join(unexpected_fields)}") - for field_name, field_value in parsed_arguments.items(): + for field_name, field_value in list(parsed_arguments.items()): if not isinstance(properties.get(field_name), dict): continue @@ -1687,6 +1770,7 @@ def _validate_arguments_against_schema( f"Invalid type for '{field_name}' in '{tool_name}': " f"expected {schema_type}, got {type(field_value).__name__}" ) + parsed_arguments[field_name] = _normalize_json_schema_value(field_value, [schema_type]) continue if isinstance(schema_type, list): @@ -1696,6 +1780,7 @@ def _validate_arguments_against_schema( f"Invalid type for '{field_name}' in '{tool_name}': expected one of " f"{allowed_types}, got {type(field_value).__name__}" ) + parsed_arguments[field_name] = _normalize_json_schema_value(field_value, allowed_types) return parsed_arguments @@ -2034,21 +2119,23 @@ def _function_execution_error_result( ) -> Content: from .observability import OBSERVABILITY_SETTINGS + include_detailed_errors = config.get("include_detailed_errors", False) + recommendation = "" if include_detailed_errors else " Set include_detailed_errors=True for the full detail." if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: logger.warning( - "Function '%s' raised an exception; returning an error result to the model. " - "Set include_detailed_errors=True for the full detail. Exception: %r", + "Function '%s' raised an exception; returning an error result to the model.%s Exception: %r", tool_name, + recommendation, exception, ) else: logger.warning( - "Function '%s' raised an exception; returning an error result to the model. " - "Set include_detailed_errors=True for the full detail.", + "Function '%s' raised an exception; returning an error result to the model.%s", tool_name, + recommendation, ) message = "Error: Function failed." - if config.get("include_detailed_errors", False): + if include_detailed_errors: message = f"{message} Exception: {exception}" return _finalize_function_result( call_id=function_call.call_id, # type: ignore[arg-type] @@ -4085,12 +4172,24 @@ def register_request_batch(batch_index: int) -> None: matched_host_result_ids.add(response_id) host_result_content_indices[response_id] = response_content_indices[response_id] + # The collected mapping keeps one response per approval id, so an earlier response would hide a + # later one sharing its id. Every unsettled response object must count as pending instead. + settled_approval_response_ids: set[int] = set() + _collect_approval_responses( + messages, + non_approval_result_ids=matched_host_result_ids, + settled_response_ids=settled_approval_response_ids, + ) pending_approval_response_ids = { - id(response) - for response in _collect_approval_responses( - messages, - non_approval_result_ids=matched_host_result_ids, - ).values() + id(content) + for message in messages + for content in message.contents + if content.type == "function_approval_response" + and not _is_hosted_tool_approval(content) + and content.id is not None + and content.function_call is not None + and content.function_call.call_id is not None + and id(content) not in settled_approval_response_ids } pending_approval_batch_indices = { batch_index @@ -4190,6 +4289,8 @@ def _collect_approval_responses( request = latest_requests_by_id.get(request_id) if request_id is not None else None is_protected = protected_response_ids is not None and id(content) in protected_response_ids if not is_protected and request is not None and id(request) in closed_request_occurrences: + # Closed already, so it can never execute; mark it settled so replay stays inert. + resolved_response_ids.add(id(content)) continue approval_responses.append(content) if content.id is not None: @@ -4469,9 +4570,7 @@ def _replace_approval_contents_with_results( Returns: The terminal contents produced while resolving the approval responses, in response order. """ - from ._types import ( - Content, - ) + from ._types import APPROVAL_REJECTION_RESULT_KEY, Content result_groups_by_call_id: dict[str, deque[list[Content]]] = {} for result_group in approved_function_result_groups: @@ -4598,7 +4697,10 @@ def find_approval_occurrence(approval_id: str) -> _ApprovalCallOccurrence | None call_id=call_id, id=occurrence.function_call.id if occurrence is not None else content.function_call.id, result="Error: Tool call invocation was rejected by user.", - additional_properties=content.function_call.additional_properties, + additional_properties={ + **content.function_call.additional_properties, + APPROVAL_REJECTION_RESULT_KEY: True, + }, ) ] if not replacements: @@ -4915,10 +5017,21 @@ def _reset_required_tool_choice(options: dict[str, Any]) -> None: def _prepare_messages_for_next_iteration(prepared_messages: list[Message], response: ChatResponse[Any]) -> None: + from ._types import Message + if response.conversation_id is None: prepared_messages.extend(response.messages) return - prepared_messages[:] = response.messages[-1:] + local_results = [ + content + for message in response.messages[:-1] + for content in message.contents + if content.type in {"function_result", "shell_tool_result", "computer_tool_result"} + and content.additional_properties.get(_LOCAL_TOOL_RESULT_KEY) is True + ] + prepared_messages[:] = ( + [Message(role="tool", contents=local_results)] if local_results else [] + ) + response.messages[-1:] @dataclass @@ -5261,22 +5374,34 @@ async def _resolve_approval_responses( # rather than raising. Settled occurrences are identified by the same correlation used # to execute approvals, so replaying a completed conversation is unaffected and only # responses that could still authorize an execution are removed. + # Dropping responses changes which calls in the batch are still awaiting an answer, so the batch + # is reclassified. Reclassification reorders the transcript and can change which responses are + # settled, so repeat until nothing more is dropped; each pass removes at least one response. settled_response_ids: set[int] = set() _collect_approval_responses( prepared_messages, non_approval_result_ids=host_result_ids, settled_response_ids=settled_response_ids, ) - if _drop_unrecorded_local_approval_responses(prepared_messages, settled_response_ids): + + dropped_any = False + while _drop_unrecorded_local_approval_responses(prepared_messages, settled_response_ids): + dropped_any = True + partial_mixed_batch, host_result_ids = _stateless_mixed_pause_batch_status(prepared_messages) + + settled_response_ids = set() + _collect_approval_responses( + prepared_messages, + non_approval_result_ids=host_result_ids, + settled_response_ids=settled_response_ids, + ) + if dropped_any: logger.warning( "Ignored one or more local tool-approval responses because this run has no authoritative " "AgentSession holding the matching approval request. Pass the same AgentSession back on the " "run that resumes an approval, or set the 'disable_approval_response_binding' function " "invocation configuration option to restore the previous unbound behavior." ) - # Dropping responses changes which calls in the batch are still awaiting an answer, - # so the batch must be reclassified before deciding whether it is incomplete. - partial_mixed_batch, host_result_ids = _stateless_mixed_pause_batch_status(prepared_messages) if partial_mixed_batch: raise RuntimeError( "A mixed function-call batch requires responses for every approval and Host-owned request." @@ -5607,6 +5732,17 @@ def __init__( kwargs["middleware"] = chat_middleware super().__init__(**kwargs) + def _finalize_function_invocation_updates( + self, + updates: Sequence[ChatResponseUpdate], + *, + response_format: Any | None = None, + ) -> ChatResponse[Any]: + """Aggregate all model turns and tool results without reapplying per-turn processing.""" + from ._types import ChatResponse + + return ChatResponse.from_updates(updates, output_format_type=response_format) + def _update_function_invocation_continuation_state( self, kwargs: dict[str, Any], @@ -6349,10 +6485,7 @@ def get_response( client_kwargs: Mapping[str, Any] | None = None, ) -> Awaitable[ChatResponse[Any]] | ResponseStream[ChatResponseUpdate, ChatResponse[Any]]: from ._middleware import _as_middleware_list, categorize_middleware # pyright: ignore[reportPrivateUsage] - from ._types import ( - ChatResponse, - ResponseStream, - ) + from ._types import ResponseStream super_get_response = cast( Callable[..., Any], @@ -6478,7 +6611,7 @@ def get_response( def finalize_stream(updates: Sequence[ChatResponseUpdate]) -> ChatResponse[Any]: if invalidation_error: raise invalidation_error[0] - return ChatResponse.from_updates(updates, output_format_type=response_format) + return self._finalize_function_invocation_updates(updates, response_format=response_format) return ResponseStream( self._stream_response_with_function_invocation( diff --git a/python/packages/core/tests/core/test_tools.py b/python/packages/core/tests/core/test_tools.py index 95ea3a8b158..d6770ee4ea3 100644 --- a/python/packages/core/tests/core/test_tools.py +++ b/python/packages/core/tests/core/test_tools.py @@ -2,6 +2,7 @@ import asyncio import copy import gc +import json import logging import pickle import threading @@ -597,6 +598,79 @@ def search(query: str, max_results: int = 10) -> str: await search.invoke(arguments={"query": "hello", "max_results": "three"}) +async def test_tool_json_schema_integer_accepts_whole_number_float(): + """JSON Schema "integer" accepts whole-number floats like 3.0 (#9843).""" + + json_schema = { + "type": "object", + "properties": { + "count": {"type": "integer"}, + }, + "required": ["count"], + } + received: list[Any] = [] + + @tool(name="counter", description="Count tool", schema=json_schema) + def counter(count: int) -> str: + received.append(count) + return str(count) + + # 3.0 is a valid JSON Schema integer; it reaches the callable as the integer + # the schema asked for, so range(count) and friends work on it. + await counter.invoke(arguments={"count": 3.0}) + assert received == [3] + assert isinstance(received[0], int) + + # 3.5 is not a valid integer. + with pytest.raises(TypeError, match="Invalid type for 'count'"): + await counter.invoke(arguments={"count": 3.5}) + + +async def test_tool_json_schema_nullable_integer_normalizes_whole_number_float(): + """A nullable integer schema accepts 3.0 and still hands the callable an int.""" + + json_schema = { + "type": "object", + "properties": { + "count": {"type": ["integer", "null"]}, + }, + } + received: list[Any] = [] + + @tool(name="counter", description="Count tool", schema=json_schema) + def counter(count: int | None) -> str: + received.append(count) + return str(count) + + await counter.invoke(arguments={"count": 3.0}) + assert received == [3] + assert isinstance(received[0], int) + + await counter.invoke(arguments={"count": None}) + assert received == [3, None] + + +async def test_tool_json_schema_number_alongside_integer_keeps_the_float(): + """When the schema also allows "number", the value's own type is the answer.""" + + json_schema = { + "type": "object", + "properties": { + "value": {"type": ["integer", "number"]}, + }, + } + received: list[Any] = [] + + @tool(name="measure", description="Measure tool", schema=json_schema) + def measure(value: float) -> str: + received.append(value) + return str(value) + + await measure.invoke(arguments={"value": 3.0}) + assert received == [3.0] + assert isinstance(received[0], float) + + def test_tool_decorator_with_json_schema_preserves_custom_properties(): """Test schema passthrough keeps custom JSON schema properties.""" @@ -1259,11 +1333,12 @@ def telemetry_test_tool(expression: str) -> str: call_args = mock_histogram.record.call_args assert call_args[0][0] > 0 # duration should be positive attributes = call_args[1]["attributes"] - assert attributes[OtelAttr.MEASUREMENT_FUNCTION_TAG_NAME] == "telemetry_test_tool" - assert attributes[OtelAttr.TOOL_CALL_ID] == "test_call_id" - assert OtelAttr.TOOL_ARGUMENTS not in attributes - assert OtelAttr.TOOL_RESULT not in attributes - assert expression not in attributes.values() + assert attributes == { + OtelAttr.OPERATION: OtelAttr.TOOL_EXECUTION_OPERATION, + OtelAttr.TOOL_NAME: "telemetry_test_tool", + OtelAttr.TOOL_TYPE: "function", + OtelAttr.MEASUREMENT_FUNCTION_TAG_NAME: "telemetry_test_tool", + } @pytest.mark.parametrize("enable_sensitive_data", [False], indirect=True) @@ -1307,8 +1382,12 @@ def telemetry_test_tool(x: int, y: int) -> int: call_args = mock_histogram.record.call_args assert call_args[0][0] > 0 # duration should be positive attributes = call_args[1]["attributes"] - assert attributes[OtelAttr.MEASUREMENT_FUNCTION_TAG_NAME] == "telemetry_test_tool" - assert attributes[OtelAttr.TOOL_CALL_ID] == "test_call_id" + assert attributes == { + OtelAttr.OPERATION: OtelAttr.TOOL_EXECUTION_OPERATION, + OtelAttr.TOOL_NAME: "telemetry_test_tool", + OtelAttr.TOOL_TYPE: "function", + OtelAttr.MEASUREMENT_FUNCTION_TAG_NAME: "telemetry_test_tool", + } @pytest.mark.parametrize("enable_sensitive_data", [True], indirect=True) @@ -1450,9 +1529,13 @@ def exception_test_tool(x: int, y: int) -> int: mock_histogram.record.assert_called_once() call_args = mock_histogram.record.call_args attributes = call_args[1]["attributes"] - assert attributes[OtelAttr.ERROR_TYPE] == ValueError.__name__ - assert OtelAttr.TOOL_ARGUMENTS not in attributes - assert OtelAttr.TOOL_RESULT not in attributes + assert attributes == { + OtelAttr.OPERATION: OtelAttr.TOOL_EXECUTION_OPERATION, + OtelAttr.TOOL_NAME: "exception_test_tool", + OtelAttr.TOOL_TYPE: "function", + OtelAttr.MEASUREMENT_FUNCTION_TAG_NAME: "exception_test_tool", + OtelAttr.ERROR_TYPE: ValueError.__name__, + } async def test_tool_invoke_telemetry_async_function(span_exporter: InMemorySpanExporter): @@ -1490,7 +1573,12 @@ async def async_telemetry_test(x: int, y: int) -> int: mock_histogram.record.assert_called_once() call_args = mock_histogram.record.call_args attributes = call_args[1]["attributes"] - assert attributes[OtelAttr.MEASUREMENT_FUNCTION_TAG_NAME] == "async_telemetry_test" + assert attributes == { + OtelAttr.OPERATION: OtelAttr.TOOL_EXECUTION_OPERATION, + OtelAttr.TOOL_NAME: "async_telemetry_test", + OtelAttr.TOOL_TYPE: "function", + OtelAttr.MEASUREMENT_FUNCTION_TAG_NAME: "async_telemetry_test", + } async def test_tool_invoke_invalid_pydantic_args(): @@ -2389,4 +2477,152 @@ def test_skip_parsing_is_singleton() -> None: assert repr(SKIP_PARSING) == "SKIP_PARSING" +def test_to_json_schema_spec_canonicalizes_reordered_top_level_keywords() -> None: + """Verify that to_json_schema_spec canonicalizes top-level and nested keyword order for prompt caching.""" + # Two tools with differently ordered top-level keywords and properties + schema_1 = { + "title": "SearchTool", + "type": "object", + "description": "Searches items", + "properties": { + "z_query": {"description": "Query string", "type": "string"}, + "a_limit": {"default": 10, "type": "integer"}, + }, + "required": ["z_query"], + } + schema_2 = { + "description": "Searches items", + "properties": { + "a_limit": {"type": "integer", "default": 10}, + "z_query": {"type": "string", "description": "Query string"}, + }, + "type": "object", + "required": ["z_query"], + "title": "SearchTool", + } + + tool_1 = FunctionTool(name="search", description="Search tool", input_model=schema_1) + tool_2 = FunctionTool(name="search", description="Search tool", input_model=schema_2) + + spec_1 = tool_1.to_json_schema_spec() + spec_2 = tool_2.to_json_schema_spec() + + # Top-level parameters dictionary keys must be sorted deterministically + assert list(spec_1["function"]["parameters"].keys()) == ["description", "properties", "required", "title", "type"] + assert list(spec_2["function"]["parameters"].keys()) == ["description", "properties", "required", "title", "type"] + + # Properties dictionary keys must be sorted deterministically + assert list(spec_1["function"]["parameters"]["properties"].keys()) == ["a_limit", "z_query"] + assert list(spec_2["function"]["parameters"]["properties"].keys()) == ["a_limit", "z_query"] + + # Wire-level serialization must be identical + wire_1 = json.dumps(spec_1) + wire_2 = json.dumps(spec_2) + assert wire_1 == wire_2 + + +def test_to_json_schema_spec_canonicalizes_root_schema_without_properties() -> None: + """Regression: root schemas without 'properties' are canonicalized deterministically.""" + schema_1 = { + "description": "A scalar or empty tool schema", + "type": "string", + "title": "ScalarInput", + } + schema_2 = { + "title": "ScalarInput", + "description": "A scalar or empty tool schema", + "type": "string", + } + + tool_1 = FunctionTool(name="scalar_tool", description="Scalar tool", input_model=schema_1) + tool_2 = FunctionTool(name="scalar_tool", description="Scalar tool", input_model=schema_2) + + spec_1 = tool_1.to_json_schema_spec() + spec_2 = tool_2.to_json_schema_spec() + + assert list(spec_1["function"]["parameters"].keys()) == ["description", "title", "type"] + assert list(spec_2["function"]["parameters"].keys()) == ["description", "title", "type"] + assert json.dumps(spec_1) == json.dumps(spec_2) + + +def test_to_json_schema_spec_canonicalizes_nested_and_defs_deterministically() -> None: + """Verify that nested objects, $defs, and arrays are recursively sorted deterministically.""" + schema = { + "type": "object", + "$defs": { + "ZItem": {"type": "string"}, + "AItem": {"type": "integer"}, + }, + "properties": { + "metadata": { + "type": "object", + "properties": { + "tag_z": {"type": "string"}, + "tag_a": {"type": "string"}, + }, + }, + }, + } + tool = FunctionTool(name="complex_tool", description="Complex tool", input_model=schema) + spec = tool.to_json_schema_spec() + params = spec["function"]["parameters"] + + assert list(params.keys()) == ["$defs", "properties", "type"] + assert list(params["$defs"].keys()) == ["AItem", "ZItem"] + assert list(params["properties"]["metadata"]["properties"].keys()) == ["tag_a", "tag_z"] + + +def test_parameters_canonicalizes_schema_deterministically() -> None: + """Verify that FunctionTool.parameters() directly canonicalizes schemas deterministically. + + This ensures providers that serialize tool.parameters() directly (such as Anthropic, + Bedrock, Gemini, and Mistral) obtain deterministic wire-level outputs without cache churn. + """ + schema_1 = { + "title": "Config", + "description": "Provider tool", + "type": "object", + "properties": { + "z_param": {"type": "string"}, + "a_param": {"type": "integer"}, + }, + } + schema_2 = { + "properties": { + "a_param": {"type": "integer"}, + "z_param": {"type": "string"}, + }, + "type": "object", + "description": "Provider tool", + "title": "Config", + } + + tool_1 = FunctionTool(name="config_tool", description="tool", input_model=schema_1) + tool_2 = FunctionTool(name="config_tool", description="tool", input_model=schema_2) + + params_1 = tool_1.parameters() + params_2 = tool_2.parameters() + + # Direct parameters() must be sorted deterministically + assert list(params_1.keys()) == ["description", "properties", "title", "type"] + assert list(params_2.keys()) == ["description", "properties", "title", "type"] + assert list(params_1["properties"].keys()) == ["a_param", "z_param"] + assert list(params_2["properties"].keys()) == ["a_param", "z_param"] + + # Provider wire simulation: Anthropic tool definition shape + anthropic_wire_1 = json.dumps({ + "type": "custom", + "name": tool_1.name, + "description": tool_1.description, + "input_schema": tool_1.parameters(), + }) + anthropic_wire_2 = json.dumps({ + "type": "custom", + "name": tool_2.name, + "description": tool_2.description, + "input_schema": tool_2.parameters(), + }) + assert anthropic_wire_1 == anthropic_wire_2 + + # endregion