Skip to content

Commit 13b1b2f

Browse files
authored
fix(core): make StructuredTool JSON-serializable (#39631)
## Problem `StructuredTool` cannot be dumped to JSON: ```python @tool def write_file(file_path: str, content: str) -> str: """Write content to the given path.""" return "ok" write_file.model_dump(mode="json") # PydanticSerializationError: Unable to serialize unknown type: # <class 'pydantic._internal._model_construction.ModelMetaclass'> ``` `args_schema` holds a Pydantic model class, and `func` / `coroutine` hold callables. None of them have a JSON form. Python-mode `model_dump()` works; only the JSON modes raise. This also costs tracing performance. The [LangSmith SDK](https://github.com/langchain-ai/langsmith-sdk/blob/main/python/langsmith/_internal/_serde.py) catches the error, dumps again in Python mode, and then sends every class and function left in the result through its own `default` hook. ## Change A `PlainSerializer(..., when_used="json-unless-none")` on the three fields. - `args_schema` dumps as its own JSON schema: `model_json_schema()` for a Pydantic v2 class, `schema()` for a v1 one. A dict schema passes through unchanged. A schema holding an arbitrary type has no JSON schema at all, so it falls back to its repr instead of raising. - `func` and `coroutine` dump as strings. - Python-mode dumps are unchanged — still the live schema class and callables. - `exclude` / `include` / `exclude_none` keep working. - Attached with `Annotated`, not `@field_serializer`. A field has only one serializer slot, so `@field_serializer` would break any subclass that declares its own serializer for the same field. - Schema generation is cached per class. Pydantic does not memoize it, and tracing would pay for it on every run. ## Result The dump is JSON-native, and the schema it carries has the same shape a dict `args_schema` already has, so it validates back into a working tool. Measured on the 8 filesystem tools of a deepagents agent, dumped through the LangSmith serializer: | | master | this PR | |---|---|---| | time per dump | 0.119 ms | **0.025 ms** | | payload | 7,706 B | 12,213 B | | objects reaching the SDK's `default` hook | 32 | 8 | The payload grows because `args_schema` now carries the real schema instead of `"<class ...>"`. Only the tool itself still enters the `default` hook; the class and functions inside it no longer do. Without the per-class cache the same dump takes 1.10 ms, so the cache is what makes this a win rather than a regression. ## Why not on `BaseTool` `args_schema` is declared there as well, so `Tool` and custom subclasses hit the same error. But an `Annotated` serializer only applies where the field is declared, and `StructuredTool` redeclares `args_schema` — it would not inherit one from `BaseTool`. ## Tests In `libs/core/tests/unit_tests/test_tools.py`: JSON round trip, Python mode unchanged, dump options respected, dict `args_schema` preserved, Pydantic v1 schema class, arbitrary-type fallback, and a subclass declaring its own serializers for the same fields.
1 parent 3b3b308 commit 13b1b2f

2 files changed

Lines changed: 203 additions & 5 deletions

File tree

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

Lines changed: 60 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
Literal,
1414
)
1515

16-
from pydantic import Field, SkipValidation
16+
from pydantic import Field, PlainSerializer, SkipValidation
1717
from typing_extensions import override
1818

1919
# Cannot move to TYPE_CHECKING as _run/_arun parameter annotations are needed at runtime
@@ -31,26 +31,81 @@
3131
_get_runnable_config_param,
3232
create_schema_from_function,
3333
)
34-
from langchain_core.utils.pydantic import is_basemodel_subclass
34+
from langchain_core.utils.pydantic import is_basemodel_subclass, model_json_schema
3535

3636
if TYPE_CHECKING:
3737
from langchain_core.messages import ToolCall
38+
from langchain_core.utils.pydantic import TypeBaseModel
39+
40+
41+
def _serialize_as_str(value: Any) -> str:
42+
"""Stringify a value that has no JSON form.
43+
44+
A plain function rather than the `str` builtin: Pydantic < 2.9 inspects the
45+
serializer's signature, and `inspect.signature` raises for C builtins.
46+
"""
47+
return str(value)
48+
49+
50+
@functools.lru_cache(maxsize=256)
51+
def _model_json_schema(args_schema: TypeBaseModel, _rebuild_token: object) -> Any:
52+
"""Ask a v1 or v2 model class for its JSON schema, or fall back to its repr.
53+
54+
Cached because pydantic does not memoize this per class and it dominates the
55+
dump -- 1.10 ms against 0.02 ms for an eight-tool payload -- which tracing
56+
pays on every run.
57+
58+
`_rebuild_token` is the class's validator, which `model_rebuild()` replaces.
59+
Keying on it retires the entry for a rebuilt schema, and for one whose
60+
forward reference was still unresolved when it was first dumped. Mutating a
61+
class in place without rebuilding it is not detected.
62+
"""
63+
try:
64+
return model_json_schema(args_schema)
65+
except Exception: # a schema holding an arbitrary type has no JSON schema
66+
return str(args_schema)
67+
68+
69+
def _serialize_args_schema(args_schema: ArgsSchema) -> Any:
70+
"""Represent a schema class by its JSON schema when dumping to JSON.
71+
72+
A Pydantic model class has no JSON form, so leaving it to the default
73+
serializer raises `PydanticSerializationError`. Its own JSON schema is the
74+
shape a dict schema already has, and a dict is returned unchanged.
75+
"""
76+
if isinstance(args_schema, dict):
77+
return args_schema
78+
return _model_json_schema(
79+
args_schema, getattr(args_schema, "__pydantic_validator__", None)
80+
)
81+
82+
83+
# Attached to the fields via `Annotated` rather than declared with
84+
# `@field_serializer`, which would take the field's one serializer slot and make
85+
# any subclass that declares its own serializer for the same field fail at class
86+
# creation with `PydanticUserError: Multiple field serializer functions ...`.
87+
_JsonSchemaFallback = PlainSerializer(
88+
_serialize_args_schema, when_used="json-unless-none"
89+
)
90+
_JsonCallableFallback = PlainSerializer(_serialize_as_str, when_used="json-unless-none")
3891

3992

4093
class StructuredTool(BaseTool):
4194
"""Tool that can operate on any number of inputs."""
4295

4396
description: str = ""
4497

45-
args_schema: Annotated[ArgsSchema, SkipValidation()] = Field(
98+
args_schema: Annotated[ArgsSchema, SkipValidation(), _JsonSchemaFallback] = Field(
4699
..., description="The tool schema."
47100
)
48101
"""The input arguments' schema."""
49102

50-
func: Callable[..., Any] | None = None
103+
func: Annotated[Callable[..., Any] | None, _JsonCallableFallback] = None
51104
"""The function to run when the tool is called."""
52105

53-
coroutine: Callable[..., Awaitable[Any]] | None = None
106+
coroutine: Annotated[
107+
Callable[..., Awaitable[Any]] | None, _JsonCallableFallback
108+
] = None
54109
"""The asynchronous version of the function."""
55110

56111
# --- Runnable ---

‎libs/core/tests/unit_tests/test_tools.py‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
Field,
3232
RootModel,
3333
ValidationError,
34+
field_serializer,
3435
)
3536
from pydantic.errors import PydanticUndefinedAnnotation
3637
from pydantic.v1 import BaseModel as BaseModelV1
@@ -4734,3 +4735,145 @@ def test_tool_call_schema_json_schema_cache_invalidated_on_reassignment() -> Non
47344735
new_schema = new_cls.model_json_schema()
47354736
assert new_schema is not old_schema
47364737
assert new_schema["description"] == "New description for cache test."
4738+
4739+
4740+
def test_structured_tool_json_dump() -> None:
4741+
"""`mode="json"` dumps must not raise on the callable / schema-class fields."""
4742+
4743+
@tool
4744+
def write_file(file_path: str, content: str) -> str:
4745+
"""Write content to the given path."""
4746+
return "ok"
4747+
4748+
dumped = write_file.model_dump(mode="json")
4749+
# Round-trips through the stdlib encoder, i.e. it really is JSON-native.
4750+
json.dumps(dumped)
4751+
schema = cast("type[BaseModel]", write_file.args_schema)
4752+
assert dumped["args_schema"] == schema.model_json_schema()
4753+
assert set(dumped["args_schema"]["properties"]) == {"file_path", "content"}
4754+
assert "write_file" in dumped["func"]
4755+
json.loads(write_file.model_dump_json())
4756+
4757+
# Python-mode dumps still hand out the live objects.
4758+
native = write_file.model_dump()
4759+
assert callable(native["func"])
4760+
assert isinstance(native["args_schema"], type)
4761+
4762+
4763+
def test_structured_tool_json_dump_respects_options() -> None:
4764+
"""The field serializers compose with the usual `model_dump` options."""
4765+
4766+
@tool
4767+
def write_file(file_path: str, content: str) -> str:
4768+
"""Write content to the given path."""
4769+
return "ok"
4770+
4771+
assert "description" not in write_file.model_dump(
4772+
mode="json", exclude={"description"}
4773+
)
4774+
assert set(write_file.model_dump(mode="json", include={"name", "func"})) == {
4775+
"name",
4776+
"func",
4777+
}
4778+
# `coroutine` is None here, so `exclude_none` must still drop it.
4779+
assert "coroutine" not in write_file.model_dump(mode="json", exclude_none=True)
4780+
4781+
4782+
def test_structured_tool_json_dump_keeps_dict_args_schema() -> None:
4783+
"""A dict schema is already JSON-native and must be passed through as-is."""
4784+
schema = {"type": "object", "properties": {"a": {"type": "string"}}}
4785+
dict_tool = StructuredTool(
4786+
name="d",
4787+
description="d",
4788+
func=lambda **kwargs: "x",
4789+
args_schema=schema,
4790+
)
4791+
assert dict_tool.model_dump(mode="json")["args_schema"] == schema
4792+
4793+
4794+
def test_structured_tool_json_dump_uses_v1_schema_method() -> None:
4795+
"""A `pydantic.v1` schema class is a supported `args_schema` form too."""
4796+
4797+
class V1Schema(BaseModelV1):
4798+
a: str
4799+
4800+
v1_tool = StructuredTool(
4801+
name="v", description="d", func=lambda a: "x", args_schema=V1Schema
4802+
)
4803+
assert v1_tool.model_dump(mode="json")["args_schema"] == V1Schema.schema()
4804+
4805+
4806+
def test_structured_tool_json_dump_falls_back_for_arbitrary_types() -> None:
4807+
"""A schema with no JSON schema form must still dump instead of raising."""
4808+
4809+
class NotJsonSchemable:
4810+
pass
4811+
4812+
@tool
4813+
def uses_injected(
4814+
a: int, conn: Annotated[NotJsonSchemable, InjectedToolArg]
4815+
) -> str:
4816+
"""Doc."""
4817+
return "ok"
4818+
4819+
assert uses_injected.model_dump(mode="json")["args_schema"].startswith("<class ")
4820+
# The injected arg never reaches the model, so the tool is still usable.
4821+
assert set(uses_injected.args) == {"a"}
4822+
4823+
4824+
def test_structured_tool_json_dump_follows_model_rebuild() -> None:
4825+
"""A rebuilt schema must not keep serving its pre-rebuild JSON schema."""
4826+
4827+
class Renamable(BaseModel):
4828+
a: str
4829+
4830+
renamable = StructuredTool(
4831+
name="r", description="d", func=lambda a: "x", args_schema=Renamable
4832+
)
4833+
assert renamable.model_dump(mode="json")["args_schema"]["title"] == "Renamable"
4834+
4835+
Renamable.model_config["title"] = "Renamed"
4836+
Renamable.model_rebuild(force=True)
4837+
assert renamable.model_dump(mode="json")["args_schema"]["title"] == "Renamed"
4838+
4839+
class Deferred(BaseModel):
4840+
a: "Resolved"
4841+
4842+
deferred = StructuredTool(
4843+
name="f", description="d", func=lambda a: "x", args_schema=Deferred
4844+
)
4845+
# Unresolvable so far, so it dumps as a repr like any other schema-less type.
4846+
assert deferred.model_dump(mode="json")["args_schema"].startswith("<class ")
4847+
4848+
class Resolved(BaseModel):
4849+
z: int
4850+
4851+
Deferred.model_rebuild(force=True)
4852+
assert deferred.model_dump(mode="json")["args_schema"]["properties"] == {
4853+
"a": {"$ref": "#/$defs/Resolved"}
4854+
}
4855+
4856+
4857+
def test_structured_tool_subclass_can_override_json_serializers() -> None:
4858+
"""The JSON fallbacks must not occupy the fields' single serializer slot.
4859+
4860+
A subclass declaring its own `@field_serializer` for the same fields used to
4861+
fail at class creation with `PydanticUserError: Multiple field serializer
4862+
functions were defined`.
4863+
"""
4864+
4865+
class MyTool(StructuredTool):
4866+
@field_serializer("func", when_used="json-unless-none")
4867+
def _my_func_repr(self, func: Any) -> str:
4868+
return "custom-func"
4869+
4870+
@field_serializer("args_schema", when_used="json-unless-none")
4871+
def _my_schema_repr(self, args_schema: Any) -> Any:
4872+
return {"custom": "schema"}
4873+
4874+
my_tool = MyTool.from_function(
4875+
func=lambda file_path, content: "ok", name="w", description="d"
4876+
)
4877+
dumped = my_tool.model_dump(mode="json")
4878+
assert dumped["func"] == "custom-func"
4879+
assert dumped["args_schema"] == {"custom": "schema"}

0 commit comments

Comments
 (0)