The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
fix(core): resolve postponed annotations in `StructuredTool._injected_args_keys` (#39602)
Mason Daugherty5c3538e83a24
diff --git a/libs/core/langchain_core/tools/base.py b/libs/core/langchain_core/tools/base.pyindex a1cd5502f1..69020241cd 100644--- a/libs/core/langchain_core/tools/base.py+++ b/libs/core/langchain_core/tools/base.py@@ -20,7 +20,6 @@ from typing import (cast,get_args,get_origin,- get_type_hints,)import typing_extensions@@ -38,7 +37,7 @@ from pydantic.fields import FieldInfofrom pydantic.v1 import BaseModel as BaseModelV1from pydantic.v1 import ValidationError as ValidationErrorV1from pydantic.v1 import validate_arguments as validate_arguments_v1-from typing_extensions import Self, override+from typing_extensions import Self, get_type_hints, overridefrom langchain_core.callbacks import (AsyncCallbackManager,@@ -184,7 +183,7 @@ def _infer_arg_descriptions(Returns:A tuple containing the function description and argument descriptions."""- annotations = typing.get_type_hints(fn, include_extras=True)+ annotations = get_type_hints(fn, include_extras=True)if parse_docstring:description, arg_descriptions = _parse_python_function_docstring(fn, annotations, error_on_invalid_docstring=error_on_invalid_docstring@@ -730,20 +729,8 @@ class ChildTool(BaseTool):# rather than by the model, so they must be excluded from the schema and# re-injected during execution. `StructuredTool` overrides this to# inspect its wrapped `func`/`coroutine` instead.- #- # Resolve annotations via `get_type_hints` (rather than reading raw- # `signature` annotations) so postponed annotations -- e.g. from- # `from __future__ import annotations` or quoted forward references --- # are recognized. Fall back to the raw annotation per-parameter when a- # hint can't be resolved.for method in (self._run, self._arun):- params = signature(method).parameters- hints = _get_type_hints(method, include_extras=True) or {}- keys = frozenset(- name- for name, param in params.items()- if _is_injected_arg_type(hints.get(name, param.annotation))- )+ keys = _get_injected_args_keys_from_signature(method)if keys:return keysreturn _EMPTY_SET@@ -1496,6 +1483,11 @@ def _stringify(content: Any) -> str:return str(content)+def _describe_callable(func: Any) -> str:+ """Return a readable identifier for a callable, for use in log messages."""+ return getattr(func, "__qualname__", None) or repr(func)++def _get_type_hints(func: Callable[..., Any], *, include_extras: bool = False) -> dict[str, type] | None:@@ -1514,6 +1506,202 @@ def _get_type_hints(try:return get_type_hints(func, include_extras=include_extras)except Exception:+ _logger.debug(+ "Failed to resolve type hints for %s.",+ _describe_callable(func),+ exc_info=True,+ )+ return None+++def _get_class_signature_source(cls: type) -> Callable[..., Any] | None:+ """Return the callable whose parameters `signature(cls)` describes.++ A class's own annotations describe its attributes, not its constructor+ parameters, so a class is never its own annotation owner. Constructor+ precedence mirrors `inspect.signature`: a metaclass `__call__` override,+ then a `__new__`/`__init__` the class defines itself, then an inherited one.++ Args:+ cls: The class being inspected.++ Returns:+ The constructor whose annotations describe `signature(cls)`, or `None`+ when only slot wrappers inherited from `object` are available.+ """+ metaclass = type(cls)+ if metaclass is not type:+ metaclass_call = inspect.getattr_static(metaclass, "__call__", None)+ if inspect.isfunction(metaclass_call):+ return metaclass_call+ for attr in ("__new__", "__init__"):+ if attr in cls.__dict__:+ return cast("Callable[..., Any]", getattr(cls, attr))+ for attr in ("__new__", "__init__"):+ # `object.__new__`/`object.__init__` are slot wrappers carrying no+ # useful annotations, so only inherited Python constructors qualify.+ inherited = getattr(cls, attr, None)+ if inspect.isfunction(inherited):+ return cast("Callable[..., Any]", inherited)+ return None+++def _get_type_hints_source(+ func: Callable[..., Any],+) -> Callable[..., Any] | None:+ """Return the callable that owns the annotations for an effective signature.++ Unwrapping stops as soon as a callable declares its own `__signature__` (or+ is a bound method), because that declaration -- not the annotations of+ whatever it wraps -- defines the effective signature.++ Args:+ func: The callable being inspected.++ Returns:+ The function or method whose annotations describe `signature(func)`, or+ `None` when an explicit `__signature__` supplies the annotations or no+ annotation owner can be identified.+ """+ func = inspect.unwrap(+ func,+ stop=lambda wrapped: (+ hasattr(wrapped, "__signature__") or inspect.ismethod(wrapped)+ ),+ )+ if inspect.ismethod(func):+ return _get_type_hints_source(func.__func__)+ if getattr(func, "__signature__", None) is not None:+ return None+ if isinstance(func, functools.partial):+ return _get_type_hints_source(func.func)+ if inspect.isclass(func):+ constructor = _get_class_signature_source(func)+ if constructor is None:+ return None+ return _get_type_hints_source(constructor)+ if not inspect.isroutine(func):+ callable_obj = cast("Any", func)+ return _get_type_hints_source(cast("Callable[..., Any]", callable_obj.__call__))+ return func+++def _get_callable_globals(func: Callable[..., Any]) -> dict[str, Any]:+ """Return the globals namespace associated with a callable.++ Explicit `__signature__` objects store annotations separately from a+ callable's `__annotations__`. String annotations on such signatures+ still need the callable's defining globals to be resolved.++ Args:+ func: The callable whose defining globals to locate.++ Returns:+ The callable's globals namespace, or an empty `dict` when none can be+ located (e.g. classes, builtins, and other C-implemented callables), in+ which case no string annotation will resolve.+ """+ if isinstance(func, functools.partial):+ return _get_callable_globals(func.func)+ if inspect.ismethod(func):+ return _get_callable_globals(func.__func__)+ globalns = getattr(func, "__globals__", None)+ if isinstance(globalns, dict):+ return globalns+ if not inspect.isroutine(func) and not inspect.isclass(func):+ callable_obj = cast("Any", func)+ return _get_callable_globals(cast("Callable[..., Any]", callable_obj.__call__))+ return {}+++def _get_injected_args_keys_from_signature(func: Callable[..., Any]) -> frozenset[str]:+ """Identify injected-argument parameters of a callable.++ Resolve annotations with `get_type_hints` (rather than reading raw+ `signature` annotations) so postponed annotations -- e.g. from+ `from __future__ import annotations` or quoted forward references -- are+ recognized. `get_type_hints` resolves every annotation at once and raises+ on the first failure, so any parameter it leaves uncovered is retried on its+ own: an unrelated unresolvable forward reference must not disable injection+ for parameters whose annotations do resolve. Each distinct string annotation+ is resolved at most once per call, failures included.++ A *string* annotation naming a type that exists only in the callable's+ defining local scope cannot be resolved here, since only globals are+ available. Such a parameter keeps its raw string annotation, which+ `_is_injected_arg_type` never classifies as injected, so it stays visible to+ the model rather than being injected at call time. Non-string annotations+ are unaffected, since `signature` yields the live object.++ Args:+ func: The function (or bound method) whose signature to inspect.++ Returns:+ `frozenset` of parameter names annotated as injected arguments.+ """+ params = signature(func).parameters+ hint_source = _get_type_hints_source(func)+ hints = (+ _get_type_hints(hint_source, include_extras=True)+ if hint_source is not None+ else None+ ) or {}+ globalns: dict[str, Any] | None = None+ resolved_annotations: dict[str, Any] = {}+ keys = set()+ for name, param in params.items():+ annotation = hints.get(name, param.annotation)+ if isinstance(annotation, str):+ if globalns is None:+ globalns = _get_callable_globals(+ func if hint_source is None else hint_source+ )+ if annotation not in resolved_annotations:+ resolved_annotations[annotation] = _resolve_forward_ref(+ annotation, globalns+ )+ resolved = resolved_annotations[annotation]+ if resolved is None:+ _logger.debug(+ "Could not resolve annotation %r for parameter %r of %s; it "+ "will not be treated as an injected argument.",+ annotation,+ name,+ _describe_callable(func),+ )+ else:+ annotation = resolved+ if _is_injected_arg_type(annotation):+ keys.add(name)+ return frozenset(keys)+++def _resolve_forward_ref(annotation: str, globalns: dict[str, Any]) -> Any:+ """Resolve a single string annotation, returning `None` on failure.++ Uses a temporary annotated function so each annotation can be passed through+ the public `get_type_hints` API independently.++ Args:+ annotation: The raw string annotation to resolve.+ globalns: The globals namespace to resolve names against.++ Returns:+ The resolved type, or `None` if the annotation cannot be resolved.+ """++ def _annotation_holder() -> None:+ pass++ _annotation_holder.__annotations__ = {"value": annotation}+ try:+ return get_type_hints(+ _annotation_holder,+ globalns=globalns,+ include_extras=True,+ )["value"]+ except Exception:+ _logger.debug("Failed to resolve annotation %r.", annotation, exc_info=True)return Nonediff --git a/libs/core/langchain_core/tools/structured.py b/libs/core/langchain_core/tools/structured.pyindex e9643a0ad8..57892a4464 100644--- a/libs/core/langchain_core/tools/structured.py+++ b/libs/core/langchain_core/tools/structured.py@@ -27,8 +27,8 @@ from langchain_core.tools.base import (FILTERED_ARGS,ArgsSchema,BaseTool,+ _get_injected_args_keys_from_signature,_get_runnable_config_param,- _is_injected_arg_type,create_schema_from_function,)from langchain_core.utils.pydantic import is_basemodel_subclass@@ -256,11 +256,7 @@ class StructuredTool(BaseTool):fn = self.func or self.coroutineif fn is None:return _EMPTY_SET- return frozenset(- k- for k, v in signature(fn).parameters.items()- if _is_injected_arg_type(v.annotation)- )+ return _get_injected_args_keys_from_signature(fn)def _filter_schema_args(func: Callable[..., Any]) -> list[str]:diff --git a/libs/core/tests/unit_tests/test_tools.py b/libs/core/tests/unit_tests/test_tools.pyindex 9b16fa8b5f..63fbfa4368 100644--- a/libs/core/tests/unit_tests/test_tools.py+++ b/libs/core/tests/unit_tests/test_tools.py@@ -7,6 +7,7 @@ import pickleimport sysimport textwrapimport threading+import warningsfrom collections.abc import Callablefrom dataclasses import dataclassfrom datetime import datetime@@ -2895,6 +2896,353 @@ def test_tool_injected_arg_with_custom_schema() -> None:assert captured["context"].value == "test_context"+@dataclass+class _PostponedRuntime(_DirectlyInjectedToolArg):+ """Custom directly injected runtime used to exercise postponed annotations."""++ some_obj: object++[email protected]("schema_format", ["model", "json_schema"])+def test_tool_allows_postponed_runtime_annotation_with_custom_schema(+ schema_format: Literal["model", "json_schema"],+) -> None:+ """Ensure postponed injected annotations are preserved with custom args_schema.++ Regression test: `StructuredTool._injected_args_keys` previously read raw+ `signature` annotations, which are strings under `from __future__ import+ annotations`. A quoted forward reference reproduces the same string-annotation+ behavior without a module-wide `__future__` import.+ """++ class InputSchema(BaseModel):+ query: str++ captured: dict[str, Any] = {}++ args_schema = (+ InputSchema if schema_format == "model" else InputSchema.model_json_schema()+ )++ @tool(args_schema=args_schema)+ def runtime_tool(query: str, runtime: "_PostponedRuntime") -> str:+ """Echo the query and capture runtime value."""+ captured["runtime"] = runtime+ return query++ runtime_obj = object()+ runtime = _PostponedRuntime(some_obj=runtime_obj)++ # The injected arg is detected from the postponed annotation...+ assert "runtime" in runtime_tool._injected_args_keys+ # ...survives input validation and reaches the function...+ assert runtime_tool.invoke({"query": "hello", "runtime": runtime}) == "hello"+ assert captured["runtime"] is runtime+ # ...and does not leak into the model-facing tool-call schema.+ tool_call_schema = runtime_tool.tool_call_schema+ if isinstance(tool_call_schema, dict):+ properties = tool_call_schema["properties"]+ else:+ properties = model_json_schema(tool_call_schema)["properties"]+ assert "runtime" not in properties+++def test_tool_partial_does_not_restore_bound_injected_arg() -> None:+ """Injected args already bound by a partial are absent from its signature."""++ class InputSchema(BaseModel):+ y: int++ bound_runtime = _PostponedRuntime(some_obj=object())++ def fn(x: int, runtime: _PostponedRuntime, y: int) -> int:+ return x + y++ tool_ = StructuredTool.from_function(+ func=partial(fn, 1, bound_runtime),+ name="fn",+ description="Add two numbers.",+ args_schema=InputSchema,+ )++ assert "runtime" not in tool_._injected_args_keys+ assert tool_.invoke({"y": 2, "runtime": object()}) == 3+++def test_tool_custom_schema_unresolvable_forward_ref_does_not_raise() -> None:+ """Unresolved forward references must not break `_injected_args_keys`.++ When a postponed annotation cannot be resolved (e.g. the name is not+ defined), `get_type_hints` raises. `_injected_args_keys` must fall back to+ the raw (string) annotation instead of propagating the error.+ """++ class InputSchema(BaseModel):+ query: str++ def fn(+ query: str,+ runtime: "NotDefinedAnywhere123", # type: ignore[name-defined] # noqa: F821+ ) -> str:+ """Fn with unresolvable forward ref."""+ return query++ tool_ = StructuredTool.from_function(+ func=fn,+ name="fn",+ description="desc",+ args_schema=InputSchema,+ )++ # The unresolved annotation is not recognized as injected (safe fallback),+ # and accessing `_injected_args_keys` must not raise.+ assert "runtime" not in tool_._injected_args_keys+++def test_tool_unresolvable_sibling_annotation_does_not_disable_injection() -> None:+ """An unresolvable annotation on one parameter must not hide injected args.++ `get_type_hints` resolves all annotations at once, so a single unresolvable+ forward reference (e.g. on `query`) would otherwise discard the resolvable+ hints too -- including the injected `runtime` -- leaving+ `_injected_args_keys` empty and dropping the injected value during custom+ `args_schema` validation.+ """++ class InputSchema(BaseModel):+ query: str++ captured: dict[str, Any] = {}++ @tool(args_schema=InputSchema)+ def runtime_tool(+ query: "NotDefinedAnywhere123", # type: ignore[name-defined] # noqa: F821+ runtime: "_PostponedRuntime",+ ) -> str:+ """Echo the query and capture runtime value."""+ captured["runtime"] = runtime+ return query # type: ignore[no-any-return]++ runtime = _PostponedRuntime(some_obj=object())++ # The resolvable injected annotation is still detected without relying on+ # deprecated typing internals.+ with warnings.catch_warnings():+ warnings.simplefilter("error", DeprecationWarning)+ injected_args_keys = runtime_tool._injected_args_keys+ assert "runtime" in injected_args_keys+ # ...while the unresolvable one is not misclassified.+ assert "query" not in injected_args_keys++ assert runtime_tool.invoke({"query": "hello", "runtime": runtime}) == "hello"+ assert captured["runtime"] is runtime+++def test_tool_fallback_preserves_annotated_injected_arg() -> None:+ """Per-parameter fallback preserves `Annotated` injection metadata."""++ class InputSchema(BaseModel):+ query: str++ captured: dict[str, Any] = {}++ @tool(args_schema=InputSchema)+ def runtime_tool(+ query: "NotDefinedAnywhere123", # type: ignore[name-defined] # noqa: F821+ runtime: "Annotated[str, InjectedToolArg]",+ ) -> str:+ """Echo the query and capture the injected value."""+ captured["runtime"] = runtime+ return query # type: ignore[no-any-return]++ assert runtime_tool._injected_args_keys == frozenset({"runtime"})+ assert runtime_tool.invoke({"query": "hello", "runtime": "injected"}) == "hello"+ assert captured["runtime"] == "injected"+++def test_tool_partial_fallback_uses_wrapped_function_namespace() -> None:+ """Partial fallback resolves hints in the wrapped function's namespace."""++ class InputSchema(BaseModel):+ query: str++ captured: dict[str, Any] = {}++ def runtime_fn(+ bound: int,+ query: "NotDefinedAnywhere123", # type: ignore[name-defined] # noqa: F821+ runtime: "_PostponedRuntime",+ ) -> str:+ captured["bound"] = bound+ captured["runtime"] = runtime+ return query # type: ignore[no-any-return]++ tool_ = StructuredTool.from_function(+ func=partial(runtime_fn, 1),+ name="runtime_tool",+ description="Echo a query.",+ args_schema=InputSchema,+ )+ runtime = _PostponedRuntime(some_obj=object())++ assert tool_._injected_args_keys == frozenset({"runtime"})+ assert tool_.invoke({"query": "hello", "runtime": runtime}) == "hello"+ assert captured == {"bound": 1, "runtime": runtime}+++def test_base_tool_unresolvable_sibling_annotation_does_not_disable_injection() -> None:+ """`BaseTool` subclasses get the same per-parameter hint resolution."""++ class MultiplyInput(BaseModel):+ a: int++ captured: dict[str, Any] = {}++ class Multiplier(BaseTool):+ name: str = "Multiplier"+ description: str = "Multiply."+ args_schema: type[BaseModel] = MultiplyInput++ def _run(+ self,+ a: "NotDefinedAnywhere123", # type: ignore[name-defined] # noqa: F821+ runtime: "_CustomRuntime",+ ) -> int:+ captured["runtime"] = runtime+ return a * 2 # type: ignore[no-any-return]++ tool_ = Multiplier()+ assert "runtime" in tool_._injected_args_keys+ assert "a" not in tool_._injected_args_keys++ runtime = _CustomRuntime(data={"scale": 10})+ assert tool_.invoke({"a": 2, "runtime": runtime}) == 4+ assert captured["runtime"] is runtime+++def test_tool_class_callable_uses_constructor_annotations() -> None:+ """A class used as `func` is inspected via its constructor, not its attributes.++ Regression test: a class's own annotations describe attributes, so a+ class-level annotation sharing a name with a constructor parameter must not+ shadow that parameter's annotation.+ """++ class InputSchema(BaseModel):+ query: str++ class SearchTool:+ runtime: str = "class attribute sharing a name with a constructor param"++ def __init__(self, query: str, runtime: _PostponedRuntime) -> None:+ self.query = query+ self.runtime = runtime # type: ignore[assignment]++ tool_ = StructuredTool.from_function(+ func=SearchTool,+ name="search_tool",+ description="Search.",+ args_schema=InputSchema,+ )+ runtime = _PostponedRuntime(some_obj=object())++ assert tool_._injected_args_keys == frozenset({"runtime"})+ result = tool_.invoke({"query": "hello", "runtime": runtime})+ assert result.query == "hello"+ assert result.runtime is runtime+++def test_tool_class_callable_attribute_annotation_is_not_injected() -> None:+ """A class attribute annotation must not mark a constructor param injected.++ Otherwise a model-facing argument is treated as injected, and the raw input+ value replaces the one validated against `args_schema`.+ """++ class InputSchema(BaseModel):+ query: str+ count: int++ class CountTool:+ count: _PostponedRuntime = None # type: ignore[assignment]++ def __init__(self, query: str, count: int) -> None:+ self.count = count # type: ignore[assignment]++ tool_ = StructuredTool.from_function(+ func=CountTool,+ name="count_tool",+ description="Count.",+ args_schema=InputSchema,+ )++ assert tool_._injected_args_keys == frozenset()+ tool_call_schema = tool_.tool_call_schema+ assert not isinstance(tool_call_schema, dict)+ assert "count" in model_json_schema(tool_call_schema)["properties"]+ # The schema-validated value reaches the constructor, not the raw input.+ result = tool_.invoke({"query": "hello", "count": "5"})+ assert result.count == 5+ assert isinstance(result.count, int)+++def test_tool_class_callable_uses_new_annotations() -> None:+ """Classes that customize allocation are inspected via `__new__`."""++ class InputSchema(BaseModel):+ query: str++ captured: dict[str, Any] = {}++ class NewTool:+ # Quoted so resolution must go through `__new__`'s own globals.+ def __new__(cls, query: str, runtime: "_PostponedRuntime") -> str: # type: ignore[misc]+ captured["runtime"] = runtime+ return query++ tool_ = StructuredTool.from_function(+ func=NewTool,+ name="new_tool",+ description="Echo a query.",+ args_schema=InputSchema,+ )+ runtime = _PostponedRuntime(some_obj=object())++ assert tool_._injected_args_keys == frozenset({"runtime"})+ assert tool_.invoke({"query": "hello", "runtime": runtime}) == "hello"+ assert captured["runtime"] is runtime+++def test_tool_class_callable_uses_metaclass_call_annotations() -> None:+ """A metaclass `__call__` override supplies the effective signature."""++ class InputSchema(BaseModel):+ query: str++ captured: dict[str, Any] = {}++ class _Meta(type):+ def __call__(cls, query: str, runtime: _PostponedRuntime) -> str:+ captured["runtime"] = runtime+ return query++ class MetaTool(metaclass=_Meta):+ def __init__(self, runtime: int) -> None:+ """Constructor parameters are shadowed by the metaclass `__call__`."""++ tool_ = StructuredTool.from_function(+ func=MetaTool,+ name="meta_tool",+ description="Echo a query.",+ args_schema=InputSchema,+ )+ runtime = _PostponedRuntime(some_obj=object())++ assert tool_._injected_args_keys == frozenset({"runtime"})+ assert tool_.invoke({"query": "hello", "runtime": runtime}) == "hello"+ assert captured["runtime"] is runtime++def test_tool_injected_tool_call_id() -> None:@tooldef foo(x: int, tool_call_id: Annotated[str, InjectedToolCallId]) -> ToolMessage:diff --git a/libs/core/tests/unit_tests/test_tools_postponed_annotations.py b/libs/core/tests/unit_tests/test_tools_postponed_annotations.pynew file mode 100644index 0000000000..defce1678c--- /dev/null+++ b/libs/core/tests/unit_tests/test_tools_postponed_annotations.py@@ -0,0 +1,178 @@+"""Tests for tools defined in modules with postponed annotations."""++from __future__ import annotations++from functools import update_wrapper+from inspect import Parameter, Signature+from typing import Annotated, Any++from pydantic import BaseModel++from langchain_core.tools import InjectedToolArg, StructuredTool+from langchain_core.tools.base import _DirectlyInjectedToolArg+from langchain_core.utils.pydantic import model_json_schema+++class _PostponedRuntime(_DirectlyInjectedToolArg):+ """Runtime type whose annotation is postponed by the module future import."""+++class _InputSchema(BaseModel):+ query: str+++class _CallableTool:+ """Callable-object tool with annotations stored on `__call__`."""++ received_runtime: _PostponedRuntime | None = None++ def __call__(self, query: str, runtime: _PostponedRuntime) -> str:+ self.received_runtime = runtime+ return query+++def test_callable_object_resolves_postponed_injected_arg() -> None:+ """Callable objects resolve annotations from their `__call__` method."""+ callable_tool = _CallableTool()+ tool = StructuredTool.from_function(+ func=callable_tool,+ name="callable_tool",+ description="Echo a query.",+ args_schema=_InputSchema,+ )+ runtime = _PostponedRuntime()++ assert tool._injected_args_keys == frozenset({"runtime"})+ assert tool.invoke({"query": "hello", "runtime": runtime}) == "hello"+ assert callable_tool.received_runtime is runtime++ tool_call_schema = tool.tool_call_schema+ assert not isinstance(tool_call_schema, dict)+ assert "runtime" not in model_json_schema(tool_call_schema)["properties"]+++def test_callable_wrapper_uses_wrapped_function_annotations() -> None:+ """Callable wrappers resolve hints from their effective signature source."""+ received: dict[str, Any] = {}++ def wrapped(query: str, runtime: _PostponedRuntime) -> str:+ received["runtime"] = runtime+ return query++ class CallableWrapper:+ def __init__(self) -> None:+ update_wrapper(self, wrapped)++ def __call__(self, query: str, runtime: str) -> str:+ return wrapped(query, runtime) # type: ignore[arg-type]++ callable_wrapper = CallableWrapper()+ tool = StructuredTool.from_function(+ func=callable_wrapper,+ name="callable_wrapper",+ description="Echo a query.",+ args_schema=_InputSchema,+ )+ runtime = _PostponedRuntime()++ assert tool._injected_args_keys == frozenset({"runtime"})+ assert tool.invoke({"query": "hello", "runtime": runtime}) == "hello"+ assert received["runtime"] is runtime+++def test_callable_object_uses_explicit_signature_annotations() -> None:+ """An explicit signature takes precedence over `__call__` annotations."""+ received: dict[str, Any] = {}++ class CallableWithSignature:+ __signature__ = Signature(+ parameters=[+ Parameter("query", Parameter.POSITIONAL_OR_KEYWORD, annotation=str),+ Parameter(+ "runtime",+ Parameter.POSITIONAL_OR_KEYWORD,+ annotation=_PostponedRuntime,+ ),+ ]+ )++ def __call__(self, query: str, runtime: str) -> str:+ received["runtime"] = runtime+ return query++ callable_with_signature = CallableWithSignature()+ tool = StructuredTool.from_function(+ func=callable_with_signature,+ name="callable_with_signature",+ description="Echo a query.",+ args_schema=_InputSchema,+ )+ runtime = _PostponedRuntime()++ assert tool._injected_args_keys == frozenset({"runtime"})+ assert tool.invoke({"query": "hello", "runtime": runtime}) == "hello"+ assert received["runtime"] is runtime+++def test_explicit_signature_resolves_string_injected_annotation() -> None:+ """String annotations on explicit signatures use callable globals."""+ received: dict[str, Any] = {}++ class CallableWithStringSignature:+ __signature__ = Signature(+ parameters=[+ Parameter("query", Parameter.POSITIONAL_OR_KEYWORD, annotation=str),+ Parameter(+ "runtime",+ Parameter.POSITIONAL_OR_KEYWORD,+ annotation="Annotated[_PostponedRuntime, InjectedToolArg]",+ ),+ ]+ )++ def __call__(+ self, query: str, runtime: Annotated[_PostponedRuntime, InjectedToolArg]+ ) -> str:+ received["runtime"] = runtime+ return query++ tool = StructuredTool.from_function(+ func=CallableWithStringSignature(),+ name="callable_with_string_signature",+ description="Echo a query.",+ args_schema=_InputSchema,+ )+ runtime = _PostponedRuntime()++ assert tool._injected_args_keys == frozenset({"runtime"})+ assert tool.invoke({"query": "hello", "runtime": runtime}) == "hello"+ assert received["runtime"] is runtime+ tool_call_schema = tool.tool_call_schema+ assert not isinstance(tool_call_schema, dict)+ assert "runtime" not in model_json_schema(tool_call_schema)["properties"]+++def test_class_callable_resolves_postponed_injected_arg() -> None:+ """Classes resolve constructor annotations postponed by the future import."""++ class ClassTool:+ def __init__(self, query: str, runtime: _PostponedRuntime) -> None:+ self.query = query+ self.runtime = runtime++ tool = StructuredTool.from_function(+ func=ClassTool,+ name="class_tool",+ description="Echo a query.",+ args_schema=_InputSchema,+ )+ runtime = _PostponedRuntime()++ assert tool._injected_args_keys == frozenset({"runtime"})+ result = tool.invoke({"query": "hello", "runtime": runtime})+ assert result.query == "hello"+ assert result.runtime is runtime++ tool_call_schema = tool.tool_call_schema+ assert not isinstance(tool_call_schema, dict)+ assert "runtime" not in model_json_schema(tool_call_schema)["properties"]