Repository navigation
Plugin framework: on_state_change_callback is never invoked #4393
Description
Description
The plugin framework provides hooks for various lifecycle events (before/after agent, tool, model callbacks, etc.), but there is no mechanism to notify plugins when session state changes occur via event.actions.state_delta.
The BigQueryAgentAnalyticsPlugin already implements an on_state_change_callback() method, demonstrating real demand for this hook, but the framework never invokes it because:
BasePluginhas no defaulton_state_change_callbackmethodPluginManagerhas no dispatcher for it- The runner never detects state deltas and triggers the callback
Expected Behavior
When an event with a non-empty state_delta is yielded from the runner, all registered plugins should have their on_state_change_callback invoked with the state delta (as a copy, to prevent mutation).
Proposed Solution
- Add
on_state_change_callbacktoBasePluginas a default no-op method - Add
"on_state_change_callback"toPluginCallbackNameand arun_on_state_change_callbackdispatcher toPluginManager - In
Runner._exec_with_plugin, after yielding the final event, check forstate_deltaand invoke the callback
The callback should be observational (return value ignored) and receive a copy of the state delta to prevent plugins from mutating event state.
Activity
feat(plugins): wire on_state_change_callback into plugin framework
feat(plugins): wire on_state_change_callback into plugin framework
mportdata commentedon Feb 9, 2026
Fix awaiting review here: #4395
wuliang229 commentedon Feb 9, 2026
@haiyuan-eng-google please take a look.
haiyuan-eng-google commentedon Feb 10, 2026
Confirmation
You are absolutely correct. We have verified that:
BigQueryAgentAnalyticsPluginimplementson_state_change_callback, but it is effectively dead code.BasePluginandPluginManagerdo not define or support this callback.Runnerdoes not dispatch any specific callback when yielding events withstate_delta.This is a clear gap in the plugin lifecycle hooks. While
on_event_callbackexists, a dedicatedon_state_change_callbackis cleaner and semantically more appropriate for state mutations, especially given thatBigQueryAgentAnalyticsPluginalready expects it.Plan
on_state_change_callbacktoBasePlugin(no-op default) andPluginManager.Runner._exec_with_plugin(and potentially_append_new_message_to_session) to invoke this callback whenever an event contains a non-emptystate_delta.mportdata commentedon Feb 10, 2026
I have raised a fix here: #4395
This has added an
on_state_change_callbackno-op method to theBasePluginandPluginManageras described above.STATE_DELTA was already being logged as part of
after_tool_callback, my fix includes removing this implementation to not cause duplicate STATE_DELTA logs.RE:
_append_new_message_to_sessionI have now added a fix so that_append_new_message_to_sessioncalls the appropriate plug-in method when state_delta is not none.RE: Safety: please let me know if this has not been addressed by my fix already.
In my fix we call
on_state_change_callbackwithinRunner._exec_with_pluginwhen any event has a non-emptyactions.state_delta.wuliang229 commentedon Feb 10, 2026
@haiyuan-eng-google FYI, the ADK team doesn't want to add a
on_state_change_callbackto the framework. Is there a way to fix it without introducing a framework change?fix: log state deltas via on_event_callback instead of dead code
adk-bot commentedon Feb 18, 2026
This issue has been automatically marked as stale because it has not had recent activity for 7 days after a maintainer requested clarification. It will be closed if no further activity occurs within 7 days.
haiyuan-eng-google commentedon Feb 18, 2026
The issue has been fixed in ea03487 with on_event_callback @wuliang229