Serialize structured realtime tool outputs as JSON (#2608)

Author: lavish0000

src/agents/realtime/session.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 import asyncio
+import dataclasses
 import inspect
 import json
 from collections.abc import AsyncIterator
 from typing import Any, cast
 
+from pydantic import BaseModel
 from typing_extensions import assert_never
 
 from ..agent import Agent
@@ -67,6 +69,29 @@
 REJECTION_MESSAGE = DEFAULT_APPROVAL_REJECTION_MESSAGE
 
 
+def _serialize_tool_output(output: Any) -> str:
+    """Serialize structured tool outputs to JSON when possible."""
+    if isinstance(output, str):
+        return output
+    if isinstance(output, BaseModel):
+        try:
+            output = output.model_dump(mode="json")
+        except Exception:
+            try:
+                output = output.model_dump()
+            except Exception:
+                return str(output)
+    elif dataclasses.is_dataclass(output) and not isinstance(output, type):
+        try:
+            output = dataclasses.asdict(output)
+        except Exception:
+            return str(output)
+    try:
+        return json.dumps(output, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return str(output)
+
+
 class RealtimeSession(RealtimeModelListener):
     """A connection to a realtime model. It streams events from the model to you, and allows you to
     send messages and audio to the model.
@@ -610,7 +635,9 @@ async def _handle_tool_call(
 
             await self._model.send_event(
                 RealtimeModelSendToolOutput(
-                    tool_call=event, output=str(result), start_response=True
+                    tool_call=event,
+                    output=_serialize_tool_output(result),
+                    start_response=True,
                 )
             )
 

tests/realtime/test_session.py

@@ -1,8 +1,12 @@
 import asyncio
+import dataclasses
+import json
+import threading
 from typing import Any, cast
 from unittest.mock import AsyncMock, Mock, PropertyMock, patch
 
 import pytest
+from pydantic import BaseModel, ConfigDict
 
 from agents.exceptions import UserError
 from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail
@@ -55,7 +59,7 @@
     RealtimeModelSendSessionUpdate,
     RealtimeModelSendUserInput,
 )
-from agents.realtime.session import REJECTION_MESSAGE, RealtimeSession
+from agents.realtime.session import REJECTION_MESSAGE, RealtimeSession, _serialize_tool_output
 from agents.tool import FunctionTool
 from agents.tool_context import ToolContext
 
@@ -1364,7 +1368,7 @@ async def test_tool_call_with_custom_call_id(self, mock_model, mock_agent, mock_
 
     @pytest.mark.asyncio
     async def test_tool_result_conversion_to_string(self, mock_model, mock_agent):
-        """Test that tool results are converted to strings for model output"""
+        """Test that structured tool results are serialized to JSON for model output."""
         # Create tool that returns non-string result
         tool = _set_default_timeout_fields(Mock(spec=FunctionTool))
         tool.name = "test_function"
@@ -1381,10 +1385,83 @@ async def test_tool_result_conversion_to_string(self, mock_model, mock_agent):
 
         await session._handle_tool_call(tool_call_event)
 
-        # Verify result was converted to string
+        # Verify result was serialized to JSON
         sent_call, sent_output, _ = mock_model.sent_tool_outputs[0]
         assert isinstance(sent_output, str)
-        assert sent_output == "{'result': 'data', 'count': 42}"
+        assert sent_output == json.dumps({"result": "data", "count": 42})
+
+    @pytest.mark.asyncio
+    async def test_tool_result_conversion_serializes_pydantic_models(self, mock_model, mock_agent):
+        """Test that pydantic tool results are serialized to JSON for model output."""
+
+        class ToolResult(BaseModel):
+            name: str
+            score: int
+
+        tool = _set_default_timeout_fields(Mock(spec=FunctionTool))
+        tool.name = "test_function"
+        tool.on_invoke_tool = AsyncMock(return_value=ToolResult(name="demo", score=7))
+        tool.needs_approval = False
+
+        mock_agent.get_all_tools.return_value = [tool]
+
+        session = RealtimeSession(mock_model, mock_agent, None)
+
+        tool_call_event = RealtimeModelToolCallEvent(
+            name="test_function", call_id="call_pydantic_conversion", arguments="{}"
+        )
+
+        await session._handle_tool_call(tool_call_event)
+
+        _sent_call, sent_output, _ = mock_model.sent_tool_outputs[0]
+        assert sent_output == json.dumps({"name": "demo", "score": 7})
+
+    def test_serialize_tool_output_ignores_non_pydantic_model_dump_objects(self) -> None:
+        class FakeModelDump:
+            def model_dump(self, *_args: Any, **_kwargs: Any) -> dict[str, Any]:
+                raise AssertionError("non-pydantic objects should not use model_dump")
+
+            def __str__(self) -> str:
+                return "fake-model-dump-object"
+
+        assert _serialize_tool_output(FakeModelDump()) == "fake-model-dump-object"
+
+    def test_serialize_tool_output_falls_back_when_pydantic_json_dump_fails(self) -> None:
+        class FallbackModel(BaseModel):
+            model_config = ConfigDict(arbitrary_types_allowed=True)
+
+            payload: object
+
+            def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
+                if kwargs.get("mode") == "json":
+                    raise ValueError("json mode failed")
+                return {"payload": "ok"}
+
+        assert _serialize_tool_output(FallbackModel(payload=object())) == json.dumps(
+            {"payload": "ok"}
+        )
+
+    def test_serialize_tool_output_returns_string_when_pydantic_dump_fails(self) -> None:
+        class BrokenModel(BaseModel):
+            value: int
+
+            def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
+                raise ValueError("dump failed")
+
+            def __str__(self) -> str:
+                return "broken-model"
+
+        assert _serialize_tool_output(BrokenModel(value=1)) == "broken-model"
+
+    def test_serialize_tool_output_returns_string_when_dataclass_asdict_fails(self) -> None:
+        @dataclasses.dataclass
+        class BrokenDataclass:
+            lock: Any
+
+            def __str__(self) -> str:
+                return "broken-dataclass"
+
+        assert _serialize_tool_output(BrokenDataclass(lock=threading.Lock())) == "broken-dataclass"
 
     @pytest.mark.asyncio
     async def test_mixed_tool_types_filtering(self, mock_model, mock_agent):