The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
fix(core): make `StructuredTool` JSON-serializable (#39631)
Emil F13b1b2feae47
diff --git a/libs/core/langchain_core/tools/structured.py b/libs/core/langchain_core/tools/structured.pyindex 57892a4464..e6d8e769f6 100644--- a/libs/core/langchain_core/tools/structured.py+++ b/libs/core/langchain_core/tools/structured.py@@ -13,7 +13,7 @@ from typing import (Literal,)-from pydantic import Field, SkipValidation+from pydantic import Field, PlainSerializer, SkipValidationfrom typing_extensions import override# Cannot move to TYPE_CHECKING as _run/_arun parameter annotations are needed at runtime@@ -31,10 +31,63 @@ from langchain_core.tools.base import (_get_runnable_config_param,create_schema_from_function,)-from langchain_core.utils.pydantic import is_basemodel_subclass+from langchain_core.utils.pydantic import is_basemodel_subclass, model_json_schemaif TYPE_CHECKING:from langchain_core.messages import ToolCall+ from langchain_core.utils.pydantic import TypeBaseModel+++def _serialize_as_str(value: Any) -> str:+ """Stringify a value that has no JSON form.++ A plain function rather than the `str` builtin: Pydantic < 2.9 inspects the+ serializer's signature, and `inspect.signature` raises for C builtins.+ """+ return str(value)++[email protected]_cache(maxsize=256)+def _model_json_schema(args_schema: TypeBaseModel, _rebuild_token: object) -> Any:+ """Ask a v1 or v2 model class for its JSON schema, or fall back to its repr.++ Cached because pydantic does not memoize this per class and it dominates the+ dump -- 1.10 ms against 0.02 ms for an eight-tool payload -- which tracing+ pays on every run.++ `_rebuild_token` is the class's validator, which `model_rebuild()` replaces.+ Keying on it retires the entry for a rebuilt schema, and for one whose+ forward reference was still unresolved when it was first dumped. Mutating a+ class in place without rebuilding it is not detected.+ """+ try:+ return model_json_schema(args_schema)+ except Exception: # a schema holding an arbitrary type has no JSON schema+ return str(args_schema)+++def _serialize_args_schema(args_schema: ArgsSchema) -> Any:+ """Represent a schema class by its JSON schema when dumping to JSON.++ A Pydantic model class has no JSON form, so leaving it to the default+ serializer raises `PydanticSerializationError`. Its own JSON schema is the+ shape a dict schema already has, and a dict is returned unchanged.+ """+ if isinstance(args_schema, dict):+ return args_schema+ return _model_json_schema(+ args_schema, getattr(args_schema, "__pydantic_validator__", None)+ )+++# Attached to the fields via `Annotated` rather than declared with+# `@field_serializer`, which would take the field's one serializer slot and make+# any subclass that declares its own serializer for the same field fail at class+# creation with `PydanticUserError: Multiple field serializer functions ...`.+_JsonSchemaFallback = PlainSerializer(+ _serialize_args_schema, when_used="json-unless-none"+)+_JsonCallableFallback = PlainSerializer(_serialize_as_str, when_used="json-unless-none")class StructuredTool(BaseTool):@@ -42,15 +95,17 @@ class StructuredTool(BaseTool):description: str = ""- args_schema: Annotated[ArgsSchema, SkipValidation()] = Field(+ args_schema: Annotated[ArgsSchema, SkipValidation(), _JsonSchemaFallback] = Field(..., description="The tool schema.")"""The input arguments' schema."""- func: Callable[..., Any] | None = None+ func: Annotated[Callable[..., Any] | None, _JsonCallableFallback] = None"""The function to run when the tool is called."""- coroutine: Callable[..., Awaitable[Any]] | None = None+ coroutine: Annotated[+ Callable[..., Awaitable[Any]] | None, _JsonCallableFallback+ ] = None"""The asynchronous version of the function."""# --- Runnable ---diff --git a/libs/core/tests/unit_tests/test_tools.py b/libs/core/tests/unit_tests/test_tools.pyindex 63fbfa4368..a143382c39 100644--- a/libs/core/tests/unit_tests/test_tools.py+++ b/libs/core/tests/unit_tests/test_tools.py@@ -31,6 +31,7 @@ from pydantic import (Field,RootModel,ValidationError,+ field_serializer,)from pydantic.errors import PydanticUndefinedAnnotationfrom pydantic.v1 import BaseModel as BaseModelV1@@ -4734,3 +4735,145 @@ def test_tool_call_schema_json_schema_cache_invalidated_on_reassignment() -> Nonnew_schema = new_cls.model_json_schema()assert new_schema is not old_schemaassert new_schema["description"] == "New description for cache test."+++def test_structured_tool_json_dump() -> None:+ """`mode="json"` dumps must not raise on the callable / schema-class fields."""++ @tool+ def write_file(file_path: str, content: str) -> str:+ """Write content to the given path."""+ return "ok"++ dumped = write_file.model_dump(mode="json")+ # Round-trips through the stdlib encoder, i.e. it really is JSON-native.+ json.dumps(dumped)+ schema = cast("type[BaseModel]", write_file.args_schema)+ assert dumped["args_schema"] == schema.model_json_schema()+ assert set(dumped["args_schema"]["properties"]) == {"file_path", "content"}+ assert "write_file" in dumped["func"]+ json.loads(write_file.model_dump_json())++ # Python-mode dumps still hand out the live objects.+ native = write_file.model_dump()+ assert callable(native["func"])+ assert isinstance(native["args_schema"], type)+++def test_structured_tool_json_dump_respects_options() -> None:+ """The field serializers compose with the usual `model_dump` options."""++ @tool+ def write_file(file_path: str, content: str) -> str:+ """Write content to the given path."""+ return "ok"++ assert "description" not in write_file.model_dump(+ mode="json", exclude={"description"}+ )+ assert set(write_file.model_dump(mode="json", include={"name", "func"})) == {+ "name",+ "func",+ }+ # `coroutine` is None here, so `exclude_none` must still drop it.+ assert "coroutine" not in write_file.model_dump(mode="json", exclude_none=True)+++def test_structured_tool_json_dump_keeps_dict_args_schema() -> None:+ """A dict schema is already JSON-native and must be passed through as-is."""+ schema = {"type": "object", "properties": {"a": {"type": "string"}}}+ dict_tool = StructuredTool(+ name="d",+ description="d",+ func=lambda **kwargs: "x",+ args_schema=schema,+ )+ assert dict_tool.model_dump(mode="json")["args_schema"] == schema+++def test_structured_tool_json_dump_uses_v1_schema_method() -> None:+ """A `pydantic.v1` schema class is a supported `args_schema` form too."""++ class V1Schema(BaseModelV1):+ a: str++ v1_tool = StructuredTool(+ name="v", description="d", func=lambda a: "x", args_schema=V1Schema+ )+ assert v1_tool.model_dump(mode="json")["args_schema"] == V1Schema.schema()+++def test_structured_tool_json_dump_falls_back_for_arbitrary_types() -> None:+ """A schema with no JSON schema form must still dump instead of raising."""++ class NotJsonSchemable:+ pass++ @tool+ def uses_injected(+ a: int, conn: Annotated[NotJsonSchemable, InjectedToolArg]+ ) -> str:+ """Doc."""+ return "ok"++ assert uses_injected.model_dump(mode="json")["args_schema"].startswith("<class ")+ # The injected arg never reaches the model, so the tool is still usable.+ assert set(uses_injected.args) == {"a"}+++def test_structured_tool_json_dump_follows_model_rebuild() -> None:+ """A rebuilt schema must not keep serving its pre-rebuild JSON schema."""++ class Renamable(BaseModel):+ a: str++ renamable = StructuredTool(+ name="r", description="d", func=lambda a: "x", args_schema=Renamable+ )+ assert renamable.model_dump(mode="json")["args_schema"]["title"] == "Renamable"++ Renamable.model_config["title"] = "Renamed"+ Renamable.model_rebuild(force=True)+ assert renamable.model_dump(mode="json")["args_schema"]["title"] == "Renamed"++ class Deferred(BaseModel):+ a: "Resolved"++ deferred = StructuredTool(+ name="f", description="d", func=lambda a: "x", args_schema=Deferred+ )+ # Unresolvable so far, so it dumps as a repr like any other schema-less type.+ assert deferred.model_dump(mode="json")["args_schema"].startswith("<class ")++ class Resolved(BaseModel):+ z: int++ Deferred.model_rebuild(force=True)+ assert deferred.model_dump(mode="json")["args_schema"]["properties"] == {+ "a": {"$ref": "#/$defs/Resolved"}+ }+++def test_structured_tool_subclass_can_override_json_serializers() -> None:+ """The JSON fallbacks must not occupy the fields' single serializer slot.++ A subclass declaring its own `@field_serializer` for the same fields used to+ fail at class creation with `PydanticUserError: Multiple field serializer+ functions were defined`.+ """++ class MyTool(StructuredTool):+ @field_serializer("func", when_used="json-unless-none")+ def _my_func_repr(self, func: Any) -> str:+ return "custom-func"++ @field_serializer("args_schema", when_used="json-unless-none")+ def _my_schema_repr(self, args_schema: Any) -> Any:+ return {"custom": "schema"}++ my_tool = MyTool.from_function(+ func=lambda file_path, content: "ok", name="w", description="d"+ )+ dumped = my_tool.model_dump(mode="json")+ assert dumped["func"] == "custom-func"+ assert dumped["args_schema"] == {"custom": "schema"}