8000 [BREAKING] Python: Refactor SharedState to State with sync methods and superstep caching by moonbox3 · Pull Request #3667 · microsoft/agent-framework · GitHub
[go: up one dir, main page]
Skip to content

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

Merged
TaoChenOSU merged 9 commits intomicrosoft:mainfrom
moonbox3:workflows-state-update
Feb 5, 2026
Merged

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

Conversation

@moonbox3
Copy link
Contributor
@moonbox3 moonbox3 commented Feb 4, 2026

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.

@moonbox3 moonbox3 self-assigned this Feb 4, 2026
Copilot AI review requested due to automatic review settings February 4, 2026 06:33
@moonbox3 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 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 markwallace-microsoft added the documentation Improvements or additions to documentation label Feb 4, 2026
@markwallace-microsoft
Copy link
Member
markwallace-microsoft commented Feb 4, 2026 •
edited
Loading

Python Test Coverage

Python Test Coverage Report •
FileStmtsMissCoverMissing
packages/core/agent_framework/_workflows
   _agent_executor.py1602286%98, 146, 164–165, 216–217, 219–220, 252–254, 262–264, 274–276, 278, 282, 286, 290–291
   _checkpoint.py121298%184–185
   _checkpoint_summary.py27485%36–39
   _const.py60100% 
   _edge_runner.py1621391%53, 58, 71, 138–139, 143, 150, 206, 211, 355–356, 360, 401
   _executor.py1731094%212, 334, 336, 345, 365, 368, 475, 480, 490, 649
   _runner.py2183285%132–133, 176–179, 183, 224–226, 251–252, 254, 289–291, 315–319, 323, 358, 362, 364, 370, 378–381, 394, 430
   _runner_context.py168696%84, 87, 383, 403, 491, 495
   _state.py430100% 
   _workflow.py2681992%89, 267–269, 271–272, 290, 294, 322, 424, 705, 747, 752, 755, 774–776, 789, 857
   _workflow_context.py157994%62–63, 71, 75, 89, 165, 190, 308, 427
   _workflow_executor.py1734375%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
TOTAL16362191388% 

Python Unit Test Overview

Tests Skipped Failures Errors Time
3989 221 💤 0 ❌ 0 🔥 1m 5s ⏱️

Copilot AI reviewed Feb 4, 2026
View reviewed changes
Copy link
Contributor
Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@moonbox3 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 moonbox3 moved this to In Review in Agent Framework Feb 4, 2026
eavanvalkenburg
eavanvalkenburg reviewed Feb 4, 2026
View reviewed changes
TaoChenOSU
TaoChenOSU approved these changes Feb 4, 2026
View reviewed changes
@markwallace-microsoft markwallace-microsoft added the lab Agent Framework Lab label Feb 5, 2026
@TaoChenOSU TaoChenOSU enabled auto-merge February 5, 2026 01:40
@TaoChenOSU TaoChenOSU added this pull request to the merge queue Feb 5, 2026
Merged via the queue into microsoft:main with commit 10afb86 Feb 5, 2026
36 checks passed
@github-project-automation github-project-automation bot moved this from In Review to Done in Agent Framework Feb 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@eavanvalkenburg eavanvalkenburg eavanvalkenburg left review comments

Copilot code review Copilot Copilot left review comments

@TaoChenOSU TaoChenOSU TaoChenOSU approved these changes

@dmytrostruk dmytrostruk dmytrostruk approved these changes

7C88

Assignees

@moonbox3 moonbox3

Labels

breaking change Introduces changes that are not backward compatible and may require updates to dependent code. documentation Improvements or additions to documentation lab Agent Framework Lab python workflows Related to Workflows in agent-framework

Projects

Agent Framework
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Python: Clean up public API surface and kwargs propagation Python: Refactor State class - rename, simplify, and implement superstep caching

6 participants

@moonbox3 @markwallace-microsoft @TaoChenOSU @eavanvalkenburg @dmytrostruk
0