fix(sessions): prevent PydanticSerializationError when session state contains non-serializable objects

Merge google#4748

## Summary

Fixes google#4724

`DatabaseSessionService.append_event` crashes with `PydanticSerializationError: Unable to serialize unknown type: <class 'function'>` when session state contains non-JSON-serializable objects (e.g. Python callables stored via MCP tool callbacks).

**Root cause:** `EventActions.state_delta` is typed as `dict[str, object]` and `agent_state` as `dict[str, Any]` — both accept arbitrary Python objects. When `StorageEvent.from_event()` calls `event.model_dump(mode="json")`, Pydantic cannot serialize callables and raises `PydanticSerializationError`, crashing the agent.

**Fix:** Add Pydantic `@field_serializer` decorators for `state_delta` and `agent_state` in `EventActions`. A helper `_make_json_serializable()` recursively walks the dict/list structure and replaces any non-JSON-serializable leaf value with a descriptive string (`<not serializable: typename>`), so the event is safely persisted without crashing and without losing any serializable data.

## Changes

- `src/google/adk/events/event_actions.py`
  - Added `_make_json_serializable()` helper
  - Added `@field_serializer('state_delta')` on `EventActions`
  - Added `@field_serializer('agent_state')` on `EventActions`

## Test plan

- [ ] Existing unit tests pass
- [ ] Create an agent with MCP tools using `DatabaseSessionService`; confirm `append_event` no longer crashes when state contains callable values
- [ ] Confirm serializable state values are persisted correctly (no regression)

Co-authored-by: Haran Rajkumar <haranrk@google.com>
COPYBARA_INTEGRATE_REVIEW=google#4748 from Raman369AI:fix/database-session-pydantic-serialization-error f2e73e9
PiperOrigin-RevId: 944235500

Author: 2 people

src/google/adk/events/event_actions.py

@@ -14,7 +14,9 @@
 
 from __future__ import annotations
 
+import logging
 from typing import Any
+from typing import cast
 from typing import Optional
 from typing import Union
 
@@ -23,13 +25,31 @@
 from pydantic import BaseModel
 from pydantic import ConfigDict
 from pydantic import Field
+from pydantic import field_serializer
+from pydantic import SerializerFunctionWrapHandler
+from pydantic_core import to_jsonable_python
 
 from ..auth.auth_tool import AuthConfig
 from ..tools.tool_confirmation import ToolConfirmation
 from .ui_widget import UiWidget
 
+logger = logging.getLogger('google_adk.' + __name__)
 
-class EventCompaction(BaseModel):
+
+def _make_json_serializable(obj: Any) -> Any:
+  """Converts an object into a JSON-serializable form.
+
+  Used as a fallback when the default Pydantic serialization fails. Delegates to
+  `pydantic_core.to_jsonable_python` so rich types (e.g. datetimes, Pydantic
+  models) are serialized faithfully instead of being discarded. Values that
+  pydantic-core cannot serialize (e.g. Python callables stored in session state)
+  are replaced with their `repr` via `serialize_unknown=True` so the overall
+  structure can still be persisted without crashing.
+  """
+  return to_jsonable_python(obj, serialize_unknown=True)
+
+
+class EventCompaction(BaseModel):  # type: ignore[misc]
   """The compaction of the events."""
 
   model_config = ConfigDict(
@@ -49,7 +69,7 @@ class EventCompaction(BaseModel):
   """The compacted content of the events."""
 
 
-class EventActions(BaseModel):
+class EventActions(BaseModel):  # type: ignore[misc]
   """Represents the actions attached to an event."""
 
   model_config = ConfigDict(
@@ -68,6 +88,27 @@ class EventActions(BaseModel):
   state_delta: dict[str, Any] = Field(default_factory=dict)
   """Indicates that the event is updating the state with the given delta."""
 
+  @field_serializer('state_delta', mode='wrap')  # type: ignore[misc, untyped-decorator]
+  def _serialize_state_delta(
+      self, value: dict[str, object], handler: SerializerFunctionWrapHandler
+  ) -> dict[str, Any]:
+    # Use a wrap serializer so the default serialization (which honors callers'
+    # `exclude`/`include` directives, e.g. the conformance harness excluding
+    # internal `_adk_*` keys) is preserved. Only fall back to sanitization when
+    # the value contains objects Pydantic cannot serialize (e.g. callables).
+    try:
+      return cast(dict[str, Any], handler(value))
+    except Exception:  # pylint: disable=broad-except
+      logger.warning(
+          'Failed to serialize `state_delta`; some values are not'
+          ' JSON-serializable (e.g. callables) and will be replaced with a'
+          ' string representation in the persisted event.',
+          exc_info=True,
+      )
+      # Re-run the handler on the sanitized value so that caller `exclude` /
+      # `include` directives are still applied to the fallback output.
+      return cast(dict[str, Any], handler(_make_json_serializable(value)))
+
   artifact_delta: dict[str, int] = Field(default_factory=dict)
   """Indicates that the event is updating an artifact. key is the filename,
   value is the version."""
@@ -108,6 +149,28 @@ class EventActions(BaseModel):
   """The agent state at the current event, used for checkpoint and resume. This
   should only be set by ADK workflow."""
 
+  @field_serializer('agent_state', mode='wrap')  # type: ignore[misc, untyped-decorator]
+  def _serialize_agent_state(
+      self,
+      value: Optional[dict[str, Any]],
+      handler: SerializerFunctionWrapHandler,
+  ) -> Optional[dict[str, Any]]:
+    if value is None:
+      return None
+    # See `_serialize_state_delta` for why a wrap serializer is used.
+    try:
+      return cast(Optional[dict[str, Any]], handler(value))
+    except Exception:  # pylint: disable=broad-except
+      logger.warning(
+          'Failed to serialize `agent_state`; some values are not'
+          ' JSON-serializable (e.g. callables) and will be replaced with a'
+          ' string representation in the persisted event.',
+          exc_info=True,
+      )
+      # Re-run the handler on the sanitized value so that caller `exclude` /
+      # `include` directives are still applied to the fallback output.
+      return cast(dict[str, Any], handler(_make_json_serializable(value)))
+
   rewind_before_invocation_id: Optional[str] = None
   """The invocation id to rewind to. This is only set for rewind event."""
 

tests/unittests/events/test_event_actions.py

@@ -0,0 +1,150 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+"""Unit tests for EventActions serialization and its fallback helper."""
+
+import datetime
+import logging
+
+from google.adk.events.event_actions import _make_json_serializable
+from google.adk.events.event_actions import EventActions
+from pydantic import BaseModel
+
+
+class _Sample(BaseModel):
+  x: int = 5
+  label: str = 'hi'
+
+
+class TestMakeJsonSerializable:
+  """Tests for the `_make_json_serializable` fallback helper."""
+
+  def test_plain_values_are_unchanged(self):
+    value = {'a': 1, 'b': [1, 2], 'c': {'d': 'e'}, 'f': None, 'g': True}
+    assert _make_json_serializable(value) == value
+
+  def test_datetime_is_preserved_not_discarded(self):
+    dt = datetime.datetime(2024, 1, 2, 3, 4, 5, tzinfo=datetime.timezone.utc)
+    assert _make_json_serializable(dt) == '2024-01-02T03:04:05Z'
+
+  def test_pydantic_model_is_serialized_to_dict(self):
+    assert _make_json_serializable(_Sample()) == {'x': 5, 'label': 'hi'}
+
+  def test_nested_rich_types_are_serialized(self):
+    dt = datetime.datetime(2024, 5, 6, tzinfo=datetime.timezone.utc)
+    result = _make_json_serializable({'when': dt, 'model': _Sample(), 'n': [1]})
+    assert result == {
+        'when': '2024-05-06T00:00:00Z',
+        'model': {'x': 5, 'label': 'hi'},
+        'n': [1],
+    }
+
+  def test_unserializable_value_is_replaced_with_repr(self):
+    result = _make_json_serializable(lambda: 1)
+    assert isinstance(result, str)
+    assert 'function' in result
+
+  def test_unserializable_value_nested(self):
+    result = _make_json_serializable({'cb': lambda: 1, 'ok': 2})
+    assert result['ok'] == 2
+    assert isinstance(result['cb'], str)
+
+
+class TestStateDeltaSerialization:
+  """Tests for the `state_delta` wrap serializer."""
+
+  def test_serializable_state_delta_round_trips(self):
+    actions = EventActions(state_delta={'a': 1, 'b': [1, 2], 'c': {'d': 'e'}})
+    dumped = actions.model_dump(mode='json')
+    assert dumped['state_delta'] == {'a': 1, 'b': [1, 2], 'c': {'d': 'e'}}
+
+  def test_non_serializable_state_delta_does_not_raise(self):
+    actions = EventActions(state_delta={'cb': lambda: 1, 'ok': 2})
+    dumped = actions.model_dump(mode='json')
+    assert dumped['state_delta']['ok'] == 2
+    assert isinstance(dumped['state_delta']['cb'], str)
+
+  def test_non_serializable_state_delta_logs_warning(self, caplog):
+    actions = EventActions(state_delta={'cb': lambda: 1})
+    with caplog.at_level(logging.WARNING):
+      actions.model_dump(mode='json')
+    assert any(
+        'Failed to serialize `state_delta`' in record.message
+        for record in caplog.records
+    )
+
+  def test_datetime_preserved_when_fallback_triggered(self):
+    # A callable forces the fallback path; the datetime must still serialize
+    # faithfully rather than being discarded.
+    dt = datetime.datetime(2024, 1, 2, 3, 4, 5, tzinfo=datetime.timezone.utc)
+    actions = EventActions(state_delta={'when': dt, 'cb': lambda: 1})
+    dumped = actions.model_dump(mode='json')
+    assert dumped['state_delta']['when'] == '2024-01-02T03:04:05Z'
+
+  def test_exclude_is_respected_for_serializable_state(self):
+    actions = EventActions(
+        state_delta={'_adk_replay_config': {'dir': '/x'}, 'foo': 1}
+    )
+    dumped = actions.model_dump(
+        mode='json', exclude={'state_delta': {'_adk_replay_config': True}}
+    )
+    assert dumped['state_delta'] == {'foo': 1}
+
+  def test_exclude_is_respected_in_fallback_path(self):
+    # Even when sanitization is required (callable present), caller `exclude`
+    # directives must still be applied to the fallback output.
+    actions = EventActions(
+        state_delta={
+            '_adk_replay_config': {'dir': '/x'},
+            'cb': lambda: 1,
+            'ok': 2,
+        }
+    )
+    dumped = actions.model_dump(
+        mode='json', exclude={'state_delta': {'_adk_replay_config': True}}
+    )
+    assert '_adk_replay_config' not in dumped['state_delta']
+    assert dumped['state_delta']['ok'] == 2
+    assert isinstance(dumped['state_delta']['cb'], str)
+
+
+class TestAgentStateSerialization:
+  """Tests for the `agent_state` wrap serializer."""
+
+  def test_none_agent_state_serializes_to_none(self):
+    assert EventActions().model_dump(mode='json')['agent_state'] is None
+
+  def test_serializable_agent_state_round_trips(self):
+    actions = EventActions(agent_state={'a': 1, 'b': 'two'})
+    assert actions.model_dump(mode='json')['agent_state'] == {
+        'a': 1,
+        'b': 'two',
+    }
+
+  def test_non_serializable_agent_state_does_not_raise(self):
+    actions = EventActions(agent_state={'cb': lambda: 1, 'n': 3})
+    dumped = actions.model_dump(mode='json')
+    assert dumped['agent_state']['n'] == 3
+    assert isinstance(dumped['agent_state']['cb'], str)
+
+  def test_non_serializable_agent_state_logs_warning(self, caplog):
+    actions = EventActions(agent_state={'cb': lambda: 1})
+    with caplog.at_level(logging.WARNING):
+      actions.model_dump(mode='json')
+    assert any(
+        'Failed to serialize `agent_state`' in record.message
+        for record in caplog.records
+    )