diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 03634de4c5d..9a1f142cfb7 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -513,6 +513,8 @@ def _annotation_includes_function_invocation_context(annotation: Any) -> bool: _ToolDescriptionFormat: TypeAlias = _ToolParameterFormat | Mapping[str, _ToolParameterFormat] _NormalizedToolDescriptionFormat: TypeAlias = _ToolParameterFormat | dict[str, _ToolParameterFormat] _TOOL_DESCRIPTION_FORMAT_ERROR = "tool_description_format must be 'compact', 'json', or a tool-name mapping." +# model_dump's fallback (str for values JSON mode doesn't know) only exists on newer Pydantic 2 versions. +_MODEL_DUMP_HAS_FALLBACK = "fallback" in inspect.signature(BaseModel.model_dump).parameters def _normalize_tool_description_format( # pyright: ignore[reportUnusedFunction] @@ -1430,13 +1432,35 @@ def _make_dumpable(value: Any) -> Any: if isinstance(value, Content): return value.to_dict(exclude={"raw_representation", "additional_properties"}) if isinstance(value, BaseModel): - return value.model_dump() + return FunctionTool._dump_model(value) if hasattr(value, "to_dict"): return value.to_dict() if hasattr(value, "text") and isinstance(value.text, str): return value.text return value + @staticmethod + def _dump_model(model: BaseModel) -> Any: + """Dump a Pydantic model in JSON mode. + + JSON mode applies enum, datetime and UUID encoding and JSON-only serializers, and values it + doesn't know become their str() form. Pydantic versions without ``model_dump(..., fallback=...)`` + get the same output from ``to_jsonable_python(..., serialize_unknown=True)``. If Pydantic still + can't dump the model (bytes that aren't valid UTF-8, a reference cycle), a placeholder is returned, + so no part of the model is sent without its serializers and exclusions. + """ + try: + if _MODEL_DUMP_HAS_FALLBACK: + return model.model_dump(mode="json", fallback=str) + return to_jsonable_python(model, by_alias=False, serialize_unknown=True) + except Exception as exception: + logger.warning( + "Replacing %s in the tool result with a placeholder: it can't be serialized as JSON (%s).", + type(model).__name__, + type(exception).__name__, + ) + return f"[{type(model).__name__} could not be serialized as JSON]" + @staticmethod def parse_result(result: Any) -> list[Content]: """Convert a raw function return value to a list of Content items. diff --git a/python/packages/core/tests/core/test_types.py b/python/packages/core/tests/core/test_types.py index f8547c1b7e5..854840ffeb1 100644 --- a/python/packages/core/tests/core/test_types.py +++ b/python/packages/core/tests/core/test_types.py @@ -4705,6 +4705,232 @@ def test_parse_result_nested_pydantic_model(): assert "18.0" in parsed[0].text or "18" in parsed[0].text # type: ignore[operator] # pyrefly: ignore[not-iterable] # ty: ignore[unsupported-operator] +def test_parse_result_pydantic_model_uses_json_mode(): + """Enum and datetime fields are serialized the way Pydantic writes them to JSON.""" + from enum import Enum + + class Status(Enum): + OPEN = "open" + + class Ticket(BaseModel): + status: Status + created: datetime + + parsed = FunctionTool.parse_result(Ticket(status=Status.OPEN, created=datetime(2024, 1, 1, 12))) + + assert json.loads(parsed[0].text) == {"status": "open", "created": "2024-01-01T12:00:00"} # type: ignore[arg-type] # pyrefly: ignore[bad-argument-type] # ty: ignore[invalid-argument-type] + + +class _UnknownValue: + """A value Pydantic JSON mode doesn't know how to encode.""" + + def __str__(self) -> str: + return "unknown-1" + + +@fixture(params=["model_dump", "to_jsonable_python"]) +def pydantic_json_dump(request: pytest.FixtureRequest, monkeypatch: pytest.MonkeyPatch) -> None: + """Run a test with model_dump(fallback=str) and with the path for Pydantic versions without it.""" + from agent_framework import _tools + + if request.param == "model_dump" and not _tools._MODEL_DUMP_HAS_FALLBACK: + pytest.skip("model_dump has no fallback parameter on this Pydantic version") + monkeypatch.setattr(_tools, "_MODEL_DUMP_HAS_FALLBACK", request.param == "model_dump") + + +def _parse_result_json(result: Any) -> Any: + text = FunctionTool.parse_result(result)[0].text + assert text is not None + return json.loads(text) + + +@mark.usefixtures("pydantic_json_dump") +def test_parse_result_pydantic_model_with_arbitrary_type(): + """Only the value Pydantic cannot serialize to JSON becomes str; the rest stays in JSON mode.""" + from pydantic import field_serializer + + class Result(BaseModel): + model_config = {"arbitrary_types_allowed": True} + + handle: _UnknownValue + created: datetime + token: str + api_key: str = Field(exclude=True) + + @field_serializer("token", when_used="json") + def _redact(self, value: str) -> str: + return "***" + + result = Result(handle=_UnknownValue(), created=datetime(2024, 1, 1, 12), token="secret", api_key="key") + + assert _parse_result_json(result) == {"handle": "unknown-1", "created": "2024-01-01T12:00:00", "token": "***"} + + +@mark.usefixtures("pydantic_json_dump") +def test_parse_result_pydantic_model_serializer_output_is_kept(): + """A wrapping model serializer keeps its structure when a field needs the str fallback.""" + from pydantic import model_serializer + + class Result(BaseModel): + model_config = {"arbitrary_types_allowed": True} + + count: int + handle: _UnknownValue + + @model_serializer(mode="wrap") + def _wrap(self, handler: Any) -> dict[str, Any]: + return {"payload": handler(self)} + + assert _parse_result_json(Result(count=1, handle=_UnknownValue())) == { + "payload": {"count": 1, "handle": "unknown-1"} + } + + +@mark.usefixtures("pydantic_json_dump") +def test_parse_result_nested_pydantic_computed_field_uses_original_values(): + """A nested computed field reads the original value, not its str() fallback.""" + from pydantic import computed_field + + class Inner(BaseModel): + model_config = {"arbitrary_types_allowed": True} + + handle: _UnknownValue + + @computed_field # type: ignore[prop-decorator] + @property + def handle_type(self) -> str: + return type(self.handle).__name__ + + class Outer(BaseModel): + inner: Inner + + assert _parse_result_json(Outer(inner=Inner(handle=_UnknownValue()))) == { + "inner": {"handle": "unknown-1", "handle_type": "_UnknownValue"} + } + + +@mark.usefixtures("pydantic_json_dump") +def test_parse_result_pydantic_bytes_field_serializer_gets_original_bytes(): + """A bytes field serializer receives the original bytes when a sibling needs the str fallback.""" + from pydantic import field_serializer + + class Result(BaseModel): + model_config = {"arbitrary_types_allowed": True} + + raw: bytes + handle: _UnknownValue + + @field_serializer("raw") + def _hex(self, value: bytes) -> str: + return value.hex() + + assert _parse_result_json(Result(raw=b"\x01\xff", handle=_UnknownValue())) == { + "raw": "01ff", + "handle": "unknown-1", + } + + +@mark.usefixtures("pydantic_json_dump") +def test_parse_result_pydantic_excluded_cyclic_field_is_not_visited(): + """Excluded fields, including one holding a reference cycle, stay out of the tool result.""" + + class Result(BaseModel): + model_config = {"arbitrary_types_allowed": True} + + handle: _UnknownValue + cache: Any = Field(default=None, exclude=True) + api_key: str = Field(exclude=True) + + result = Result(handle=_UnknownValue(), api_key="key") + result.cache = result + + assert _parse_result_json(result) == {"handle": "unknown-1"} + + +@mark.usefixtures("pydantic_json_dump") +def test_parse_result_nested_pydantic_dataclass_keeps_exclusions(): + """A nested Pydantic dataclass keeps its exclusions; only the unknown value becomes str.""" + from pydantic.dataclasses import dataclass as pydantic_dataclass + + @pydantic_dataclass(config={"arbitrary_types_allowed": True}) + class Inner: + handle: _UnknownValue + api_key: str = Field(default="key", exclude=True) + + class Outer(BaseModel): + model_config = {"arbitrary_types_allowed": True} + + inner: Inner + + assert _parse_result_json(Outer(inner=Inner(handle=_UnknownValue()))) == {"inner": {"handle": "unknown-1"}} + + +@mark.usefixtures("pydantic_json_dump") +def test_parse_result_pydantic_declared_field_types_are_kept(): + """A subclass in a field declared as its base keeps its subclass-only fields out.""" + + class Public(BaseModel): + model_config = {"arbitrary_types_allowed": True} + + handle: _UnknownValue + + class Secret(Public): + api_key: str + + class Envelope(BaseModel): + item: Public + items: list[Public] + by_name: dict[str, Public] + + secret = Secret(handle=_UnknownValue(), api_key="key") + expected_item = {"handle": "unknown-1"} + + assert _parse_result_json(Envelope(item=secret, items=[secret], by_name={"a": secret})) == { + "item": expected_item, + "items": [expected_item], + "by_name": {"a": expected_item}, + } + + +@mark.usefixtures("pydantic_json_dump") +def test_parse_result_pydantic_model_with_non_utf8_bytes_is_replaced(): + """A model with bytes that aren't valid UTF-8 is replaced by a placeholder, so nothing in it leaks.""" + from pydantic import field_serializer + + class Inner(BaseModel): + data: bytes + token: str + api_key: str = Field(exclude=True) + + @field_serializer("token", when_used="json") + def _redact(self, value: str) -> str: + return "***" + + class Outer(BaseModel): + inner: Inner + + inner = Inner(data=b"\xff\xfe", token="secret", api_key="key") + placeholder = "[Outer could not be serialized as JSON]" + + assert FunctionTool.parse_result(Outer(inner=inner))[0].text == placeholder + assert _parse_result_json([Outer(inner=inner), {"ok": 1}]) == [placeholder, {"ok": 1}] + + +@mark.usefixtures("pydantic_json_dump") +def test_parse_result_pydantic_model_with_reference_cycle_is_replaced(): + """A model with a reference cycle in a serialized field is replaced by a placeholder.""" + + class Node(BaseModel): + name: str + next: Any = None + api_key: str = Field(default="key", exclude=True) + + node = Node(name="a") + node.next = node + + assert FunctionTool.parse_result(node)[0].text == "[Node could not be serialized as JSON]" + + # region FunctionTool.parse_result with MCP TextContent-like objects