// Copyright (c) Microsoft. All rights reserved.
using System.Threading;
using System.Threading.Tasks;
namespace Microsoft.Agents.AI.Workflows;
///
/// Defines an execution environment for running, streaming, and resuming workflows asynchronously, with optional
/// checkpointing and run management capabilities.
///
public interface IWorkflowExecutionEnvironment
{
///
/// Initiates an asynchronous streaming execution using the specified input.
///
/// The returned provides methods to observe and control
/// the ongoing streaming execution. The operation will continue until the streaming execution is finished or
/// cancelled.
/// A type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the streaming run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask StreamAsync(Workflow workflow, TInput input, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Initiates an asynchronous streaming execution using the specified input.
///
/// The returned provides methods to observe and control
/// the ongoing streaming execution. The operation will continue until the streaming execution is finished or
/// cancelled.
/// A type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the streaming run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask StreamAsync(Workflow workflow, TInput input, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Initiates an asynchronous streaming execution using the specified input, with checkpointing.
///
/// The returned provides methods to observe and control
/// the ongoing streaming execution. The operation will continue until the streaming execution is finished or
/// cancelled.
/// The type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the streaming run.
/// The to use with this run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask> StreamAsync(Workflow workflow, TInput input, CheckpointManager checkpointManager, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Initiates an asynchronous streaming execution using the specified input, with checkpointing.
///
/// The returned provides methods to observe and control
/// the ongoing streaming execution. The operation will continue until the streaming execution is finished or
/// cancelled.
/// The type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the streaming run.
/// The to use with this run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask> StreamAsync(Workflow workflow, TInput input, CheckpointManager checkpointManager, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Resumes an asynchronous streaming execution for the specified input from a checkpoint.
///
/// If the operation is cancelled via the token, the streaming execution will
/// be terminated.
/// The workflow to be executed. Must not be null.
/// The corresponding to the checkpoint from which to resume.
/// The to use with this run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that provides access to the results of the streaming run.
ValueTask> ResumeStreamAsync(Workflow workflow, CheckpointInfo fromCheckpoint, CheckpointManager checkpointManager, string? runId = null, CancellationToken cancellationToken = default);
///
/// Resumes an asynchronous streaming execution for the specified input from a checkpoint.
///
/// If the operation is cancelled via the token, the streaming execution will
/// be terminated.
/// The type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The corresponding to the checkpoint from which to resume.
/// The to use with this run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that provides access to the results of the streaming run.
ValueTask> ResumeStreamAsync(Workflow workflow, CheckpointInfo fromCheckpoint, CheckpointManager checkpointManager, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Initiates a non-streaming execution of the workflow with the specified input.
///
/// The workflow will run until its first halt, and the returned will capture
/// all outgoing events. Use the Run instance to resume execution with responses to outgoing events.
/// The type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask RunAsync(Workflow workflow, TInput input, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Initiates a non-streaming execution of the workflow with the specified input.
///
/// The workflow will run until its first halt, and the returned will capture
/// all outgoing events. Use the Run instance to resume execution with responses to outgoing events.
/// The type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask RunAsync(Workflow workflow, TInput input, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Initiates a non-streaming execution of the workflow with the specified input, with checkpointing.
///
/// The workflow will run until its first halt, and the returned will capture
/// all outgoing events. Use the Run instance to resume execution with responses to outgoing events.
/// The type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the run.
/// The to use with this run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask> RunAsync(Workflow workflow, TInput input, CheckpointManager checkpointManager, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Initiates a non-streaming execution of the workflow with the specified input, with checkpointing.
///
/// The workflow will run until its first halt, and the returned will capture
/// all outgoing events. Use the Run instance to resume execution with responses to outgoing events.
/// The type of input accepted by the workflow. Must be non-nullable.
/// The workflow to be executed. Must not be null.
/// The input message to be processed as part of the run.
/// The to use with this run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask> RunAsync(Workflow workflow, TInput input, CheckpointManager checkpointManager, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
///
/// Resumes a non-streaming execution of the workflow from a checkpoint.
///
/// The workflow will run until its first halt, and the returned will capture
/// all outgoing events. Use the Run instance to resume execution with responses to outgoing events.
/// The workflow to be executed. Must not be null.
/// The corresponding to the checkpoint from which to resume.
/// The to use with this run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask> ResumeAsync(Workflow workflow, CheckpointInfo fromCheckpoint, CheckpointManager checkpointManager, string? runId = null, CancellationToken cancellationToken = default);
///
/// Resumes a non-streaming execution of the workflow from a checkpoint.
///
/// The workflow will run until its first halt, and the returned will capture
/// all outgoing events. Use the Run instance to resume execution with responses to outgoing events.
/// The workflow to be executed. Must not be null.
/// The corresponding to the checkpoint from which to resume.
/// The to use with this run.
/// An optional unique identifier for the run. If not provided, a new identifier will be generated.
/// The to monitor for cancellationToken requests. The default is .
/// A that represents the asynchronous operation. The result contains a for managing and interacting with the streaming run.
ValueTask> ResumeAsync(Workflow workflow, CheckpointInfo fromCheckpoint, CheckpointManager checkpointManager, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull;
}