[BREAKING] Python: Refactor SharedState to State with sync methods and superstep caching by moonbox3 · Pull Request #3667 · microsoft/agent-framework

moonbox3 · 2026-02-04T06:33:55Z

Motivation and Context

Refactors the workflow state management system with breaking changes:

Rename SharedState -> State class and _shared_state.py -> _state.py
Convert all async methods to sync (Python dicts are thread-safe; async was unnecessary overhead)
Implement superstep caching: writes go to pending cache, committed at superstep boundary via commit(), which is now consistent with the .NET behavior.
Add get(key, default=None) API that returns default instead of raising KeyError
Add has(key) method for existence checks
Rename WorkflowCheckpoint.shared_state → WorkflowCheckpoint.state
Remove State from public exports (internal implementation detail)

Breaking Changes

Before	After
`SharedState`	`State`
`ctx.shared_state`	`ctx.state`
`await ctx.get_shared_state(key)`	`ctx.get_state(key, default=None)`
`await ctx.set_shared_state(key, value)`	`ctx.set_state(key, value)`
`checkpoint.shared_state`	`checkpoint.state`

Description

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.

markwallace-microsoft · 2026-02-04T06:36:05Z

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_agent_executor.py	171	23	86%	95, 117, 151, 167–168, 219–220, 222–223, 255–257, 265–267, 277–279, 281, 285, 289, 293–294
_checkpoint.py	121	2	98%	182–183
_checkpoint_summary.py	27	4	85%	36–39
_const.py	6	0	100%
_edge_runner.py	162	13	91%	53, 58, 71, 138–139, 143, 150, 206, 211, 355–356, 360, 401
_executor.py	173	10	94%	212, 334, 336, 345, 365, 368, 475, 480, 490, 649
_runner.py	211	32	84%	124–125, 168–171, 175, 216–218, 243–244, 246, 281–283, 307–311, 315, 350, 354, 356, 362, 370–373, 386, 422
_runner_context.py	168	6	96%	84, 87, 383, 403, 491, 495
_state.py	43	0	100%
_workflow.py	249	17	93%	89, 259–261, 263–264, 282, 310, 412, 689, 723, 728, 731, 750–752, 817
_workflow_context.py	174	21	87%	63–64, 72, 76, 90, 166, 191, 309, 428, 471, 473–474, 476–477, 486–488, 490–492, 494
_workflow_executor.py	173	43	75%	96, 445, 456, 468–471, 474–476, 479–480, 482, 485–487, 490–494, 498–499, 508, 513, 547, 573–578, 581, 584, 592, 597, 608, 618, 622, 628, 632, 642, 646
TOTAL	16332	1981	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3845	221 💤	0 ❌	0 🔥	1m 9s ⏱️

Copilot

Pull request overview

This PR implements a breaking refactoring of workflow state management, renaming SharedState to State, converting all async methods to sync, and implementing superstep caching semantics to align with .NET behavior.

Changes:

Renamed SharedState class to State and file _shared_state.py to _state.py
Converted all state methods from async to sync (removing asyncio.Lock)
Implemented superstep caching: writes go to pending buffer, committed at boundaries via commit()
Added get(key, default=None) API and has(key) method
Renamed WorkflowCheckpoint.shared_state → WorkflowCheckpoint.state
Updated all references across codebase (workflow context, runner, executors, tests, samples)

Reviewed changes

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

Show a summary per file

File	Description
`_state.py`	New State class with sync methods and superstep caching implementation
`_workflow.py`	Updated to use State with commit() call after kwargs initialization
`_runner.py`	Integrated commit() at superstep boundaries
`_workflow_context.py`	Changed to sync get_state/set_state methods
`_checkpoint.py`	Renamed shared_state field to state
`__init__.py`	Updated exports (but State still exported - should be removed)
Test files	Updated all test mocks and assertions to use State
Sample files	Updated comments and documentation references
Frontend	Updated TypeScript interfaces and references

python/packages/core/agent_framework/_workflows/_state.py

python/packages/core/agent_framework/_workflows/__init__.py

python/packages/devui/frontend/src/components/features/workflow/checkpoint-info-modal.tsx

eavanvalkenburg · 2026-02-04T09:16:47Z

python/samples/getting_started/workflows/state-management/state_with_agents.py

    new_email = Email(email_id=str(uuid4()), email_content=email_text)
-    await ctx.set_shared_state(f"{EMAIL_STATE_PREFIX}{new_email.email_id}", new_email)
-    await ctx.set_shared_state(CURRENT_EMAIL_ID_KEY, new_email.email_id)
+    ctx.set_state(f"{EMAIL_STATE_PREFIX}{new_email.email_id}", new_email)


is this prefix needed to demonstrate the concept?

eavanvalkenburg · 2026-02-04T09:25:42Z

python/packages/core/agent_framework/_workflows/_checkpoint.py

        messages: Messages exchanged between executors
-        shared_state: Complete shared state including user data and executor states.
-                     Executor states are stored under the reserved key '_executor_state'.
+        state: Complete workflow state including user data and executor states.


maybe clarify that this is committed state only

eavanvalkenburg · 2026-02-04T09:26:27Z

python/packages/core/agent_framework/_workflows/_state.py

+        The value will be visible to subsequent `get()` calls but won't be
+        committed to the actual state until `commit()` is called.
+        """
+        self._pending[key] = value


should we deal with two pending updates for the same key? maybe from two different executors?

TaoChenOSU · 2026-02-04T23:32:27Z

python/packages/core/agent_framework/_workflows/_agent_executor.py

            The complete AgentResponse, or None if waiting for user input.
        """
-        run_kwargs: dict[str, Any] = await ctx.get_shared_state(WORKFLOW_RUN_KWARGS_KEY)
+        run_kwargs: dict[str, Any] = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY) or {}


Suggested change

run_kwargs: dict[str, Any] = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY) or {}

run_kwargs: dict[str, Any] = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY, {})

TaoChenOSU · 2026-02-04T23:40:17Z

python/packages/core/agent_framework/_workflows/_workflow_context.py

@@ -459,41 +459,37 @@ def get_yielded_outputs(self) -> list[Any]:

    @deprecated(


Should we remove these deprecated methods?

Refactor SharedState to State with sync methods and superstep caching

12b1324

moonbox3 self-assigned this Feb 4, 2026

moonbox3 added this to Agent Framework Feb 4, 2026

Copilot AI review requested due to automatic review settings February 4, 2026 06:33

moonbox3 added python workflows Related to Workflows in agent-framework breaking change Introduces changes that are not backward compatible and may require updates to dependent code. labels Feb 4, 2026

github-actions bot changed the title ~~[BREAKING] Python: Refactor SharedState to State with sync methods and superstep caching~~ Python: [BREAKING] Python: Refactor SharedState to State with sync methods and superstep caching Feb 4, 2026

markwallace-microsoft added the documentation Improvements or additions to documentation label Feb 4, 2026

Copilot started reviewing on behalf of moonbox3 February 4, 2026 06:34 View session

Copilot AI reviewed Feb 4, 2026

View reviewed changes

moonbox3 added 2 commits February 4, 2026 15:47

Fixes

f4bf6a4

Merge main

1df4db0

moonbox3 changed the title ~~Python: [BREAKING] Python: Refactor SharedState to State with sync methods and superstep caching~~ [BREAKING] Python: Refactor SharedState to State with sync methods and superstep caching Feb 4, 2026

moonbox3 moved this to In Review in Agent Framework Feb 4, 2026

eavanvalkenburg reviewed Feb 4, 2026

View reviewed changes

dmytrostruk approved these changes Feb 4, 2026

View reviewed changes

TaoChenOSU approved these changes Feb 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[BREAKING] Python: Refactor SharedState to State with sync methods and superstep caching#3667

[BREAKING] Python: Refactor SharedState to State with sync methods and superstep caching#3667
moonbox3 wants to merge 3 commits intomicrosoft:mainfrom
moonbox3:workflows-state-update

moonbox3 commented Feb 4, 2026

Uh oh!

markwallace-microsoft commented Feb 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eavanvalkenburg Feb 4, 2026

Uh oh!

eavanvalkenburg Feb 4, 2026

Uh oh!

eavanvalkenburg Feb 4, 2026

Uh oh!

TaoChenOSU Feb 4, 2026

Uh oh!

TaoChenOSU Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	run_kwargs: dict[str, Any] = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY) or {}
	run_kwargs: dict[str, Any] = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY, {})

		@@ -459,41 +459,37 @@ def get_yielded_outputs(self) -> list[Any]:

		@deprecated(

Conversation

moonbox3 commented Feb 4, 2026

Motivation and Context

Breaking Changes

Description

Contribution Checklist

Uh oh!

markwallace-microsoft commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python Unit Test Overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eavanvalkenburg Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

eavanvalkenburg Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

eavanvalkenburg Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

TaoChenOSU Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

TaoChenOSU Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

markwallace-microsoft commented Feb 4, 2026 •

edited

Loading