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
<165470467+Soban-2004@users.noreply.github.com>
fixes#39099
We currently allow forward refs in pydantic v2 schemas upon creation:
```python
class Container(BaseModel):
rows: list["Row"] = [] # "Row" is declared below, after the tool is decorated
@tool
def my_tool(container: Container):
"""A tool whose schema depends on a forward reference that is not resolvable yet."""
return "ok"
class Row(BaseModel):
name: str
```
When it comes time to introspect the tool schema (notably in
`count_tokens_approximately` and `convert_to_openai_tool`), we rely on
[signature
introspection](https://github.com/langchain-ai/langchain/blob/943dd700ef7c33e3f1f21d3e280c9c249b88259c/libs/core/langchain_core/tools/base.py#L1654-L1661)
to extract the tool's input schema. If that contains invalid forward
references, there's no schema fields to extract which results in an
empty dict:
<details>
<summary>Invalid forward reference MRE</summary>
```python
from __future__ import annotations
import inspect
from pydantic import BaseModel, Field
from pydantic.errors import PydanticUndefinedAnnotation
from langchain_core.tools.base import get_all_basemodel_annotations
from langchain_core.utils.pydantic import _create_subset_model, model_json_schema
class Container(BaseModel):
"""A model with a nested forward reference that can never resolve."""
rows: list["UndefinedRow"] = Field(default_factory=list)
def main() -> None:
"""Print the field-selection inputs and their zero-field subset result."""
selected_annotations = get_all_basemodel_annotations(Container)
subset_schema = _create_subset_model(
"ContainerSubset",
Container,
list(selected_annotations),
fn_description=Container.__doc__,
)
print(f"Pydantic complete: {Container.__pydantic_complete__}")
print(f"Pydantic fields: {list(Container.model_fields)}")
print(f"inspect.signature: {inspect.signature(Container)}")
print(f"Fields selected by get_all_basemodel_annotations: {selected_annotations}")
print(f"Subset properties: {model_json_schema(subset_schema)['properties']}")
if __name__ == "__main__":
main()
```
```output
Pydantic complete: False
Pydantic fields: ['rows']
inspect.signature: (**data: 'Any') -> 'None'
Fields selected by get_all_basemodel_annotations: {}
Subset properties: {}
```
</details>
<details>
<summary>Valid forward reference MRE</summary>
```python
from __future__ import annotations
import inspect
from pydantic import BaseModel, Field
from pydantic.errors import PydanticUndefinedAnnotation
from langchain_core.tools.base import get_all_basemodel_annotations
from langchain_core.utils.pydantic import _create_subset_model, model_json_schema
class Container(BaseModel):
"""A model with a nested forward reference that can never resolve."""
rows: list["UndefinedRow"] = Field(default_factory=list)
class UndefinedRow(BaseModel):
name: str = Field()
def main() -> None:
"""Print the field-selection inputs and their zero-field subset result."""
Container.model_rebuild()
selected_annotations = get_all_basemodel_annotations(Container)
subset_schema = _create_subset_model(
"ContainerSubset",
Container,
list(selected_annotations),
fn_description=Container.__doc__,
)
print(f"Pydantic complete: {Container.__pydantic_complete__}")
print(f"Pydantic fields: {list(Container.model_fields)}")
print(f"inspect.signature: {inspect.signature(Container)}")
print(f"Fields selected by get_all_basemodel_annotations: {selected_annotations}")
print(f"Subset properties: {model_json_schema(subset_schema)['properties']}")
if __name__ == "__main__":
main()
```
```output
Pydantic complete: True
Pydantic fields: ['rows']
inspect.signature: (*, rows: list[__main__.UndefinedRow] = <factory>) -> None
Fields selected by get_all_basemodel_annotations: {'rows': list[__main__.UndefinedRow]}
Subset properties: {'rows': {'items': {'$ref': '#/$defs/UndefinedRow'}, 'title': 'Rows', 'type': 'array'}}
```
</details>
---
The fix is to
* at introspection time, resolve forward references using
`.model_rebuild()` that raises a pydantic exception if forward
references cant be resolved
* i'm also widening a pydantic utility to use a type guard instead of
having to use bool + cast
I'm intentionally not rebuilding pydantic v1 schemas in the same way
since
* forward references are specified by explicitly passing names into
`update_forward_refs`
* pydantic v1 is old news
Runnable snapshots currently embed the exact `langchain-core` version,
forcing unrelated snapshot rewrites during every release. Normalize only
the current `VERSION` to a stable placeholder before comparison, so
missing or stale version metadata still fails.
Made by [Open
SWE](https://openswe.vercel.app/agents/bfd72574-359e-544e-dbf5-78f8bae3636a)
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
This PR sends gateway metadata information (if present in the client
response) as metadata for the llm invocation.
Requires changes corresponding changes in the ChatModel implementations
(e.g., ChatOpenAI) so gateway metadata is picked up from the gateway
response headers.
---------
Signed-off-by: Eugene Yurtsev <eugene@langchain.dev>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: eyurtsev <3205522+eyurtsev@users.noreply.github.com>
This PR fixes the documentation issue reported in #39683: corrects
`capabilites` to `capabilities` in `README.md`.
Fixes#39683
Fixes #
---
Read the full contributing guidelines:
https://docs.langchain.com/oss/python/contributing/overview
> **All contributions must be in English.** See the [language
policy](https://docs.langchain.com/oss/python/contributing/overview#language-policy).
If you paste a large clearly AI generated description here your PR may
be IGNORED or CLOSED!
Thank you for contributing to LangChain! Follow these steps to have your
pull request considered as ready for review.
1. PR title: Should follow the format: TYPE(SCOPE): DESCRIPTION
- Examples:
- fix(anthropic): resolve flag parsing error
- feat(core): add multi-tenant support
- test(openai): update API usage tests
- Allowed TYPE and SCOPE values:
https://github.com/langchain-ai/langchain/blob/master/.github/workflows/pr_lint.yml#L15-L33
2. PR description:
- Write 1-2 sentences that make the change easy to understand: who
benefits, what problem they had, and how this solves it. Prefer a simple
user story over a long summary.
- The `Fixes #xx` line at the top is **required** for external
contributions — update the issue number and keep the keyword. This links
your PR to the approved issue and auto-closes it on merge.
- If there are any breaking changes, please clearly describe them.
- If this PR depends on another PR being merged first, please include
"Depends on #PR_NUMBER" in the description.
## Release note
3. Run `make format`, `make lint` and `make test` from the root of the
package(s) you've modified.
- We will not consider a PR unless these three are passing in CI.
4. How did you verify your code works?
Additional guidelines:
- All external PRs must link to an issue or discussion where a solution
has been approved by a maintainer, and you must be assigned to that
issue. PRs without prior approval will be closed.
- PRs should not touch more than one package unless absolutely
necessary.
- Do not update the `uv.lock` files or add dependencies to
`pyproject.toml` files (even optional ones) unless you have explicit
permission to do so by a maintainer.
## Social handles (optional)
Twitter: @
LinkedIn: https://linkedin.com/in/Fixes#39683
ccurme