mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Jacob Alber
0086d38f58
* refactor: Normalize Run/RunStreaming with AIAgent * refactor: Clarify Session vs. Run -level concepts * Rename RunId to SessionId to better match Run/Session terminology in AIAgent * [BREAKING]: Will break existing checkpointed sessions in CosmosDb due to field rename * refactor: Rename and simplify interface around getting typed data out of ExternalRequest/Response * Also adds hints around using value types in PortableValue * refactor: Rename AddFanInEdge to AddFanInBarrierEdge This will prevent a breaking change later when we introduce a programmable FanIn edge, analogous to the FanOut edge's EdgeSelector. The goal, in the long run is to support a number of different FanIn scenarios, with naive FanIn (no barrier) by default, similar to FanOut. * refactor: AsAgent(this Workflow, ...) => AsAIAgent(...) * misc - part1: SwitchBuilder internal --------- Co-authored-by: Dmytro Struk <13853051+dmytrostruk@users.noreply.github.com>
82 lines
6.0 KiB
C#
82 lines
6.0 KiB
C#
// Copyright (c) Microsoft. All rights reserved.
|
|
|
|
using System.Threading;
|
|
using System.Threading.Tasks;
|
|
|
|
namespace Microsoft.Agents.AI.Workflows;
|
|
|
|
/// <summary>
|
|
/// Defines an execution environment for running, streaming, and resuming workflows asynchronously, with optional
|
|
/// checkpointing and run management capabilities.
|
|
/// </summary>
|
|
public interface IWorkflowExecutionEnvironment
|
|
{
|
|
/// <summary>
|
|
/// Specifies whether Checkpointing is configured for this environment.
|
|
/// </summary>
|
|
bool IsCheckpointingEnabled { get; }
|
|
|
|
/// <summary>
|
|
/// Initiates a streaming run of the specified workflow without sending any initial input. Note that the starting
|
|
/// <see cref="Executor"/> will not be invoked until an input message is received.
|
|
/// </summary>
|
|
/// <param name="workflow">The workflow to execute. Cannot be null.</param>
|
|
/// <param name="sessionId">An optional identifier for the session. If null, a new identifier will be generated.</param>
|
|
/// <param name="cancellationToken">A cancellation token that can be used to cancel the streaming operation.</param>
|
|
/// <returns>A ValueTask that represents the asynchronous operation. The result contains a StreamingRun object for accessing
|
|
/// the streamed workflow output.</returns>
|
|
ValueTask<StreamingRun> OpenStreamingAsync(Workflow workflow, string? sessionId = null, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Initiates an asynchronous streaming execution using the specified input.
|
|
/// </summary>
|
|
/// <remarks>The returned <see cref="StreamingRun"/> provides methods to observe and control
|
|
/// the ongoing streaming execution. The operation will continue until the streaming execution is finished or
|
|
/// cancelled.</remarks>
|
|
/// <typeparam name="TInput">A type of input accepted by the workflow. Must be non-nullable.</typeparam>
|
|
/// <param name="workflow">The workflow to be executed. Must not be <c>null</c>.</param>
|
|
/// <param name="input">The input message to be processed as part of the streaming run.</param>
|
|
/// <param name="sessionId">An optional unique identifier for the session. If not provided, a new identifier will be generated.</param>
|
|
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
|
|
/// <returns>A <see cref="ValueTask{StreamingRun}"/> that represents the asynchronous operation. The result contains a <see
|
|
/// cref="StreamingRun"/> for managing and interacting with the streaming run.</returns>
|
|
ValueTask<StreamingRun> RunStreamingAsync<TInput>(Workflow workflow, TInput input, string? sessionId = null, CancellationToken cancellationToken = default) where TInput : notnull;
|
|
|
|
/// <summary>
|
|
/// Resumes an asynchronous streaming execution for the specified input from a checkpoint.
|
|
/// </summary>
|
|
/// <remarks>If the operation is cancelled via the <paramref name="cancellationToken"/> token, the streaming execution will
|
|
/// be terminated.</remarks>
|
|
/// <param name="workflow">The workflow to be executed. Must not be <c>null</c>.</param>
|
|
/// <param name="fromCheckpoint">The <see cref="CheckpointInfo"/> corresponding to the checkpoint from which to resume.</param>
|
|
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
|
|
/// <returns>A <see cref="StreamingRun"/> that provides access to the results of the streaming run.</returns>
|
|
ValueTask<StreamingRun> ResumeStreamingAsync(Workflow workflow, CheckpointInfo fromCheckpoint, CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Initiates a non-streaming execution of the workflow with the specified input.
|
|
/// </summary>
|
|
/// <remarks>The workflow will run until its first halt, and the returned <see cref="Run"/> will capture
|
|
/// all outgoing events. Use the <c>Run</c> instance to resume execution with responses to outgoing events.</remarks>
|
|
/// <typeparam name="TInput">The type of input accepted by the workflow. Must be non-nullable.</typeparam>
|
|
/// <param name="workflow">The workflow to be executed. Must not be <c>null</c>.</param>
|
|
/// <param name="input">The input message to be processed as part of the run.</param>
|
|
/// <param name="sessionId">An optional unique identifier for the session. If not provided, a new identifier will be generated.</param>
|
|
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
|
|
/// <returns>A <see cref="ValueTask{Run}"/> that represents the asynchronous operation. The result contains a <see
|
|
/// cref="Run"/> for managing and interacting with the streaming run.</returns>
|
|
ValueTask<Run> RunAsync<TInput>(Workflow workflow, TInput input, string? sessionId = null, CancellationToken cancellationToken = default) where TInput : notnull;
|
|
|
|
/// <summary>
|
|
/// Resumes a non-streaming execution of the workflow from a checkpoint.
|
|
/// </summary>
|
|
/// <remarks>The workflow will run until its first halt, and the returned <see cref="Run"/> will capture
|
|
/// all outgoing events. Use the <c>Run</c> instance to resume execution with responses to outgoing events.</remarks>
|
|
/// <param name="workflow">The workflow to be executed. Must not be <c>null</c>.</param>
|
|
/// <param name="fromCheckpoint">The <see cref="CheckpointInfo"/> corresponding to the checkpoint from which to resume.</param>
|
|
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
|
|
/// <returns>A <see cref="ValueTask{Run}"/> that represents the asynchronous operation. The result contains a <see
|
|
/// cref="Run"/> for managing and interacting with the streaming run.</returns>
|
|
ValueTask<Run> ResumeAsync(Workflow workflow, CheckpointInfo fromCheckpoint, CancellationToken cancellationToken = default);
|
|
}
|