Python: Avoid unchanged AG-UI predictive state snapshots

[ALEX LILUZ (alexliluz)]

Motivation & Context

When predict_state_config is enabled, every tool result currently emits a full StateSnapshotEvent, even when the completed tool did not produce a predictive update. The handler object is truthy regardless of whether pending_state_updates is empty, so unrelated tools resend unchanged state and can trigger unnecessary client rendering.

Description & Review Guide

• What are the major changes? Record whether predictive updates are pending before applying and clearing them, then use that signal when deciding whether to emit the coalesced state snapshot. Add regression tests for both the no-op and real-update paths.
• What is the impact of these changes? Unrelated tool results no longer emit unchanged full-state snapshots. Actual predictive updates and deterministic state_update results retain the existing single-snapshot behavior.
• What do you want reviewers to focus on? Whether checking the pending-update set before apply_pending_updates() is the preferred boundary for distinguishing configured prediction from an actual state change.

Related Issue

Fixes#7490

No other open PR is linked to this issue.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR adjusts when _emit_tool_result_common emits STATE_SNAPSHOT events so that a configured predictive state handler only triggers a snapshot when it actually has pending predictive updates, and adds tests to lock in that behavior.

Changes:

• Prevent emitting unchanged STATE_SNAPSHOT events when a predictive handler is present but has no pending updates.
• Add tests covering predictive handler behavior with/without pending updates.
• Keep existing snapshot behavior for explicit tool state_update results.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
python/packages/ag-ui/agent_framework_ag_ui/_run_common.py	Gate snapshot emission on predictive handler having pending updates (not merely being configured).
python/packages/ag-ui/tests/ag_ui/test_run_common.py	Add regression tests ensuring snapshots are emitted only when predictive updates are pending/applied.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[ALEX LILUZ (alexliluz)]

@microsoft-github-policy-service agree

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/ag-ui/agent_framework_ag_ui
_run_common.py	623	39	93%	100, 175–176, 178, 180, 183, 189, 191, 205, 212, 236–237, 250, 269, 292–294, 305, 349, 361, 369, 372, 565, 846–847, 1171–1172, 1177, 1179–1181, 1190, 1198, 1210, 1212–1215, 1278
TOTAL	47110	4371	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9560	36 💤	0 ❌	0 🔥	2m 37s ⏱️