Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 25 additions & 1 deletion python/packages/core/agent_framework/_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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.
Expand Down
226 changes: 226 additions & 0 deletions python/packages/core/tests/core/test_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down
Loading