fix: handle Pydantic models in safe_json_serialize for tool tracing

safe_json_serialize silently replaced Pydantic BaseModel tool return values
with "<not serializable>" in trace spans, because json.dumps cannot serialize
Pydantic models natively. Tools returning a BaseModel (wrapped by ADK as
{"result": <BaseModel>}) had their traced output dropped, degrading
observability integrations (e.g. Langfuse, Phoenix) even though the tool itself
ran fine.

The json.dumps default handler now serializes BaseModel instances via
model_dump(mode="json") before falling back to "<not serializable>", consistent
with how serialize_content already handles Pydantic objects. Adds unit tests
covering plain dicts, nested and top-level Pydantic models, and the
non-serializable fallback.

Closes #4629

Co-authored-by: Haran Rajkumar <haranrk@google.com>
PiperOrigin-RevId: 935041717

Author: 2 people

src/google/adk/telemetry/_serialization.py

@@ -26,17 +26,24 @@
 def safe_json_serialize(obj: object) -> str:
   """Convert any Python object to a JSON-serializable type or string.
 
+  Handles Pydantic `BaseModel` instances (common as tool return types) by
+  calling `model_dump(mode="json")` before JSON encoding.
+
   Args:
     obj: The object to serialize.
 
   Returns:
     The JSON-serialized object string or `<not serializable>` if the object
     cannot be serialized.
   """
+
+  def _default(o: object) -> object:
+    if isinstance(o, BaseModel):
+      return o.model_dump(mode="json")
+    return "<not serializable>"
+
   try:
-    return json.dumps(
-        obj, ensure_ascii=False, default=lambda o: "<not serializable>"
-    )
+    return json.dumps(obj, ensure_ascii=False, default=_default)
   except (TypeError, ValueError, OverflowError, RecursionError):
     return "<not serializable>"
 

tests/unittests/telemetry/test_spans.py

@@ -57,6 +57,7 @@
 from opentelemetry.semconv._incubating.attributes.gen_ai_attributes import GEN_AI_USAGE_INPUT_TOKENS
 from opentelemetry.semconv._incubating.attributes.gen_ai_attributes import GEN_AI_USAGE_OUTPUT_TOKENS
 from opentelemetry.semconv._incubating.attributes.user_attributes import USER_ID
+from pydantic import BaseModel
 import pytest
 
 try:
@@ -1787,3 +1788,57 @@ def test_build_llm_request_for_trace_excludes_live_http_clients():
   json.dumps(result)
   assert 'httpx_async_client' not in result['config'].get('http_options', {})
   assert result['config']['temperature'] == 0.1
+
+
+# ---------------------------------------------------------------------------
+# safe_json_serialize tests
+# ---------------------------------------------------------------------------
+
+
+class _SampleToolResult(BaseModel):
+  query: str
+  total: int
+  items: list[str] = []
+
+
+class _NestedModel(BaseModel):
+  inner: _SampleToolResult
+
+
+def test_safe_json_serialize_plain_dict():
+  """Plain dicts serialize normally."""
+  result = safe_json_serialize({'key': 'value', 'num': 42})
+  assert json.loads(result) == {'key': 'value', 'num': 42}
+
+
+def test_safe_json_serialize_pydantic_model_in_dict():
+  """Pydantic models nested in a dict are serialized via model_dump."""
+  model = _SampleToolResult(query='test', total=2, items=['a', 'b'])
+  result = safe_json_serialize({'result': model})
+  parsed = json.loads(result)
+  assert parsed == {
+      'result': {'query': 'test', 'total': 2, 'items': ['a', 'b']}
+  }
+
+
+def test_safe_json_serialize_nested_pydantic_model():
+  """Nested Pydantic models are fully serialized."""
+  inner = _SampleToolResult(query='q', total=0, items=[])
+  outer = _NestedModel(inner=inner)
+  result = safe_json_serialize({'result': outer})
+  parsed = json.loads(result)
+  assert parsed['result']['inner'] == {'query': 'q', 'total': 0, 'items': []}
+
+
+def test_safe_json_serialize_top_level_pydantic_model():
+  """A top-level Pydantic model (not wrapped in a dict) is serialized."""
+  model = _SampleToolResult(query='direct', total=1, items=['x'])
+  result = safe_json_serialize(model)
+  parsed = json.loads(result)
+  assert parsed == {'query': 'direct', 'total': 1, 'items': ['x']}
+
+
+def test_safe_json_serialize_non_serializable_fallback():
+  """Objects that are neither JSON-native nor Pydantic fall back gracefully."""
+  result = safe_json_serialize({'value': object()})
+  assert '<not serializable>' in result