Python: AG-UI deterministic state updates from tool results

[moonbox3]

Motivation and Context

• Fixes Python: State Management with AG-UI #3167 — AG-UI agents had no way to push a deterministic state update from a tool's actual return value. The only built-in path, predict_state_config, is driven optimistically by LLM-predicted tool arguments, which is wrong when the real state depends on what the tool actually computes (e.g. get_weather needs to fetch data and put that in state).
• Adds a new state_update(text, state=...) helper in agent_framework_ag_ui. Tools return it as a Content; the snapshot rides in additional_properties under a reserved key, survives parse_result / from_function_result round-tripping, and is extracted by the AG-UI emitter which merges it into FlowState.current_state and emits a StateSnapshotEvent right after the ToolCallResult event.
• Orthogonal to predict_state_config — both mechanisms can fire on the same tool result, with predictive state applied first.
• Non-breaking and opt-in: zero behavior change for tools that don't call state_update().

Description

• Closes Python: State Management with AG-UI #3167

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/ag-ui/agent_framework_ag_ui
_run_common.py	307	10	96%	381–382, 388–393, 701–702
_state.py	11	0	100%
packages/ag-ui/agent_framework_ag_ui_examples/agents
weather_state_agent.py	15	15	0%	16, 18, 20–21, 23, 27, 36–37, 53–54, 58–59, 68, 70, 82
packages/ag-ui/agent_framework_ag_ui_examples/server
main.py	64	64	0%	5, 7–9, 11–17, 19–27, 29–32, 34, 36, 39–40, 43–45, 48–50, 52–54, 56–58, 61–62, 64–65, 67, 69, 80, 88, 95, 102, 109, 116, 125, 132, 139, 147, 154, 156–157, 159–160, 164, 172–173
TOTAL	27249	3201	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5466	20 💤	0 ❌	0 🔥	1m 28s ⏱️

[Copilot]

Pull request overview

Adds an opt-in mechanism for AG-UI tools to emit deterministic state snapshots derived from the tool’s actual return value (vs. optimistic predict_state_config based on predicted args), addressing agent-framework issue #3167.

Changes:

• Introduces a public state_update(text, state=...) helper that encodes a state snapshot into Content.additional_properties.
• Extracts tool-result state markers during AG-UI emission, merges into FlowState.current_state, and emits STATE_SNAPSHOT after tool results (including MCP tool results).
• Adds unit + end-to-end + golden tests and an examples endpoint demonstrating deterministic tool-driven state.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/ag_ui/init.pyi	Exposes state_update in the core AG-UI typing surface.
python/packages/core/agent_framework/ag_ui/init.py	Adds state_update to lazy exports (but still has export-list mismatches vs stub).
python/packages/ag-ui/agent_framework_ag_ui/_state.py	New helper + reserved marker key for deterministic state updates.
python/packages/ag-ui/agent_framework_ag_ui/_run_common.py	Extracts/merges tool-result state and emits STATE_SNAPSHOT events.
python/packages/ag-ui/agent_framework_ag_ui/init.py	Re-exports state_update from the runtime package.
python/packages/ag-ui/agent_framework_ag_ui_examples/server/main.py	Registers a new /deterministic_state example endpoint.
python/packages/ag-ui/agent_framework_ag_ui_examples/agents/weather_state_agent.py	New example agent showing tool-driven deterministic state.
python/packages/ag-ui/tests/ag_ui/test_run_common.py	Adds focused tests for helper, extraction, and emission behavior.
python/packages/ag-ui/tests/ag_ui/test_public_exports.py	Verifies state_update is exported publicly.
python/packages/ag-ui/tests/ag_ui/test_agent_wrapper_comprehensive.py	End-to-end regression coverage through real tool invocation.
python/packages/ag-ui/tests/ag_ui/golden/test_scenario_deterministic_state.py	Golden stream tests pinning user-visible event ordering/content.