Skip to content

Commit 5c3538e

Browse files
authored
fix(core): resolve postponed annotations in StructuredTool._injected_args_keys (#39602)
Closes #39568 Related: #33999 > [!WARNING] > This PR expands the surface area for arbitrary code execution during tool setup. Detecting injected arguments now requires calling `typing.get_type_hints`, which *evaluates* string annotations (e.g. those created by `from __future__ import annotations` or quoted forward references) as Python expressions. As with existing type-hint resolution paths, wrapped tool callables must be trusted application code — never point `StructuredTool` at a callable whose module or annotations come from an untrusted source. Tools with a custom `args_schema` could drop injected arguments such as `ToolRuntime` when the wrapped function's module uses postponed annotations. The injected value was removed during input validation, so an otherwise valid tool call failed at invocation. --- `StructuredTool` now resolves annotations with `typing.get_type_hints(..., include_extras=True)` before identifying injected parameters. If an unrelated forward reference prevents resolving the complete signature, each string annotation is resolved independently so resolvable injected arguments are still preserved. Callable wrappers resolve annotations from the source of their effective signature, honoring `__wrapped__` and `__signature__`, while other callable objects use their `__call__` method. `functools.partial` callables retain their effective signature so already-bound injected arguments remain excluded. <details> <summary><b>Before/after:</b> injected arg dropped under <code>from __future__ import annotations</code></summary> With postponed annotations, every annotation is stored as a plain string. Previously `_injected_args_keys` read the raw `signature()` annotations, so `runtime` was never recognized as injected and was stripped during `args_schema` validation: ```python from __future__ import annotations # all annotations become strings from pydantic import BaseModel from langchain_core.tools import tool, ToolRuntime class InputSchema(BaseModel): query: str @tool(args_schema=InputSchema) def my_tool(query: str, runtime: ToolRuntime) -> str: """Echo the query.""" return query ``` | | Behavior | |---|---| | **Before** | `runtime` not detected as injected → removed during validation → tool call fails at invocation | | **After** | `runtime` detected via `get_type_hints` → survives validation and is injected at invocation; hidden from the model-facing schema | </details> <details> <summary><b>Before/after:</b> one unresolvable annotation disabling injection for the whole signature</summary> `get_type_hints` resolves *all* annotations at once and raises on the first failure. A single unresolvable forward reference — even on an unrelated parameter — previously meant *no* hints were available, so the resolvable injected arg was dropped too: ```python @tool(args_schema=InputSchema) def my_tool( query: "SomeTypeThatDoesNotExist", # unresolvable forward reference runtime: "ToolRuntime", # resolvable injected arg ) -> str: """Echo the query.""" return query ``` | | Behavior | |---|---| | **Before** | `get_type_hints` raises on `query` → all hints discarded → `runtime` not detected as injected | | **After** | each annotation is retried independently → `query` falls back to its raw string (not injected), `runtime` still resolves and is injected | </details> <details> <summary><b>Before/after:</b> callable objects and wrappers</summary> For non-function callables, the annotations now come from the source of the *effective* signature: `__call__` for callable objects, and the wrapped function for wrappers (`__wrapped__` / `__signature__`): ```python class MyCallableTool: def __call__(self, query: str, runtime: ToolRuntime) -> str: return query tool = StructuredTool.from_function( func=MyCallableTool(), name="my_tool", description="Echo the query.", args_schema=InputSchema, ) ``` | | Behavior | |---|---| | **Before** | annotations read from the wrong callable (or left as unresolved strings) → `runtime` dropped | | **After** | annotations resolved from `__call__` / the unwrapped function → `runtime` injected correctly | </details> <details> <summary><b>Unchanged:</b> <code>functools.partial</code> with an already-bound injected arg</summary> A `partial` that already binds an injected argument keeps its effective signature — the bound parameter is absent, so nothing is re-injected over it: ```python from functools import partial def fn(x: int, runtime: ToolRuntime, 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, ) ``` **Before & after:** `runtime` is already bound by the `partial` → excluded from the signature → the bound value is used as-is </details> Co-authored-by: Soban Shankar <[email protected]>
1 parent 9984a87 commit 5c3538e

4 files changed

Lines changed: 732 additions & 22 deletions

File tree

‎libs/core/langchain_core/tools/base.py‎

Lines changed: 204 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@
2020
cast,
2121
get_args,
2222
get_origin,
23-
get_type_hints,
2423
)
2524

2625
import typing_extensions
@@ -38,7 +37,7 @@
3837
from pydantic.v1 import BaseModel as BaseModelV1
3938
from pydantic.v1 import ValidationError as ValidationErrorV1
4039
from pydantic.v1 import validate_arguments as validate_arguments_v1
41-
from typing_extensions import Self, override
40+
from typing_extensions import Self, get_type_hints, override
4241

4342
from langchain_core.callbacks import (
4443
AsyncCallbackManager,
@@ -184,7 +183,7 @@ def _infer_arg_descriptions(
184183
Returns:
185184
A tuple containing the function description and argument descriptions.
186185
"""
187-
annotations = typing.get_type_hints(fn, include_extras=True)
186+
annotations = get_type_hints(fn, include_extras=True)
188187
if parse_docstring:
189188
description, arg_descriptions = _parse_python_function_docstring(
190189
fn, annotations, error_on_invalid_docstring=error_on_invalid_docstring
@@ -730,20 +729,8 @@ def _injected_args_keys(self) -> frozenset[str]:
730729
# rather than by the model, so they must be excluded from the schema and
731730
# re-injected during execution. `StructuredTool` overrides this to
732731
# inspect its wrapped `func`/`coroutine` instead.
733-
#
734-
# Resolve annotations via `get_type_hints` (rather than reading raw
735-
# `signature` annotations) so postponed annotations -- e.g. from
736-
# `from __future__ import annotations` or quoted forward references --
737-
# are recognized. Fall back to the raw annotation per-parameter when a
738-
# hint can't be resolved.
739732
for method in (self._run, self._arun):
740-
params = signature(method).parameters
741-
hints = _get_type_hints(method, include_extras=True) or {}
742-
keys = frozenset(
743-
name
744-
for name, param in params.items()
745-
if _is_injected_arg_type(hints.get(name, param.annotation))
746-
)
733+
keys = _get_injected_args_keys_from_signature(method)
747734
if keys:
748735
return keys
749736
return _EMPTY_SET
@@ -1496,6 +1483,11 @@ def _stringify(content: Any) -> str:
14961483
return str(content)
14971484

14981485

1486+
def _describe_callable(func: Any) -> str:
1487+
"""Return a readable identifier for a callable, for use in log messages."""
1488+
return getattr(func, "__qualname__", None) or repr(func)
1489+
1490+
14991491
def _get_type_hints(
15001492
func: Callable[..., Any], *, include_extras: bool = False
15011493
) -> dict[str, type] | None:
@@ -1514,6 +1506,202 @@ def _get_type_hints(
15141506
try:
15151507
return get_type_hints(func, include_extras=include_extras)
15161508
except Exception:
1509+
_logger.debug(
1510+
"Failed to resolve type hints for %s.",
1511+
_describe_callable(func),
1512+
exc_info=True,
1513+
)
1514+
return None
1515+
1516+
1517+
def _get_class_signature_source(cls: type) -> Callable[..., Any] | None:
1518+
"""Return the callable whose parameters `signature(cls)` describes.
1519+
1520+
A class's own annotations describe its attributes, not its constructor
1521+
parameters, so a class is never its own annotation owner. Constructor
1522+
precedence mirrors `inspect.signature`: a metaclass `__call__` override,
1523+
then a `__new__`/`__init__` the class defines itself, then an inherited one.
1524+
1525+
Args:
1526+
cls: The class being inspected.
1527+
1528+
Returns:
1529+
The constructor whose annotations describe `signature(cls)`, or `None`
1530+
when only slot wrappers inherited from `object` are available.
1531+
"""
1532+
metaclass = type(cls)
1533+
if metaclass is not type:
1534+
metaclass_call = inspect.getattr_static(metaclass, "__call__", None)
1535+
if inspect.isfunction(metaclass_call):
1536+
return metaclass_call
1537+
for attr in ("__new__", "__init__"):
1538+
if attr in cls.__dict__:
1539+
return cast("Callable[..., Any]", getattr(cls, attr))
1540+
for attr in ("__new__", "__init__"):
1541+
# `object.__new__`/`object.__init__` are slot wrappers carrying no
1542+
# useful annotations, so only inherited Python constructors qualify.
1543+
inherited = getattr(cls, attr, None)
1544+
if inspect.isfunction(inherited):
1545+
return cast("Callable[..., Any]", inherited)
1546+
return None
1547+
1548+
1549+
def _get_type_hints_source(
1550+
func: Callable[..., Any],
1551+
) -> Callable[..., Any] | None:
1552+
"""Return the callable that owns the annotations for an effective signature.
1553+
1554+
Unwrapping stops as soon as a callable declares its own `__signature__` (or
1555+
is a bound method), because that declaration -- not the annotations of
1556+
whatever it wraps -- defines the effective signature.
1557+
1558+
Args:
1559+
func: The callable being inspected.
1560+
1561+
Returns:
1562+
The function or method whose annotations describe `signature(func)`, or
1563+
`None` when an explicit `__signature__` supplies the annotations or no
1564+
annotation owner can be identified.
1565+
"""
1566+
func = inspect.unwrap(
1567+
func,
1568+
stop=lambda wrapped: (
1569+
hasattr(wrapped, "__signature__") or inspect.ismethod(wrapped)
1570+
),
1571+
)
1572+
if inspect.ismethod(func):
1573+
return _get_type_hints_source(func.__func__)
1574+
if getattr(func, "__signature__", None) is not None:
1575+
return None
1576+
if isinstance(func, functools.partial):
1577+
return _get_type_hints_source(func.func)
1578+
if inspect.isclass(func):
1579+
constructor = _get_class_signature_source(func)
1580+
if constructor is None:
1581+
return None
1582+
return _get_type_hints_source(constructor)
1583+
if not inspect.isroutine(func):
1584+
callable_obj = cast("Any", func)
1585+
return _get_type_hints_source(cast("Callable[..., Any]", callable_obj.__call__))
1586+
return func
1587+
1588+
1589+
def _get_callable_globals(func: Callable[..., Any]) -> dict[str, Any]:
1590+
"""Return the globals namespace associated with a callable.
1591+
1592+
Explicit `__signature__` objects store annotations separately from a
1593+
callable's `__annotations__`. String annotations on such signatures
1594+
still need the callable's defining globals to be resolved.
1595+
1596+
Args:
1597+
func: The callable whose defining globals to locate.
1598+
1599+
Returns:
1600+
The callable's globals namespace, or an empty `dict` when none can be
1601+
located (e.g. classes, builtins, and other C-implemented callables), in
1602+
which case no string annotation will resolve.
1603+
"""
1604+
if isinstance(func, functools.partial):
1605+
return _get_callable_globals(func.func)
1606+
if inspect.ismethod(func):
1607+
return _get_callable_globals(func.__func__)
1608+
globalns = getattr(func, "__globals__", None)
1609+
if isinstance(globalns, dict):
1610+
return globalns
1611+
if not inspect.isroutine(func) and not inspect.isclass(func):
1612+
callable_obj = cast("Any", func)
1613+
return _get_callable_globals(cast("Callable[..., Any]", callable_obj.__call__))
1614+
return {}
1615+
1616+
1617+
def _get_injected_args_keys_from_signature(func: Callable[..., Any]) -> frozenset[str]:
1618+
"""Identify injected-argument parameters of a callable.
1619+
1620+
Resolve annotations with `get_type_hints` (rather than reading raw
1621+
`signature` annotations) so postponed annotations -- e.g. from
1622+
`from __future__ import annotations` or quoted forward references -- are
1623+
recognized. `get_type_hints` resolves every annotation at once and raises
1624+
on the first failure, so any parameter it leaves uncovered is retried on its
1625+
own: an unrelated unresolvable forward reference must not disable injection
1626+
for parameters whose annotations do resolve. Each distinct string annotation
1627+
is resolved at most once per call, failures included.
1628+
1629+
A *string* annotation naming a type that exists only in the callable's
1630+
defining local scope cannot be resolved here, since only globals are
1631+
available. Such a parameter keeps its raw string annotation, which
1632+
`_is_injected_arg_type` never classifies as injected, so it stays visible to
1633+
the model rather than being injected at call time. Non-string annotations
1634+
are unaffected, since `signature` yields the live object.
1635+
1636+
Args:
1637+
func: The function (or bound method) whose signature to inspect.
1638+
1639+
Returns:
1640+
`frozenset` of parameter names annotated as injected arguments.
1641+
"""
1642+
params = signature(func).parameters
1643+
hint_source = _get_type_hints_source(func)
1644+
hints = (
1645+
_get_type_hints(hint_source, include_extras=True)
1646+
if hint_source is not None
1647+
else None
1648+
) or {}
1649+
globalns: dict[str, Any] | None = None
1650+
resolved_annotations: dict[str, Any] = {}
1651+
keys = set()
1652+
for name, param in params.items():
1653+
annotation = hints.get(name, param.annotation)
1654+
if isinstance(annotation, str):
1655+
if globalns is None:
1656+
globalns = _get_callable_globals(
1657+
func if hint_source is None else hint_source
1658+
)
1659+
if annotation not in resolved_annotations:
1660+
resolved_annotations[annotation] = _resolve_forward_ref(
1661+
annotation, globalns
1662+
)
1663+
resolved = resolved_annotations[annotation]
1664+
if resolved is None:
1665+
_logger.debug(
1666+
"Could not resolve annotation %r for parameter %r of %s; it "
1667+
"will not be treated as an injected argument.",
1668+
annotation,
1669+
name,
1670+
_describe_callable(func),
1671+
)
1672+
else:
1673+
annotation = resolved
1674+
if _is_injected_arg_type(annotation):
1675+
keys.add(name)
1676+
return frozenset(keys)
1677+
1678+
1679+
def _resolve_forward_ref(annotation: str, globalns: dict[str, Any]) -> Any:
1680+
"""Resolve a single string annotation, returning `None` on failure.
1681+
1682+
Uses a temporary annotated function so each annotation can be passed through
1683+
the public `get_type_hints` API independently.
1684+
1685+
Args:
1686+
annotation: The raw string annotation to resolve.
1687+
globalns: The globals namespace to resolve names against.
1688+
1689+
Returns:
1690+
The resolved type, or `None` if the annotation cannot be resolved.
1691+
"""
1692+
1693+
def _annotation_holder() -> None:
1694+
pass
1695+
1696+
_annotation_holder.__annotations__ = {"value": annotation}
1697+
try:
1698+
return get_type_hints(
1699+
_annotation_holder,
1700+
globalns=globalns,
1701+
include_extras=True,
1702+
)["value"]
1703+
except Exception:
1704+
_logger.debug("Failed to resolve annotation %r.", annotation, exc_info=True)
15171705
return None
15181706

15191707

‎libs/core/langchain_core/tools/structured.py‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@
2727
FILTERED_ARGS,
2828
ArgsSchema,
2929
BaseTool,
30+
_get_injected_args_keys_from_signature,
3031
_get_runnable_config_param,
31-
_is_injected_arg_type,
3232
create_schema_from_function,
3333
)
3434
from langchain_core.utils.pydantic import is_basemodel_subclass
@@ -256,11 +256,7 @@ def _injected_args_keys(self) -> frozenset[str]:
256256
fn = self.func or self.coroutine
257257
if fn is None:
258258
return _EMPTY_SET
259-
return frozenset(
260-
k
261-
for k, v in signature(fn).parameters.items()
262-
if _is_injected_arg_type(v.annotation)
263-
)
259+
return _get_injected_args_keys_from_signature(fn)
264260

265261

266262
def _filter_schema_args(func: Callable[..., Any]) -> list[str]:

0 commit comments

Comments
 (0)