@@ -14,13 +14,16 @@ namespace Microsoft.Agents.AI.Workflows;
1414/// <summary>
1515/// Provides a base class for executors that maintain and manage state across multiple message handling operations.
1616/// </summary>
17+ /// <remarks>
18+ /// State is read from the current workflow context, including pending updates and restored checkpoints.
19+ /// Derived executors with instance state must explicitly implement <see cref="IResettableExecutor"/>
20+ /// to support resetting that state between runs.
21+ /// </remarks>
1722/// <typeparam name="TState">The type of state associated with this Executor.</typeparam>
1823public abstract class StatefulExecutor < TState > : Executor
1924{
2025 private readonly Func < TState > _initialStateFactory ;
2126
22- private TState ? _stateCache ;
23-
2427 /// <summary>
2528 /// Initializes the executor with a unique id and an initial value for the state.
2629 /// </summary>
@@ -52,28 +55,12 @@ protected StatefulExecutor(string id,
5255 /// Reads the state associated with this executor. If it is not initialized, it will be set to the initial state.
5356 /// </summary>
5457 /// <param name="context">The workflow context in which the executor executes.</param>
55- /// <param name="skipCache">Ignore the cached value, if any. State is not cached when running in Cross-Run Shareable
56- /// mode.</param>
58+ /// <param name="skipCache">Retained for compatibility. State is always read from the workflow context.</param>
5759 /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
5860 /// The default is <see cref="CancellationToken.None"/>.</param>
5961 /// <returns></returns>
60- protected async ValueTask < TState > ReadStateAsync ( IWorkflowContext context , bool skipCache = false , CancellationToken cancellationToken = default )
61- {
62- if ( ! skipCache && this . _stateCache is not null )
63- {
64- return this . _stateCache ;
65- }
66-
67- TState ? state = await context . ReadOrInitStateAsync ( this . StateKey , this . _initialStateFactory , this . Options . ScopeName , cancellationToken )
68- . ConfigureAwait ( false ) ;
69-
70- if ( ! context . ConcurrentRunsEnabled )
71- {
72- this . _stateCache = state ;
73- }
74-
75- return state ;
76- }
62+ protected ValueTask < TState > ReadStateAsync ( IWorkflowContext context , bool skipCache = false , CancellationToken cancellationToken = default )
63+ => context . ReadOrInitStateAsync ( this . StateKey , this . _initialStateFactory , this . Options . ScopeName , cancellationToken ) ;
7764
7865 /// <summary>
7966 /// Queues up an update to the executor's state.
@@ -84,14 +71,7 @@ protected async ValueTask<TState> ReadStateAsync(IWorkflowContext context, bool
8471 /// The default is <see cref="CancellationToken.None"/>.</param>
8572 /// <returns></returns>
8673 protected ValueTask QueueStateUpdateAsync ( TState state , IWorkflowContext context , CancellationToken cancellationToken = default )
87- {
88- if ( ! context . ConcurrentRunsEnabled )
89- {
90- this . _stateCache = state ;
91- }
92-
93- return context . QueueStateUpdateAsync ( this . StateKey , state , this . Options . ScopeName , cancellationToken ) ;
94- }
74+ => context . QueueStateUpdateAsync ( this . StateKey , state , this . Options . ScopeName , cancellationToken ) ;
9575
9676 /// <summary>
9777 /// Invokes an asynchronous operation that reads, updates, and persists workflow state associated with the specified
@@ -100,55 +80,27 @@ protected ValueTask QueueStateUpdateAsync(TState state, IWorkflowContext context
10080 /// <param name="invocation">A delegate that receives the current state, workflow context, and cancellation token,
10181 /// and returns the updated state asynchronously.</param>
10282 /// <param name="context">The workflow context in which the executor executes.</param>
103- /// <param name="skipCache">Ignore the cached value, if any. State is not cached when running in Cross-Run Shareable
104- /// mode.</param>
83+ /// <param name="skipCache">Retained for compatibility. State is always read from the workflow context.</param>
10584 /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
10685 /// The default is <see cref="CancellationToken.None"/>.</param>
10786 /// <returns>A ValueTask that represents the asynchronous operation.</returns>
108- protected async ValueTask InvokeWithStateAsync (
87+ protected ValueTask InvokeWithStateAsync (
10988 Func < TState , IWorkflowContext , CancellationToken , ValueTask < TState ? > > invocation ,
11089 IWorkflowContext context ,
11190 bool skipCache = false ,
11291 CancellationToken cancellationToken = default )
113- {
114- if ( ! skipCache && ! context . ConcurrentRunsEnabled )
115- {
116- if ( this . _stateCache is null )
117- {
118- this . _stateCache = await context . ReadOrInitStateAsync ( this . StateKey , this . _initialStateFactory , this . Options . ScopeName , cancellationToken )
119- . ConfigureAwait ( false ) ;
120- }
121-
122- TState newState = await invocation ( this . _stateCache ?? this . _initialStateFactory ( ) ,
123- context ,
124- cancellationToken ) . ConfigureAwait ( false )
125- ?? this . _initialStateFactory ( ) ;
126-
127- await context . QueueStateUpdateAsync ( this . StateKey ,
128- newState ,
129- this . Options . ScopeName ,
130- cancellationToken ) . ConfigureAwait ( false ) ;
131-
132- this . _stateCache = newState ;
133- }
134- else
135- {
136- await context . InvokeWithStateAsync ( invocation ,
137- this . StateKey ,
138- this . _initialStateFactory ,
139- this . Options . ScopeName ,
140- cancellationToken )
141- . ConfigureAwait ( false ) ;
142- }
143- }
92+ => context . InvokeWithStateAsync ( invocation ,
93+ this . StateKey ,
94+ this . _initialStateFactory ,
95+ this . Options . ScopeName ,
96+ cancellationToken ) ;
14497
14598 /// <inheritdoc cref="IResettableExecutor.ResetAsync"/>
146- protected virtual ValueTask ResetAsync ( )
147- {
148- this . _stateCache = this . _initialStateFactory ( ) ;
149-
150- return default ;
151- }
99+ /// <remarks>
100+ /// The base implementation has no instance state to reset and does not change persisted workflow state.
101+ /// Derived executors can override this method to reset their own instance state.
102+ /// </remarks>
103+ protected virtual ValueTask ResetAsync ( ) => default ;
152104}
153105
154106/// <summary>
0 commit comments