mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
.NET: [Feature Branch] Add basic durable workflow support (#3648)
* Add basic durable workflow support. * PR feedback fixes * Add conditional edge sample. * PR feedback fixes. * Minor cleanup. * Minor cleanup * Minor formatting improvements. * Improve comments/documentation on the execution flow.
This commit is contained in:
Shyju Krishnankutty
committed by
GitHub
Unverified
GitHub
parent
98cd72839e
commit
e8d0bd9051
@@ -141,4 +141,15 @@ public sealed class DurableAgentsOptions
|
||||
{
|
||||
return this._agentTimeToLive.TryGetValue(agentName, out TimeSpan? ttl) ? ttl : this.DefaultTimeToLive;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Determines whether an agent with the specified name is registered.
|
||||
/// </summary>
|
||||
/// <param name="agentName">The name of the agent to locate. Cannot be null.</param>
|
||||
/// <returns>true if an agent with the specified name is registered; otherwise, false.</returns>
|
||||
internal bool ContainsAgent(string agentName)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(agentName);
|
||||
return this._agentFactories.ContainsKey(agentName);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
using System.Text.Json;
|
||||
using System.Text.Json.Serialization.Metadata;
|
||||
using Microsoft.Agents.AI.DurableTask.State;
|
||||
using Microsoft.DurableTask;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask;
|
||||
|
||||
/// <summary>
|
||||
/// Custom data converter for durable agents and workflows that ensures proper JSON serialization.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This converter handles special cases like <see cref="DurableAgentState"/> using source-generated
|
||||
/// JSON contexts for AOT compatibility, and falls back to reflection-based serialization for other types.
|
||||
/// </remarks>
|
||||
internal sealed class DurableDataConverter : DataConverter
|
||||
{
|
||||
private static readonly JsonSerializerOptions s_options = new(DurableAgentJsonUtilities.DefaultOptions)
|
||||
{
|
||||
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
|
||||
PropertyNameCaseInsensitive = true,
|
||||
};
|
||||
|
||||
[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Fallback uses reflection when metadata unavailable.")]
|
||||
[UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Fallback uses reflection when metadata unavailable.")]
|
||||
public override object? Deserialize(string? data, Type targetType)
|
||||
{
|
||||
if (data is null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
if (targetType == typeof(DurableAgentState))
|
||||
{
|
||||
return JsonSerializer.Deserialize(data, DurableAgentStateJsonContext.Default.DurableAgentState);
|
||||
}
|
||||
|
||||
JsonTypeInfo? typeInfo = s_options.GetTypeInfo(targetType);
|
||||
return typeInfo is not null
|
||||
? JsonSerializer.Deserialize(data, typeInfo)
|
||||
: JsonSerializer.Deserialize(data, targetType, s_options);
|
||||
}
|
||||
|
||||
[return: NotNullIfNotNull(nameof(value))]
|
||||
[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Fallback uses reflection when metadata unavailable.")]
|
||||
[UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Fallback uses reflection when metadata unavailable.")]
|
||||
public override string? Serialize(object? value)
|
||||
{
|
||||
if (value is null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
if (value is DurableAgentState durableAgentState)
|
||||
{
|
||||
return JsonSerializer.Serialize(durableAgentState, DurableAgentStateJsonContext.Default.DurableAgentState);
|
||||
}
|
||||
|
||||
JsonTypeInfo? typeInfo = s_options.GetTypeInfo(value.GetType());
|
||||
return typeInfo is not null
|
||||
? JsonSerializer.Serialize(value, typeInfo)
|
||||
: JsonSerializer.Serialize(value, s_options);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Diagnostics;
|
||||
using Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask;
|
||||
|
||||
/// <summary>
|
||||
/// Provides configuration options for durable agents and workflows.
|
||||
/// </summary>
|
||||
[DebuggerDisplay("Workflows = {Workflows.Workflows.Count}, Agents = {Agents.AgentCount}")]
|
||||
public sealed class DurableOptions
|
||||
{
|
||||
/// <summary>
|
||||
/// Initializes a new instance of the <see cref="DurableOptions"/> class.
|
||||
/// </summary>
|
||||
internal DurableOptions()
|
||||
{
|
||||
this.Workflows = new DurableWorkflowOptions(this);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the configuration options for durable agents.
|
||||
/// </summary>
|
||||
public DurableAgentsOptions Agents { get; } = new();
|
||||
|
||||
/// <summary>
|
||||
/// Gets the configuration options for durable workflows.
|
||||
/// </summary>
|
||||
public DurableWorkflowOptions Workflows { get; }
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask;
|
||||
|
||||
/// <summary>
|
||||
/// Marker class used to track whether core durable task services have been registered.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Problem it solves:</b> Users may call configuration methods multiple times:
|
||||
/// <code>
|
||||
/// services.ConfigureDurableOptions(...); // 1st call - registers agent A
|
||||
/// services.ConfigureDurableOptions(...); // 2nd call - registers workflow X
|
||||
/// services.ConfigureDurableOptions(...); // 3rd call - registers agent B and workflow Y
|
||||
/// </code>
|
||||
/// Each call invokes <c>EnsureDurableServicesRegistered</c>. Without this marker, core services like
|
||||
/// <c>AddDurableTaskWorker</c> and <c>AddDurableTaskClient</c> would be registered multiple times,
|
||||
/// causing runtime errors or unexpected behavior.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>How it works:</b>
|
||||
/// <list type="number">
|
||||
/// <item><description>First call: No marker in services → register marker + all core services</description></item>
|
||||
/// <item><description>Subsequent calls: Marker exists → early return, skip core service registration</description></item>
|
||||
/// </list>
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Why not use TryAddSingleton for everything?</b>
|
||||
/// While <c>TryAddSingleton</c> prevents duplicate simple service registrations, it doesn't work for
|
||||
/// complex registrations like <c>AddDurableTaskWorker</c> which have side effects and configure
|
||||
/// internal builders. The marker pattern provides a clean, explicit guard for the entire registration block.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
internal sealed class DurableServicesMarker;
|
||||
@@ -100,4 +100,115 @@ internal static partial class Logs
|
||||
public static partial void LogTTLExpirationTimeCleared(
|
||||
this ILogger logger,
|
||||
AgentSessionId sessionId);
|
||||
|
||||
// Durable workflow logs (EventIds 100-199)
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 100,
|
||||
Level = LogLevel.Information,
|
||||
Message = "Starting workflow '{WorkflowName}' with instance '{InstanceId}'")]
|
||||
public static partial void LogWorkflowStarting(
|
||||
this ILogger logger,
|
||||
string workflowName,
|
||||
string instanceId);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 101,
|
||||
Level = LogLevel.Information,
|
||||
Message = "Superstep {Step}: {Count} active executor(s)")]
|
||||
public static partial void LogSuperstepStarting(
|
||||
this ILogger logger,
|
||||
int step,
|
||||
int count);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 102,
|
||||
Level = LogLevel.Debug,
|
||||
Message = "Superstep {Step} executors: [{Executors}]")]
|
||||
public static partial void LogSuperstepExecutors(
|
||||
this ILogger logger,
|
||||
int step,
|
||||
string executors);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 103,
|
||||
Level = LogLevel.Information,
|
||||
Message = "Workflow completed")]
|
||||
public static partial void LogWorkflowCompleted(
|
||||
this ILogger logger);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 104,
|
||||
Level = LogLevel.Warning,
|
||||
Message = "Workflow '{InstanceId}' terminated early: reached maximum superstep limit ({MaxSupersteps}) with {RemainingExecutors} executor(s) still queued")]
|
||||
public static partial void LogWorkflowMaxSuperstepsExceeded(
|
||||
this ILogger logger,
|
||||
string instanceId,
|
||||
int maxSupersteps,
|
||||
int remainingExecutors);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 105,
|
||||
Level = LogLevel.Debug,
|
||||
Message = "Fan-In executor {ExecutorId}: aggregated {Count} messages from [{Sources}]")]
|
||||
public static partial void LogFanInAggregated(
|
||||
this ILogger logger,
|
||||
string executorId,
|
||||
int count,
|
||||
string sources);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 106,
|
||||
Level = LogLevel.Debug,
|
||||
Message = "Executor '{ExecutorId}' returned result (length: {Length}, messages: {MessageCount})")]
|
||||
public static partial void LogExecutorResultReceived(
|
||||
this ILogger logger,
|
||||
string executorId,
|
||||
int length,
|
||||
int messageCount);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 107,
|
||||
Level = LogLevel.Debug,
|
||||
Message = "Dispatching executor '{ExecutorId}' (agentic: {IsAgentic})")]
|
||||
public static partial void LogDispatchingExecutor(
|
||||
this ILogger logger,
|
||||
string executorId,
|
||||
bool isAgentic);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 108,
|
||||
Level = LogLevel.Warning,
|
||||
Message = "Agent '{AgentName}' not found")]
|
||||
public static partial void LogAgentNotFound(
|
||||
this ILogger logger,
|
||||
string agentName);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 109,
|
||||
Level = LogLevel.Debug,
|
||||
Message = "Edge {Source} -> {Sink}: condition returned false, skipping")]
|
||||
public static partial void LogEdgeConditionFalse(
|
||||
this ILogger logger,
|
||||
string source,
|
||||
string sink);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 110,
|
||||
Level = LogLevel.Warning,
|
||||
Message = "Failed to evaluate condition for edge {Source} -> {Sink}, skipping")]
|
||||
public static partial void LogEdgeConditionEvaluationFailed(
|
||||
this ILogger logger,
|
||||
Exception ex,
|
||||
string source,
|
||||
string sink);
|
||||
|
||||
[LoggerMessage(
|
||||
EventId = 111,
|
||||
Level = LogLevel.Debug,
|
||||
Message = "Edge {Source} -> {Sink}: routing message")]
|
||||
public static partial void LogEdgeRoutingMessage(
|
||||
this ILogger logger,
|
||||
string source,
|
||||
string sink);
|
||||
}
|
||||
|
||||
@@ -24,6 +24,7 @@
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
|
||||
<ProjectReference Include="..\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
|
||||
</ItemGroup>
|
||||
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
using System.Text.Json;
|
||||
using System.Text.Json.Serialization.Metadata;
|
||||
using Microsoft.Agents.AI.DurableTask.State;
|
||||
using Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
using Microsoft.DurableTask;
|
||||
using Microsoft.DurableTask.Client;
|
||||
using Microsoft.DurableTask.Worker;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
using Microsoft.Extensions.DependencyInjection.Extensions;
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask;
|
||||
|
||||
/// <summary>
|
||||
/// Agent-specific extension methods for the <see cref="IServiceCollection"/> class.
|
||||
/// Extension methods for configuring durable agents and workflows with dependency injection.
|
||||
/// </summary>
|
||||
public static class ServiceCollectionExtensions
|
||||
{
|
||||
@@ -30,77 +30,319 @@ public static class ServiceCollectionExtensions
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Configures the Durable Agents services via the service collection.
|
||||
/// Configures durable agents, automatically registering agent entities.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This method provides an agent-focused configuration experience.
|
||||
/// If you need to configure both agents and workflows, consider using
|
||||
/// <see cref="ConfigureDurableOptions"/> instead.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Multiple calls to this method are supported and configurations are composed additively.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
/// <param name="services">The service collection.</param>
|
||||
/// <param name="configure">A delegate to configure the durable agents.</param>
|
||||
/// <param name="workerBuilder">A delegate to configure the Durable Task worker.</param>
|
||||
/// <param name="clientBuilder">A delegate to configure the Durable Task client.</param>
|
||||
/// <returns>The service collection.</returns>
|
||||
/// <param name="workerBuilder">Optional delegate to configure the Durable Task worker.</param>
|
||||
/// <param name="clientBuilder">Optional delegate to configure the Durable Task client.</param>
|
||||
/// <returns>The service collection for chaining.</returns>
|
||||
public static IServiceCollection ConfigureDurableAgents(
|
||||
this IServiceCollection services,
|
||||
Action<DurableAgentsOptions> configure,
|
||||
Action<IDurableTaskWorkerBuilder>? workerBuilder = null,
|
||||
Action<IDurableTaskClientBuilder>? clientBuilder = null)
|
||||
{
|
||||
return services.ConfigureDurableOptions(
|
||||
options => configure(options.Agents),
|
||||
workerBuilder,
|
||||
clientBuilder);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Configures durable workflows, automatically registering orchestrations and activities.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This method provides a workflow-focused configuration experience.
|
||||
/// If you need to configure both agents and workflows, consider using
|
||||
/// <see cref="ConfigureDurableOptions"/> instead.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Multiple calls to this method are supported and configurations are composed additively.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
/// <param name="services">The service collection to configure.</param>
|
||||
/// <param name="configure">A delegate to configure the workflow options.</param>
|
||||
/// <param name="workerBuilder">Optional delegate to configure the durable task worker.</param>
|
||||
/// <param name="clientBuilder">Optional delegate to configure the durable task client.</param>
|
||||
/// <returns>The service collection for chaining.</returns>
|
||||
public static IServiceCollection ConfigureDurableWorkflows(
|
||||
this IServiceCollection services,
|
||||
Action<DurableWorkflowOptions> configure,
|
||||
Action<IDurableTaskWorkerBuilder>? workerBuilder = null,
|
||||
Action<IDurableTaskClientBuilder>? clientBuilder = null)
|
||||
{
|
||||
return services.ConfigureDurableOptions(
|
||||
options => configure(options.Workflows),
|
||||
workerBuilder,
|
||||
clientBuilder);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Configures durable agents and workflows, automatically registering orchestrations, activities, and agent entities.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This is the recommended entry point for configuring durable functionality. It provides unified configuration
|
||||
/// for both agents and workflows through a single <see cref="DurableOptions"/> instance, ensuring agents
|
||||
/// referenced in workflows are automatically registered.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Multiple calls to this method (or to <see cref="ConfigureDurableAgents"/>
|
||||
/// and <see cref="ConfigureDurableWorkflows"/>) are supported and configurations are composed additively.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
/// <param name="services">The service collection to configure.</param>
|
||||
/// <param name="configure">A delegate to configure the durable options for both agents and workflows.</param>
|
||||
/// <param name="workerBuilder">Optional delegate to configure the durable task worker.</param>
|
||||
/// <param name="clientBuilder">Optional delegate to configure the durable task client.</param>
|
||||
/// <returns>The service collection for chaining.</returns>
|
||||
/// <example>
|
||||
/// <code>
|
||||
/// services.ConfigureDurableOptions(options =>
|
||||
/// {
|
||||
/// // Register agents not part of workflows
|
||||
/// options.Agents.AddAIAgent(standaloneAgent);
|
||||
///
|
||||
/// // Register workflows - agents in workflows are auto-registered
|
||||
/// options.Workflows.AddWorkflow(myWorkflow);
|
||||
/// },
|
||||
/// workerBuilder: builder => builder.UseDurableTaskScheduler(connectionString),
|
||||
/// clientBuilder: builder => builder.UseDurableTaskScheduler(connectionString));
|
||||
/// </code>
|
||||
/// </example>
|
||||
public static IServiceCollection ConfigureDurableOptions(
|
||||
this IServiceCollection services,
|
||||
Action<DurableOptions> configure,
|
||||
Action<IDurableTaskWorkerBuilder>? workerBuilder = null,
|
||||
Action<IDurableTaskClientBuilder>? clientBuilder = null)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(services);
|
||||
ArgumentNullException.ThrowIfNull(configure);
|
||||
|
||||
DurableAgentsOptions options = services.ConfigureDurableAgents(configure);
|
||||
// Get or create the shared DurableOptions instance for configuration
|
||||
DurableOptions sharedOptions = GetOrCreateSharedOptions(services);
|
||||
|
||||
// A worker is required to run the agent entities
|
||||
services.AddDurableTaskWorker(builder =>
|
||||
{
|
||||
workerBuilder?.Invoke(builder);
|
||||
// Apply the configuration immediately to capture agent names for keyed service registration
|
||||
configure(sharedOptions);
|
||||
|
||||
builder.AddTasks(registry =>
|
||||
{
|
||||
foreach (string name in options.GetAgentFactories().Keys)
|
||||
{
|
||||
registry.AddEntity<AgentEntity>(AgentSessionId.ToEntityName(name));
|
||||
}
|
||||
});
|
||||
});
|
||||
// Register keyed services for any new agents
|
||||
RegisterAgentKeyedServices(services, sharedOptions);
|
||||
|
||||
// The client is needed to send notifications to the agent entities from non-orchestrator code
|
||||
if (clientBuilder != null)
|
||||
{
|
||||
services.AddDurableTaskClient(clientBuilder);
|
||||
}
|
||||
|
||||
services.AddSingleton<IDurableAgentClient, DefaultDurableAgentClient>();
|
||||
// Register core services only once
|
||||
EnsureDurableServicesRegistered(services, sharedOptions, workerBuilder, clientBuilder);
|
||||
|
||||
return services;
|
||||
}
|
||||
|
||||
// This is internal because it's also used by Microsoft.Azure.Functions.DurableAgents, which is a friend assembly project.
|
||||
internal static DurableAgentsOptions ConfigureDurableAgents(
|
||||
this IServiceCollection services,
|
||||
Action<DurableAgentsOptions> configure)
|
||||
private static DurableOptions GetOrCreateSharedOptions(IServiceCollection services)
|
||||
{
|
||||
DurableAgentsOptions options = new();
|
||||
configure(options);
|
||||
// Look for an existing DurableOptions registration
|
||||
ServiceDescriptor? existingDescriptor = services.FirstOrDefault(
|
||||
d => d.ServiceType == typeof(DurableOptions) && d.ImplementationInstance is not null);
|
||||
|
||||
IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>> agents = options.GetAgentFactories();
|
||||
|
||||
// The agent dictionary contains the real agent factories, which is used by the agent entities.
|
||||
services.AddSingleton(agents);
|
||||
|
||||
// Register the options so AgentEntity can access TTL configuration
|
||||
services.AddSingleton(options);
|
||||
|
||||
// The keyed services are used to resolve durable agent *proxy* instances for external clients.
|
||||
foreach (var factory in agents)
|
||||
if (existingDescriptor?.ImplementationInstance is DurableOptions existing)
|
||||
{
|
||||
services.AddKeyedSingleton(factory.Key, (sp, _) => factory.Value(sp).AsDurableAgentProxy(sp));
|
||||
return existing;
|
||||
}
|
||||
|
||||
// A custom data converter is needed because the default chat client uses camel case for JSON properties,
|
||||
// which is not the default behavior for the Durable Task SDK.
|
||||
services.AddSingleton<DataConverter, DefaultDataConverter>();
|
||||
|
||||
// Create a new shared options instance
|
||||
DurableOptions options = new();
|
||||
services.AddSingleton(options);
|
||||
return options;
|
||||
}
|
||||
|
||||
private static void RegisterAgentKeyedServices(IServiceCollection services, DurableOptions options)
|
||||
{
|
||||
foreach (KeyValuePair<string, Func<IServiceProvider, AIAgent>> factory in options.Agents.GetAgentFactories())
|
||||
{
|
||||
// Only add if not already registered (to support multiple Configure* calls)
|
||||
if (!services.Any(d => d.ServiceType == typeof(AIAgent) && d.IsKeyedService && Equals(d.ServiceKey, factory.Key)))
|
||||
{
|
||||
services.AddKeyedSingleton(factory.Key, (sp, _) => factory.Value(sp).AsDurableAgentProxy(sp));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Ensures that the core durable services are registered only once, regardless of how many
|
||||
/// times the configuration methods are called.
|
||||
/// </summary>
|
||||
private static void EnsureDurableServicesRegistered(
|
||||
IServiceCollection services,
|
||||
DurableOptions sharedOptions,
|
||||
Action<IDurableTaskWorkerBuilder>? workerBuilder,
|
||||
Action<IDurableTaskClientBuilder>? clientBuilder)
|
||||
{
|
||||
// Use a marker to ensure we only register core services once
|
||||
if (services.Any(d => d.ServiceType == typeof(DurableServicesMarker)))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
services.AddSingleton<DurableServicesMarker>();
|
||||
|
||||
services.TryAddSingleton<DurableWorkflowRunner>();
|
||||
|
||||
// Configure Durable Task Worker - capture sharedOptions reference in closure.
|
||||
// The options object is populated by all Configure* calls before the worker starts.
|
||||
services.AddDurableTaskWorker(builder =>
|
||||
{
|
||||
workerBuilder?.Invoke(builder);
|
||||
|
||||
builder.AddTasks(registry => RegisterTasksFromOptions(registry, sharedOptions));
|
||||
});
|
||||
|
||||
// Configure Durable Task Client
|
||||
if (clientBuilder is not null)
|
||||
{
|
||||
services.AddDurableTaskClient(clientBuilder);
|
||||
}
|
||||
|
||||
// Register workflow and agent services
|
||||
services.TryAddSingleton<DurableWorkflowClient>();
|
||||
services.TryAddSingleton<IWorkflowClient>(sp => sp.GetRequiredService<DurableWorkflowClient>());
|
||||
services.TryAddSingleton<DataConverter, DurableDataConverter>();
|
||||
services.TryAddSingleton<IDurableAgentClient, DefaultDurableAgentClient>();
|
||||
|
||||
// Register agent factories resolver - returns factories from the shared options
|
||||
services.TryAddSingleton(
|
||||
sp => sp.GetRequiredService<DurableOptions>().Agents.GetAgentFactories());
|
||||
|
||||
// Register DurableAgentsOptions resolver
|
||||
services.TryAddSingleton(sp => sp.GetRequiredService<DurableOptions>().Agents);
|
||||
}
|
||||
|
||||
private static void RegisterTasksFromOptions(DurableTaskRegistry registry, DurableOptions durableOptions)
|
||||
{
|
||||
// Build registrations for all workflows including sub-workflows
|
||||
List<WorkflowRegistrationInfo> registrations = [];
|
||||
HashSet<string> registeredActivities = [];
|
||||
HashSet<string> registeredOrchestrations = [];
|
||||
|
||||
foreach (Workflow workflow in durableOptions.Workflows.Workflows.Values.ToList())
|
||||
{
|
||||
BuildWorkflowRegistrationRecursive(
|
||||
workflow,
|
||||
durableOptions.Workflows,
|
||||
registrations,
|
||||
registeredActivities,
|
||||
registeredOrchestrations);
|
||||
}
|
||||
|
||||
IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>> agentFactories =
|
||||
durableOptions.Agents.GetAgentFactories();
|
||||
|
||||
// Register orchestrations and activities
|
||||
foreach (WorkflowRegistrationInfo registration in registrations)
|
||||
{
|
||||
// Register with DurableWorkflowInput<object> - the DataConverter handles serialization/deserialization
|
||||
registry.AddOrchestratorFunc<DurableWorkflowInput<object>, string>(
|
||||
registration.OrchestrationName,
|
||||
(context, input) => RunWorkflowOrchestrationAsync(context, input, durableOptions));
|
||||
|
||||
foreach (ActivityRegistrationInfo activity in registration.Activities)
|
||||
{
|
||||
ExecutorBinding binding = activity.Binding;
|
||||
registry.AddActivityFunc<string, string>(
|
||||
activity.ActivityName,
|
||||
(context, input) => DurableActivityExecutor.ExecuteAsync(binding, input));
|
||||
}
|
||||
}
|
||||
|
||||
// Register agent entities
|
||||
foreach (string agentName in agentFactories.Keys)
|
||||
{
|
||||
registry.AddEntity<AgentEntity>(AgentSessionId.ToEntityName(agentName));
|
||||
}
|
||||
}
|
||||
|
||||
private static void BuildWorkflowRegistrationRecursive(
|
||||
Workflow workflow,
|
||||
DurableWorkflowOptions workflowOptions,
|
||||
List<WorkflowRegistrationInfo> registrations,
|
||||
HashSet<string> registeredActivities,
|
||||
HashSet<string> registeredOrchestrations)
|
||||
{
|
||||
string orchestrationName = WorkflowNamingHelper.ToOrchestrationFunctionName(workflow.Name!);
|
||||
|
||||
if (!registeredOrchestrations.Add(orchestrationName))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
registrations.Add(BuildWorkflowRegistration(workflow, registeredActivities));
|
||||
|
||||
// Process subworkflows recursively to register them as separate orchestrations
|
||||
foreach (SubworkflowBinding subworkflowBinding in workflow.ReflectExecutors()
|
||||
.Select(e => e.Value)
|
||||
.OfType<SubworkflowBinding>())
|
||||
{
|
||||
Workflow subWorkflow = subworkflowBinding.WorkflowInstance;
|
||||
workflowOptions.AddWorkflow(subWorkflow);
|
||||
|
||||
BuildWorkflowRegistrationRecursive(
|
||||
subWorkflow,
|
||||
workflowOptions,
|
||||
registrations,
|
||||
registeredActivities,
|
||||
registeredOrchestrations);
|
||||
}
|
||||
}
|
||||
|
||||
private static WorkflowRegistrationInfo BuildWorkflowRegistration(
|
||||
Workflow workflow,
|
||||
HashSet<string> registeredActivities)
|
||||
{
|
||||
string orchestrationName = WorkflowNamingHelper.ToOrchestrationFunctionName(workflow.Name!);
|
||||
Dictionary<string, ExecutorBinding> executorBindings = workflow.ReflectExecutors();
|
||||
List<ActivityRegistrationInfo> activities = [];
|
||||
|
||||
// Filter out AI agents and subworkflows - they are not registered as activities.
|
||||
// AI agents use Durable Entities for stateful execution, and subworkflows are
|
||||
// registered as separate orchestrations via BuildWorkflowRegistrationRecursive.
|
||||
foreach (KeyValuePair<string, ExecutorBinding> entry in executorBindings
|
||||
.Where(e => e.Value is not AIAgentBinding and not SubworkflowBinding))
|
||||
{
|
||||
string executorName = WorkflowNamingHelper.GetExecutorName(entry.Key);
|
||||
string activityName = WorkflowNamingHelper.ToOrchestrationFunctionName(executorName);
|
||||
|
||||
if (registeredActivities.Add(activityName))
|
||||
{
|
||||
activities.Add(new ActivityRegistrationInfo(activityName, entry.Value));
|
||||
}
|
||||
}
|
||||
|
||||
return new WorkflowRegistrationInfo(orchestrationName, activities);
|
||||
}
|
||||
|
||||
private static async Task<string> RunWorkflowOrchestrationAsync(
|
||||
TaskOrchestrationContext context,
|
||||
DurableWorkflowInput<object> workflowInput,
|
||||
DurableOptions durableOptions)
|
||||
{
|
||||
ILogger logger = context.CreateReplaySafeLogger("DurableWorkflow");
|
||||
DurableWorkflowRunner runner = new(durableOptions);
|
||||
|
||||
// ConfigureAwait(true) is required in orchestration code for deterministic replay.
|
||||
return await runner.RunWorkflowOrchestrationAsync(context, workflowInput, logger).ConfigureAwait(true);
|
||||
}
|
||||
|
||||
private sealed record WorkflowRegistrationInfo(string OrchestrationName, List<ActivityRegistrationInfo> Activities);
|
||||
|
||||
private sealed record ActivityRegistrationInfo(string ActivityName, ExecutorBinding Binding);
|
||||
|
||||
/// <summary>
|
||||
/// Validates that an agent with the specified name has been registered.
|
||||
/// </summary>
|
||||
@@ -124,63 +366,4 @@ public static class ServiceCollectionExtensions
|
||||
throw new AgentNotRegisteredException(agentName);
|
||||
}
|
||||
}
|
||||
|
||||
private sealed class DefaultDataConverter : DataConverter
|
||||
{
|
||||
// Use durable agent options (web defaults + camel case by default) with case-insensitive matching.
|
||||
// We clone to apply naming/casing tweaks while retaining source-generated metadata where available.
|
||||
private static readonly JsonSerializerOptions s_options = new(DurableAgentJsonUtilities.DefaultOptions)
|
||||
{
|
||||
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
|
||||
PropertyNameCaseInsensitive = true,
|
||||
};
|
||||
|
||||
[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Fallback path uses reflection when metadata unavailable.")]
|
||||
[UnconditionalSuppressMessage("ReflectionAnalysis", "IL3050", Justification = "Fallback path uses reflection when metadata unavailable.")]
|
||||
public override object? Deserialize(string? data, Type targetType)
|
||||
{
|
||||
if (data is null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
if (targetType == typeof(DurableAgentState))
|
||||
{
|
||||
return JsonSerializer.Deserialize(data, DurableAgentStateJsonContext.Default.DurableAgentState);
|
||||
}
|
||||
|
||||
JsonTypeInfo? typeInfo = s_options.GetTypeInfo(targetType);
|
||||
if (typeInfo is JsonTypeInfo typedInfo)
|
||||
{
|
||||
return JsonSerializer.Deserialize(data, typedInfo);
|
||||
}
|
||||
|
||||
// Fallback (may trigger trimming/AOT warnings for unsupported dynamic types).
|
||||
return JsonSerializer.Deserialize(data, targetType, s_options);
|
||||
}
|
||||
|
||||
[return: NotNullIfNotNull(nameof(value))]
|
||||
[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Fallback path uses reflection when metadata unavailable.")]
|
||||
[UnconditionalSuppressMessage("ReflectionAnalysis", "IL3050", Justification = "Fallback path uses reflection when metadata unavailable.")]
|
||||
public override string? Serialize(object? value)
|
||||
{
|
||||
if (value is null)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
if (value is DurableAgentState durableAgentState)
|
||||
{
|
||||
return JsonSerializer.Serialize(durableAgentState, DurableAgentStateJsonContext.Default.DurableAgentState);
|
||||
}
|
||||
|
||||
JsonTypeInfo? typeInfo = s_options.GetTypeInfo(value.GetType());
|
||||
if (typeInfo is JsonTypeInfo typedInfo)
|
||||
{
|
||||
return JsonSerializer.Serialize(value, typedInfo);
|
||||
}
|
||||
|
||||
return JsonSerializer.Serialize(value, s_options);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,107 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Diagnostics;
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
using System.Text.Json;
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// A workflow context for durable activity execution.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Some of the methods are returning default for this version. Those method will be updated with real implementations in follow up PRs.
|
||||
/// </remarks>
|
||||
[DebuggerDisplay("Executor = {_executor.Id}, StateEntries = {_initialState.Count}")]
|
||||
internal sealed class DurableActivityContext : IWorkflowContext
|
||||
{
|
||||
private readonly Dictionary<string, string> _initialState;
|
||||
private readonly Executor _executor;
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of the <see cref="DurableActivityContext"/> class.
|
||||
/// </summary>
|
||||
/// <param name="initialState">The shared state passed from the orchestration.</param>
|
||||
/// <param name="executor">The executor running in this context.</param>
|
||||
internal DurableActivityContext(Dictionary<string, string>? initialState, Executor executor)
|
||||
{
|
||||
this._executor = executor;
|
||||
this._initialState = initialState ?? [];
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the messages sent during activity execution via <see cref="SendMessageAsync"/>.
|
||||
/// </summary>
|
||||
internal List<SentMessageInfo> SentMessages { get; } = [];
|
||||
|
||||
/// <inheritdoc/>
|
||||
public ValueTask AddEventAsync(
|
||||
WorkflowEvent workflowEvent,
|
||||
CancellationToken cancellationToken = default) => default;
|
||||
|
||||
/// <inheritdoc/>
|
||||
[UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Serializing workflow message types registered at startup.")]
|
||||
[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Serializing workflow message types registered at startup.")]
|
||||
public ValueTask SendMessageAsync(
|
||||
object message,
|
||||
string? targetId = null,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
if (message is not null)
|
||||
{
|
||||
Type messageType = message.GetType();
|
||||
this.SentMessages.Add(new SentMessageInfo
|
||||
{
|
||||
Message = JsonSerializer.Serialize(message, messageType),
|
||||
TypeName = messageType.FullName ?? messageType.Name
|
||||
});
|
||||
}
|
||||
|
||||
return default;
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public ValueTask YieldOutputAsync(
|
||||
object output,
|
||||
CancellationToken cancellationToken = default) => default;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public ValueTask RequestHaltAsync() => default;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public ValueTask<T?> ReadStateAsync<T>(
|
||||
string key,
|
||||
string? scopeName = null,
|
||||
CancellationToken cancellationToken = default) => default;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public ValueTask<T> ReadOrInitStateAsync<T>(
|
||||
string key,
|
||||
Func<T> initialStateFactory,
|
||||
string? scopeName = null,
|
||||
CancellationToken cancellationToken = default) => default;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public ValueTask<HashSet<string>> ReadStateKeysAsync(
|
||||
string? scopeName = null,
|
||||
CancellationToken cancellationToken = default) => default;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public ValueTask QueueStateUpdateAsync<T>(
|
||||
string key,
|
||||
T? value,
|
||||
string? scopeName = null,
|
||||
CancellationToken cancellationToken = default) => default;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public ValueTask QueueClearScopeAsync(
|
||||
string? scopeName = null,
|
||||
CancellationToken cancellationToken = default) => default;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public IReadOnlyDictionary<string, string>? TraceContext => null;
|
||||
|
||||
/// <inheritdoc/>
|
||||
public bool ConcurrentRunsEnabled => false;
|
||||
}
|
||||
@@ -0,0 +1,146 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
using System.Text.Json;
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
using Microsoft.Agents.AI.Workflows.Checkpointing;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Executes workflow activities by invoking executor bindings and handling serialization.
|
||||
/// </summary>
|
||||
[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Workflow and executor types are registered at startup.")]
|
||||
[UnconditionalSuppressMessage("Trimming", "IL2057", Justification = "Workflow and executor types are registered at startup.")]
|
||||
[UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Workflow and executor types are registered at startup.")]
|
||||
internal static class DurableActivityExecutor
|
||||
{
|
||||
/// <summary>
|
||||
/// Shared JSON options that match the DurableDataConverter settings.
|
||||
/// </summary>
|
||||
private static readonly JsonSerializerOptions s_jsonOptions = new()
|
||||
{
|
||||
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
|
||||
PropertyNameCaseInsensitive = true
|
||||
};
|
||||
|
||||
/// <summary>
|
||||
/// Executes an activity using the provided executor binding.
|
||||
/// </summary>
|
||||
/// <param name="binding">The executor binding to invoke.</param>
|
||||
/// <param name="input">The serialized input string.</param>
|
||||
/// <param name="cancellationToken">A token to cancel the operation.</param>
|
||||
/// <returns>The serialized activity output.</returns>
|
||||
/// <exception cref="ArgumentNullException">Thrown when <paramref name="binding"/> is null.</exception>
|
||||
/// <exception cref="InvalidOperationException">Thrown when the executor factory is not configured.</exception>
|
||||
internal static async Task<string> ExecuteAsync(
|
||||
ExecutorBinding binding,
|
||||
string input,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(binding);
|
||||
|
||||
if (binding.FactoryAsync is null)
|
||||
{
|
||||
throw new InvalidOperationException($"Executor binding for '{binding.Id}' does not have a factory configured.");
|
||||
}
|
||||
|
||||
DurableActivityInput? inputWithState = TryDeserializeActivityInput(input);
|
||||
string executorInput = inputWithState?.Input ?? input;
|
||||
Dictionary<string, string> sharedState = inputWithState?.State ?? [];
|
||||
|
||||
Executor executor = await binding.FactoryAsync(binding.Id).ConfigureAwait(false);
|
||||
Type inputType = ResolveInputType(inputWithState?.InputTypeName, executor.InputTypes);
|
||||
object typedInput = DeserializeInput(executorInput, inputType);
|
||||
|
||||
DurableActivityContext workflowContext = new(sharedState, executor);
|
||||
object? result = await executor.ExecuteAsync(
|
||||
typedInput,
|
||||
new TypeId(inputType),
|
||||
workflowContext,
|
||||
cancellationToken).ConfigureAwait(false);
|
||||
|
||||
return SerializeActivityOutput(result, workflowContext);
|
||||
}
|
||||
|
||||
private static string SerializeActivityOutput(object? result, DurableActivityContext context)
|
||||
{
|
||||
DurableActivityOutput output = new()
|
||||
{
|
||||
Result = SerializeResult(result),
|
||||
SentMessages = context.SentMessages.ConvertAll(m => new SentMessageInfo
|
||||
{
|
||||
Message = m.Message,
|
||||
TypeName = m.TypeName
|
||||
})
|
||||
};
|
||||
|
||||
return JsonSerializer.Serialize(output, DurableWorkflowJsonContext.Default.DurableActivityOutput);
|
||||
}
|
||||
|
||||
private static string SerializeResult(object? result)
|
||||
{
|
||||
if (result is null)
|
||||
{
|
||||
return string.Empty;
|
||||
}
|
||||
|
||||
if (result is string str)
|
||||
{
|
||||
return str;
|
||||
}
|
||||
|
||||
return JsonSerializer.Serialize(result, result.GetType(), s_jsonOptions);
|
||||
}
|
||||
|
||||
private static DurableActivityInput? TryDeserializeActivityInput(string input)
|
||||
{
|
||||
try
|
||||
{
|
||||
return JsonSerializer.Deserialize(input, DurableWorkflowJsonContext.Default.DurableActivityInput);
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
private static object DeserializeInput(string input, Type targetType)
|
||||
{
|
||||
if (targetType == typeof(string))
|
||||
{
|
||||
return input;
|
||||
}
|
||||
|
||||
return JsonSerializer.Deserialize(input, targetType, s_jsonOptions)
|
||||
?? throw new InvalidOperationException($"Failed to deserialize input to type '{targetType.Name}'.");
|
||||
}
|
||||
|
||||
private static Type ResolveInputType(string? inputTypeName, ISet<Type> supportedTypes)
|
||||
{
|
||||
if (string.IsNullOrEmpty(inputTypeName))
|
||||
{
|
||||
return supportedTypes.FirstOrDefault() ?? typeof(string);
|
||||
}
|
||||
|
||||
Type? matchedType = supportedTypes.FirstOrDefault(t =>
|
||||
t.AssemblyQualifiedName == inputTypeName ||
|
||||
t.FullName == inputTypeName ||
|
||||
t.Name == inputTypeName);
|
||||
|
||||
if (matchedType is not null)
|
||||
{
|
||||
return matchedType;
|
||||
}
|
||||
|
||||
Type? loadedType = Type.GetType(inputTypeName);
|
||||
|
||||
// Fall back if type is string but executor doesn't support string
|
||||
if (loadedType == typeof(string) && !supportedTypes.Contains(typeof(string)))
|
||||
{
|
||||
return supportedTypes.FirstOrDefault() ?? typeof(string);
|
||||
}
|
||||
|
||||
return loadedType ?? supportedTypes.FirstOrDefault() ?? typeof(string);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Input payload for activity execution, containing the input and other metadata.
|
||||
/// </summary>
|
||||
internal sealed class DurableActivityInput
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets or sets the serialized executor input.
|
||||
/// </summary>
|
||||
public string? Input { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets or sets the assembly-qualified type name of the input, used for proper deserialization.
|
||||
/// </summary>
|
||||
public string? InputTypeName { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets or sets the shared state dictionary (scope-prefixed key -> serialized value).
|
||||
/// </summary>
|
||||
public Dictionary<string, string> State { get; set; } = [];
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Output payload from activity execution, containing the result and other metadata.
|
||||
/// </summary>
|
||||
internal sealed class DurableActivityOutput
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets or sets the serialized result of the activity.
|
||||
/// </summary>
|
||||
public string? Result { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets or sets the collection of messages that have been sent.
|
||||
/// </summary>
|
||||
public List<SentMessageInfo> SentMessages { get; set; } = [];
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
// ConfigureAwait Usage in Orchestration Code:
|
||||
// This file uses ConfigureAwait(true) because it runs within orchestration context.
|
||||
// Durable Task orchestrations require deterministic replay - the same code must execute
|
||||
// identically across replays. ConfigureAwait(true) ensures continuations run on the
|
||||
// orchestration's synchronization context, which is essential for replay correctness.
|
||||
// Using ConfigureAwait(false) here could cause non-deterministic behavior during replay.
|
||||
|
||||
using System.Text.Json;
|
||||
using Microsoft.DurableTask;
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Dispatches workflow executors to either activities or AI agents.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Called during the dispatch phase of each superstep by
|
||||
/// <c>DurableWorkflowRunner.DispatchExecutorsInParallelAsync</c>. For each executor that has
|
||||
/// pending input, this dispatcher determines whether the executor is an AI agent (stateful,
|
||||
/// backed by Durable Entities) or a regular activity, and invokes the appropriate Durable Task API.
|
||||
/// The serialised string result is returned to the runner for the routing phase.
|
||||
/// </remarks>
|
||||
internal static class DurableExecutorDispatcher
|
||||
{
|
||||
/// <summary>
|
||||
/// Dispatches an executor based on its type (activity or AI agent).
|
||||
/// </summary>
|
||||
/// <param name="context">The task orchestration context.</param>
|
||||
/// <param name="executorInfo">Information about the executor to dispatch.</param>
|
||||
/// <param name="envelope">The message envelope containing input and type information.</param>
|
||||
/// <param name="logger">The logger for tracing.</param>
|
||||
/// <returns>The result from the executor.</returns>
|
||||
internal static async Task<string> DispatchAsync(
|
||||
TaskOrchestrationContext context,
|
||||
WorkflowExecutorInfo executorInfo,
|
||||
DurableMessageEnvelope envelope,
|
||||
ILogger logger)
|
||||
{
|
||||
logger.LogDispatchingExecutor(executorInfo.ExecutorId, executorInfo.IsAgenticExecutor);
|
||||
|
||||
if (executorInfo.IsAgenticExecutor)
|
||||
{
|
||||
return await ExecuteAgentAsync(context, executorInfo, logger, envelope.Message).ConfigureAwait(true);
|
||||
}
|
||||
|
||||
return await ExecuteActivityAsync(context, executorInfo, envelope.Message, envelope.InputTypeName).ConfigureAwait(true);
|
||||
}
|
||||
|
||||
private static async Task<string> ExecuteActivityAsync(
|
||||
TaskOrchestrationContext context,
|
||||
WorkflowExecutorInfo executorInfo,
|
||||
string input,
|
||||
string? inputTypeName)
|
||||
{
|
||||
string executorName = WorkflowNamingHelper.GetExecutorName(executorInfo.ExecutorId);
|
||||
string activityName = WorkflowNamingHelper.ToOrchestrationFunctionName(executorName);
|
||||
|
||||
DurableActivityInput activityInput = new()
|
||||
{
|
||||
Input = input,
|
||||
InputTypeName = inputTypeName
|
||||
};
|
||||
|
||||
string serializedInput = JsonSerializer.Serialize(activityInput, DurableWorkflowJsonContext.Default.DurableActivityInput);
|
||||
|
||||
return await context.CallActivityAsync<string>(activityName, serializedInput).ConfigureAwait(true);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Executes an AI agent executor through Durable Entities.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// AI agents are stateful and maintain conversation history. They use Durable Entities
|
||||
/// to persist state across orchestration replays.
|
||||
/// </remarks>
|
||||
private static async Task<string> ExecuteAgentAsync(
|
||||
TaskOrchestrationContext context,
|
||||
WorkflowExecutorInfo executorInfo,
|
||||
ILogger logger,
|
||||
string input)
|
||||
{
|
||||
string agentName = WorkflowNamingHelper.GetExecutorName(executorInfo.ExecutorId);
|
||||
DurableAIAgent agent = context.GetAgent(agentName);
|
||||
|
||||
if (agent is null)
|
||||
{
|
||||
logger.LogAgentNotFound(agentName);
|
||||
return $"Agent '{agentName}' not found";
|
||||
}
|
||||
|
||||
AgentSession session = await agent.GetNewSessionAsync().ConfigureAwait(true);
|
||||
AgentResponse response = await agent.RunAsync(input, session).ConfigureAwait(true);
|
||||
|
||||
return response.Text;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a message envelope for durable workflow message passing.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This is the durable equivalent of <c>MessageEnvelope</c> in the in-process runner.
|
||||
/// Unlike the in-process version which holds native .NET objects, this envelope
|
||||
/// contains serialized JSON strings suitable for Durable Task activities.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
internal sealed class DurableMessageEnvelope
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets or sets the serialized JSON message content.
|
||||
/// </summary>
|
||||
public required string Message { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets or sets the full type name of the message for deserialization.
|
||||
/// </summary>
|
||||
public string? InputTypeName { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets or sets the ID of the executor that produced this message.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Used for tracing and debugging. Null for initial workflow input.
|
||||
/// </remarks>
|
||||
public string? SourceExecutorId { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Creates a new message envelope.
|
||||
/// </summary>
|
||||
/// <param name="message">The serialized JSON message content.</param>
|
||||
/// <param name="inputTypeName">The full type name of the message for deserialization.</param>
|
||||
/// <param name="sourceExecutorId">The ID of the executor that produced this message, or null for initial input.</param>
|
||||
/// <returns>A new <see cref="DurableMessageEnvelope"/> instance.</returns>
|
||||
internal static DurableMessageEnvelope Create(string message, string? inputTypeName, string? sourceExecutorId = null)
|
||||
{
|
||||
return new DurableMessageEnvelope
|
||||
{
|
||||
Message = message,
|
||||
InputTypeName = inputTypeName,
|
||||
SourceExecutorId = sourceExecutorId
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
using Microsoft.DurableTask;
|
||||
using Microsoft.DurableTask.Client;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Provides a durable task-based implementation of <see cref="IWorkflowClient"/> for running
|
||||
/// workflows as durable orchestrations.
|
||||
/// </summary>
|
||||
internal sealed class DurableWorkflowClient : IWorkflowClient
|
||||
{
|
||||
private readonly DurableTaskClient _client;
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of the <see cref="DurableWorkflowClient"/> class.
|
||||
/// </summary>
|
||||
/// <param name="client">The durable task client for orchestration operations.</param>
|
||||
/// <exception cref="ArgumentNullException">Thrown when <paramref name="client"/> is null.</exception>
|
||||
public DurableWorkflowClient(DurableTaskClient client)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(client);
|
||||
this._client = client;
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public async ValueTask<IWorkflowRun> RunAsync<TInput>(
|
||||
Workflow workflow,
|
||||
TInput input,
|
||||
string? runId = null,
|
||||
CancellationToken cancellationToken = default)
|
||||
where TInput : notnull
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(workflow);
|
||||
|
||||
if (string.IsNullOrEmpty(workflow.Name))
|
||||
{
|
||||
throw new ArgumentException("Workflow must have a valid Name property.", nameof(workflow));
|
||||
}
|
||||
|
||||
DurableWorkflowInput<TInput> workflowInput = new() { Input = input };
|
||||
|
||||
string instanceId = await this._client.ScheduleNewOrchestrationInstanceAsync(
|
||||
orchestratorName: WorkflowNamingHelper.ToOrchestrationFunctionName(workflow.Name),
|
||||
input: workflowInput,
|
||||
options: runId is not null ? new StartOrchestrationOptions(runId) : null,
|
||||
cancellation: cancellationToken).ConfigureAwait(false);
|
||||
|
||||
return new DurableWorkflowRun(this._client, instanceId, workflow.Name);
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public ValueTask<IWorkflowRun> RunAsync(
|
||||
Workflow workflow,
|
||||
string input,
|
||||
string? runId = null,
|
||||
CancellationToken cancellationToken = default)
|
||||
=> this.RunAsync<string>(workflow, input, runId, cancellationToken);
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Represents the input envelope for a durable workflow orchestration.
|
||||
/// </summary>
|
||||
/// <typeparam name="TInput">The type of the workflow input.</typeparam>
|
||||
internal sealed class DurableWorkflowInput<TInput>
|
||||
where TInput : notnull
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets the workflow input data.
|
||||
/// </summary>
|
||||
public required TInput Input { get; init; }
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Source-generated JSON serialization context for durable workflow types.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This context provides AOT-compatible and trimmer-safe JSON serialization for the
|
||||
/// internal data transfer types used by the durable workflow infrastructure:
|
||||
/// </para>
|
||||
/// <list type="bullet">
|
||||
/// <item><description><see cref="DurableActivityInput"/>: Activity input wrapper with state</description></item>
|
||||
/// <item><description><see cref="DurableActivityOutput"/>: Activity output wrapper with results and events</description></item>
|
||||
/// <item><description><see cref="SentMessageInfo"/>: Messages sent via SendMessageAsync</description></item>
|
||||
/// </list>
|
||||
/// <para>
|
||||
/// Note: User-defined executor input/output types still use reflection-based serialization
|
||||
/// since their types are not known at compile time.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
[JsonSourceGenerationOptions(
|
||||
WriteIndented = false,
|
||||
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
|
||||
PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
|
||||
[JsonSerializable(typeof(DurableActivityInput))]
|
||||
[JsonSerializable(typeof(DurableActivityOutput))]
|
||||
[JsonSerializable(typeof(SentMessageInfo))]
|
||||
[JsonSerializable(typeof(List<SentMessageInfo>))]
|
||||
[JsonSerializable(typeof(Dictionary<string, string?>))]
|
||||
internal partial class DurableWorkflowJsonContext : JsonSerializerContext;
|
||||
@@ -0,0 +1,107 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Diagnostics;
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Provides configuration options for managing durable workflows within an application.
|
||||
/// </summary>
|
||||
[DebuggerDisplay("Workflows = {Workflows.Count}")]
|
||||
public sealed class DurableWorkflowOptions
|
||||
{
|
||||
private readonly Dictionary<string, Workflow> _workflows = new(StringComparer.OrdinalIgnoreCase);
|
||||
private readonly DurableOptions? _parentOptions;
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of the <see cref="DurableWorkflowOptions"/> class.
|
||||
/// </summary>
|
||||
/// <param name="parentOptions">Optional parent options container for accessing related configuration.</param>
|
||||
internal DurableWorkflowOptions(DurableOptions? parentOptions = null)
|
||||
{
|
||||
this._parentOptions = parentOptions;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the collection of workflows available in the current context, keyed by their unique names.
|
||||
/// </summary>
|
||||
public IReadOnlyDictionary<string, Workflow> Workflows => this._workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Gets the executor registry for direct executor lookup.
|
||||
/// </summary>
|
||||
internal ExecutorRegistry Executors { get; } = new();
|
||||
|
||||
/// <summary>
|
||||
/// Adds a workflow to the collection for processing or execution.
|
||||
/// </summary>
|
||||
/// <param name="workflow">The workflow instance to add. Cannot be null.</param>
|
||||
/// <remarks>
|
||||
/// When a workflow is added, all executors are registered in the executor registry.
|
||||
/// Any AI agent executors will also be automatically registered with the
|
||||
/// <see cref="DurableAgentsOptions"/> if available.
|
||||
/// </remarks>
|
||||
/// <exception cref="ArgumentNullException">Thrown when <paramref name="workflow"/> is null.</exception>
|
||||
/// <exception cref="ArgumentException">Thrown when the workflow does not have a valid name.</exception>
|
||||
public void AddWorkflow(Workflow workflow)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(workflow);
|
||||
|
||||
if (string.IsNullOrEmpty(workflow.Name))
|
||||
{
|
||||
throw new ArgumentException("Workflow must have a valid Name property.", nameof(workflow));
|
||||
}
|
||||
|
||||
this._workflows[workflow.Name] = workflow;
|
||||
this.RegisterWorkflowExecutors(workflow);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds a collection of workflows to the current instance.
|
||||
/// </summary>
|
||||
/// <param name="workflows">The collection of <see cref="Workflow"/> objects to add.</param>
|
||||
/// <exception cref="ArgumentNullException">Thrown when <paramref name="workflows"/> is null.</exception>
|
||||
public void AddWorkflows(params Workflow[] workflows)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(workflows);
|
||||
|
||||
foreach (Workflow workflow in workflows)
|
||||
{
|
||||
this.AddWorkflow(workflow);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Registers all executors from a workflow, including AI agents if agent options are available.
|
||||
/// </summary>
|
||||
private void RegisterWorkflowExecutors(Workflow workflow)
|
||||
{
|
||||
DurableAgentsOptions? agentOptions = this._parentOptions?.Agents;
|
||||
|
||||
foreach ((string executorId, ExecutorBinding binding) in workflow.ReflectExecutors())
|
||||
{
|
||||
string executorName = WorkflowNamingHelper.GetExecutorName(executorId);
|
||||
this.Executors.Register(executorName, executorId, workflow);
|
||||
|
||||
TryRegisterAgent(binding, agentOptions);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Registers an AI agent with the agent options if the binding contains an unregistered agent.
|
||||
/// </summary>
|
||||
private static void TryRegisterAgent(ExecutorBinding binding, DurableAgentsOptions? agentOptions)
|
||||
{
|
||||
if (agentOptions is null)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
if (binding.RawValue is AIAgent { Name: not null } agent
|
||||
&& !agentOptions.ContainsAgent(agent.Name))
|
||||
{
|
||||
agentOptions.AddAIAgent(agent);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,116 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Diagnostics;
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
using Microsoft.DurableTask;
|
||||
using Microsoft.DurableTask.Client;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a durable workflow run that tracks execution status and provides access to workflow events.
|
||||
/// </summary>
|
||||
[DebuggerDisplay("{WorkflowName} ({RunId})")]
|
||||
internal sealed class DurableWorkflowRun : IAwaitableWorkflowRun
|
||||
{
|
||||
private readonly DurableTaskClient _client;
|
||||
private readonly List<WorkflowEvent> _eventSink = [];
|
||||
private int _lastBookmark;
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of the <see cref="DurableWorkflowRun"/> class.
|
||||
/// </summary>
|
||||
/// <param name="client">The durable task client for orchestration operations.</param>
|
||||
/// <param name="instanceId">The unique instance ID for this orchestration run.</param>
|
||||
/// <param name="workflowName">The name of the workflow being executed.</param>
|
||||
internal DurableWorkflowRun(DurableTaskClient client, string instanceId, string workflowName)
|
||||
{
|
||||
this._client = client;
|
||||
this.RunId = instanceId;
|
||||
this.WorkflowName = workflowName;
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public string RunId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets the name of the workflow being executed.
|
||||
/// </summary>
|
||||
public string WorkflowName { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Waits for the workflow to complete and returns the result.
|
||||
/// </summary>
|
||||
/// <typeparam name="TResult">The expected result type.</typeparam>
|
||||
/// <param name="cancellationToken">A cancellation token to observe.</param>
|
||||
/// <returns>The result of the workflow execution.</returns>
|
||||
/// <exception cref="TaskFailedException">Thrown when the workflow failed.</exception>
|
||||
/// <exception cref="InvalidOperationException">Thrown when the workflow was terminated or ended with an unexpected status.</exception>
|
||||
public async ValueTask<TResult?> WaitForCompletionAsync<TResult>(CancellationToken cancellationToken = default)
|
||||
{
|
||||
OrchestrationMetadata metadata = await this._client.WaitForInstanceCompletionAsync(
|
||||
this.RunId,
|
||||
getInputsAndOutputs: true,
|
||||
cancellation: cancellationToken).ConfigureAwait(false);
|
||||
|
||||
if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Completed)
|
||||
{
|
||||
return metadata.ReadOutputAs<TResult>();
|
||||
}
|
||||
|
||||
if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Failed)
|
||||
{
|
||||
if (metadata.FailureDetails is not null)
|
||||
{
|
||||
// Use TaskFailedException to preserve full failure details including stack trace and inner exceptions
|
||||
throw new TaskFailedException(
|
||||
taskName: this.WorkflowName,
|
||||
taskId: 0,
|
||||
failureDetails: metadata.FailureDetails);
|
||||
}
|
||||
|
||||
throw new InvalidOperationException(
|
||||
$"Workflow '{this.WorkflowName}' (RunId: {this.RunId}) failed without failure details.");
|
||||
}
|
||||
|
||||
throw new InvalidOperationException(
|
||||
$"Workflow '{this.WorkflowName}' (RunId: {this.RunId}) ended with unexpected status: {metadata.RuntimeStatus}");
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Waits for the workflow to complete and returns the string result.
|
||||
/// </summary>
|
||||
/// <param name="cancellationToken">A cancellation token to observe.</param>
|
||||
/// <returns>The string result of the workflow execution.</returns>
|
||||
public ValueTask<string?> WaitForCompletionAsync(CancellationToken cancellationToken = default)
|
||||
=> this.WaitForCompletionAsync<string>(cancellationToken);
|
||||
|
||||
/// <summary>
|
||||
/// Gets all events that have been collected from the workflow.
|
||||
/// </summary>
|
||||
public IEnumerable<WorkflowEvent> OutgoingEvents => this._eventSink;
|
||||
|
||||
/// <summary>
|
||||
/// Gets the number of events collected since the last access to <see cref="NewEvents"/>.
|
||||
/// </summary>
|
||||
public int NewEventCount => this._eventSink.Count - this._lastBookmark;
|
||||
|
||||
/// <summary>
|
||||
/// Gets all events collected since the last access to <see cref="NewEvents"/>.
|
||||
/// </summary>
|
||||
public IEnumerable<WorkflowEvent> NewEvents
|
||||
{
|
||||
get
|
||||
{
|
||||
if (this._lastBookmark >= this._eventSink.Count)
|
||||
{
|
||||
return [];
|
||||
}
|
||||
|
||||
int currentBookmark = this._lastBookmark;
|
||||
this._lastBookmark = this._eventSink.Count;
|
||||
|
||||
return this._eventSink.Skip(currentBookmark);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,440 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
// ConfigureAwait Usage in Orchestration Code:
|
||||
// This file uses ConfigureAwait(true) because it runs within orchestration context.
|
||||
// Durable Task orchestrations require deterministic replay - the same code must execute
|
||||
// identically across replays. ConfigureAwait(true) ensures continuations run on the
|
||||
// orchestration's synchronization context, which is essential for replay correctness.
|
||||
// Using ConfigureAwait(false) here could cause non-deterministic behavior during replay.
|
||||
|
||||
// Superstep execution walkthrough for a workflow like below:
|
||||
//
|
||||
// [A] ──► [B] ──► [C] ──► [E] (B→D has condition: x => x.NeedsReview)
|
||||
// │ ▲
|
||||
// └──► [D] ──────┘
|
||||
//
|
||||
// Superstep 1 — A runs
|
||||
// Queues before: A:[input] Results: {}
|
||||
// Dispatch: A executes, returns resultA
|
||||
// Route: EdgeMap routes A's output → B's queue
|
||||
// Queues after: B:[resultA] Results: {A: resultA}
|
||||
//
|
||||
// Superstep 2 — B runs
|
||||
// Queues before: B:[resultA] Results: {A: resultA}
|
||||
// Dispatch: B executes, returns resultB (type: Order)
|
||||
// Route: FanOutRouter sends resultB to:
|
||||
// C's queue (unconditional)
|
||||
// D's queue (only if resultB.NeedsReview == true)
|
||||
// Queues after: C:[resultB], D:[resultB] Results: {A: .., B: resultB}
|
||||
// (D may be empty if condition was false)
|
||||
//
|
||||
// Superstep 3 — C and D run in parallel
|
||||
// Queues before: C:[resultB], D:[resultB]
|
||||
// Dispatch: C and D execute concurrently via Task.WhenAll
|
||||
// Route: Both route output → E's queue
|
||||
// Queues after: E:[resultC, resultD] Results: {.., C: resultC, D: resultD}
|
||||
//
|
||||
// Superstep 4 — E runs (fan-in)
|
||||
// Queues before: E:[resultC, resultD] ◄── IsFanInExecutor("E") = true
|
||||
// Collect: AggregateQueueMessages merges into JSON array ["resultC","resultD"]
|
||||
// Dispatch: E executes with aggregated input
|
||||
// Route: E has no successors → nothing enqueued
|
||||
// Queues after: (all empty) Results: {.., E: resultE}
|
||||
//
|
||||
// Superstep 5 — loop exits (no pending messages)
|
||||
// GetFinalResult returns resultE
|
||||
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
using System.Text.Json;
|
||||
using Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
using Microsoft.DurableTask;
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
// Superstep loop:
|
||||
//
|
||||
// ┌───────────────┐ ┌───────────────┐ ┌───────────────────┐
|
||||
// │ Collect │───►│ Dispatch │───►│ Process Results │
|
||||
// │ Executor │ │ Executors │ │ & Route Messages │
|
||||
// │ Inputs │ │ in Parallel │ │ │
|
||||
// └───────────────┘ └───────────────┘ └───────────────────┘
|
||||
// ▲ │
|
||||
// └───────────────────────────────────────────┘
|
||||
// (repeat until no pending messages)
|
||||
|
||||
/// <summary>
|
||||
/// Runs workflow orchestrations using message-driven superstep execution with Durable Task.
|
||||
/// </summary>
|
||||
internal sealed class DurableWorkflowRunner
|
||||
{
|
||||
private const int MaxSupersteps = 100;
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of the <see cref="DurableWorkflowRunner"/> class.
|
||||
/// </summary>
|
||||
/// <param name="durableOptions">The durable options containing workflow configurations.</param>
|
||||
internal DurableWorkflowRunner(DurableOptions durableOptions)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(durableOptions);
|
||||
|
||||
this.Options = durableOptions.Workflows;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Gets the workflow options.
|
||||
/// </summary>
|
||||
private DurableWorkflowOptions Options { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Runs a workflow orchestration.
|
||||
/// </summary>
|
||||
/// <param name="context">The task orchestration context.</param>
|
||||
/// <param name="workflowInput">The workflow input envelope containing workflow input and metadata.</param>
|
||||
/// <param name="logger">The replay-safe logger for orchestration logging.</param>
|
||||
/// <returns>The result of the workflow execution.</returns>
|
||||
/// <exception cref="InvalidOperationException">Thrown when the specified workflow is not found.</exception>
|
||||
internal async Task<string> RunWorkflowOrchestrationAsync(
|
||||
TaskOrchestrationContext context,
|
||||
DurableWorkflowInput<object> workflowInput,
|
||||
ILogger logger)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(context);
|
||||
ArgumentNullException.ThrowIfNull(workflowInput);
|
||||
|
||||
Workflow workflow = this.GetWorkflowOrThrow(context.Name);
|
||||
|
||||
string workflowName = context.Name;
|
||||
string instanceId = context.InstanceId;
|
||||
logger.LogWorkflowStarting(workflowName, instanceId);
|
||||
|
||||
WorkflowGraphInfo graphInfo = WorkflowAnalyzer.BuildGraphInfo(workflow);
|
||||
DurableEdgeMap edgeMap = new(graphInfo);
|
||||
|
||||
// Extract input - the start executor determines the expected input type from its own InputTypes
|
||||
object input = workflowInput.Input;
|
||||
|
||||
return await RunSuperstepLoopAsync(context, workflow, edgeMap, input, logger).ConfigureAwait(true);
|
||||
}
|
||||
|
||||
private Workflow GetWorkflowOrThrow(string orchestrationName)
|
||||
{
|
||||
string workflowName = WorkflowNamingHelper.ToWorkflowName(orchestrationName);
|
||||
|
||||
if (!this.Options.Workflows.TryGetValue(workflowName, out Workflow? workflow))
|
||||
{
|
||||
throw new InvalidOperationException($"Workflow '{workflowName}' not found.");
|
||||
}
|
||||
|
||||
return workflow;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Runs the workflow execution loop using superstep-based processing.
|
||||
/// </summary>
|
||||
[UnconditionalSuppressMessage("AOT", "IL2026:RequiresUnreferencedCode", Justification = "Input types are preserved by the Durable Task framework's DataConverter.")]
|
||||
[UnconditionalSuppressMessage("AOT", "IL3050:RequiresDynamicCode", Justification = "Input types are preserved by the Durable Task framework's DataConverter.")]
|
||||
private static async Task<string> RunSuperstepLoopAsync(
|
||||
TaskOrchestrationContext context,
|
||||
Workflow workflow,
|
||||
DurableEdgeMap edgeMap,
|
||||
object initialInput,
|
||||
ILogger logger)
|
||||
{
|
||||
SuperstepState state = new(workflow, edgeMap);
|
||||
|
||||
// Convert input to string for the message queue - serialize if not already a string
|
||||
string inputString = initialInput is string s ? s : JsonSerializer.Serialize(initialInput);
|
||||
|
||||
edgeMap.EnqueueInitialInput(inputString, state.MessageQueues);
|
||||
|
||||
for (int superstep = 1; superstep <= MaxSupersteps; superstep++)
|
||||
{
|
||||
List<ExecutorInput> executorInputs = CollectExecutorInputs(state, logger);
|
||||
if (executorInputs.Count == 0)
|
||||
{
|
||||
break;
|
||||
}
|
||||
|
||||
logger.LogSuperstepStarting(superstep, executorInputs.Count);
|
||||
if (logger.IsEnabled(LogLevel.Debug))
|
||||
{
|
||||
logger.LogSuperstepExecutors(superstep, string.Join(", ", executorInputs.Select(e => e.ExecutorId)));
|
||||
}
|
||||
|
||||
string[] results = await DispatchExecutorsInParallelAsync(context, executorInputs, logger).ConfigureAwait(true);
|
||||
|
||||
ProcessSuperstepResults(executorInputs, results, state, logger);
|
||||
|
||||
// Check if we've reached the limit and still have work remaining
|
||||
if (superstep == MaxSupersteps)
|
||||
{
|
||||
int remainingExecutors = CountRemainingExecutors(state.MessageQueues);
|
||||
if (remainingExecutors > 0)
|
||||
{
|
||||
logger.LogWorkflowMaxSuperstepsExceeded(context.InstanceId, MaxSupersteps, remainingExecutors);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
string finalResult = GetFinalResult(state.LastResults);
|
||||
logger.LogWorkflowCompleted();
|
||||
|
||||
return finalResult;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Counts the number of executors with pending messages in their queues.
|
||||
/// </summary>
|
||||
private static int CountRemainingExecutors(Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues)
|
||||
{
|
||||
return messageQueues.Count(kvp => kvp.Value.Count > 0);
|
||||
}
|
||||
|
||||
private static async Task<string[]> DispatchExecutorsInParallelAsync(
|
||||
TaskOrchestrationContext context,
|
||||
List<ExecutorInput> executorInputs,
|
||||
ILogger logger)
|
||||
{
|
||||
Task<string>[] dispatchTasks = executorInputs
|
||||
.Select(input => DurableExecutorDispatcher.DispatchAsync(context, input.Info, input.Envelope, logger))
|
||||
.ToArray();
|
||||
|
||||
return await Task.WhenAll(dispatchTasks).ConfigureAwait(true);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Holds state that accumulates and changes across superstep iterations during workflow execution.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <c>MessageQueues</c> starts with one entry (the start executor's queue, seeded by
|
||||
/// <see cref="DurableEdgeMap.EnqueueInitialInput"/>). After each superstep, <c>RouteOutputToSuccessors</c>
|
||||
/// adds entries for successor executors that receive routed messages. Queues are drained during
|
||||
/// <c>CollectExecutorInputs</c>; empty queues are skipped.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <c>LastResults</c> is updated after every superstep with the result of each executor that ran.
|
||||
/// At workflow completion, the last non-empty value is returned as the workflow's final result.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
private sealed class SuperstepState
|
||||
{
|
||||
public SuperstepState(Workflow workflow, DurableEdgeMap edgeMap)
|
||||
{
|
||||
this.EdgeMap = edgeMap;
|
||||
this.ExecutorBindings = workflow.ReflectExecutors();
|
||||
}
|
||||
|
||||
public DurableEdgeMap EdgeMap { get; }
|
||||
|
||||
public Dictionary<string, ExecutorBinding> ExecutorBindings { get; }
|
||||
|
||||
public Dictionary<string, Queue<DurableMessageEnvelope>> MessageQueues { get; } = [];
|
||||
|
||||
public Dictionary<string, string> LastResults { get; } = [];
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Represents prepared input for an executor ready for dispatch.
|
||||
/// </summary>
|
||||
private sealed record ExecutorInput(string ExecutorId, DurableMessageEnvelope Envelope, WorkflowExecutorInfo Info);
|
||||
|
||||
/// <summary>
|
||||
/// Collects inputs for all active executors, applying Fan-In aggregation where needed.
|
||||
/// </summary>
|
||||
private static List<ExecutorInput> CollectExecutorInputs(
|
||||
SuperstepState state,
|
||||
ILogger logger)
|
||||
{
|
||||
List<ExecutorInput> inputs = [];
|
||||
|
||||
// Only process queues that have pending messages
|
||||
foreach ((string executorId, Queue<DurableMessageEnvelope> queue) in state.MessageQueues
|
||||
.Where(kvp => kvp.Value.Count > 0))
|
||||
{
|
||||
DurableMessageEnvelope envelope = GetNextEnvelope(executorId, queue, state.EdgeMap, logger);
|
||||
WorkflowExecutorInfo executorInfo = CreateExecutorInfo(executorId, state.ExecutorBindings);
|
||||
|
||||
inputs.Add(new ExecutorInput(executorId, envelope, executorInfo));
|
||||
}
|
||||
|
||||
return inputs;
|
||||
}
|
||||
|
||||
private static DurableMessageEnvelope GetNextEnvelope(
|
||||
string executorId,
|
||||
Queue<DurableMessageEnvelope> queue,
|
||||
DurableEdgeMap edgeMap,
|
||||
ILogger logger)
|
||||
{
|
||||
bool shouldAggregate = edgeMap.IsFanInExecutor(executorId) && queue.Count > 1;
|
||||
|
||||
return shouldAggregate
|
||||
? AggregateQueueMessages(queue, executorId, logger)
|
||||
: queue.Dequeue();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Aggregates all messages in a queue into a JSON array for Fan-In executors.
|
||||
/// </summary>
|
||||
private static DurableMessageEnvelope AggregateQueueMessages(
|
||||
Queue<DurableMessageEnvelope> queue,
|
||||
string executorId,
|
||||
ILogger logger)
|
||||
{
|
||||
List<string> messages = [];
|
||||
List<string> sourceIds = [];
|
||||
|
||||
while (queue.Count > 0)
|
||||
{
|
||||
DurableMessageEnvelope envelope = queue.Dequeue();
|
||||
messages.Add(envelope.Message);
|
||||
|
||||
if (envelope.SourceExecutorId is not null)
|
||||
{
|
||||
sourceIds.Add(envelope.SourceExecutorId);
|
||||
}
|
||||
}
|
||||
|
||||
if (logger.IsEnabled(LogLevel.Debug))
|
||||
{
|
||||
logger.LogFanInAggregated(executorId, messages.Count, string.Join(", ", sourceIds));
|
||||
}
|
||||
|
||||
return new DurableMessageEnvelope
|
||||
{
|
||||
Message = SerializeToJsonArray(messages),
|
||||
InputTypeName = typeof(string[]).FullName,
|
||||
SourceExecutorId = sourceIds.Count > 0 ? string.Join(",", sourceIds) : null
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Processes results from a superstep, updating state and routing messages to successors.
|
||||
/// </summary>
|
||||
private static void ProcessSuperstepResults(
|
||||
List<ExecutorInput> inputs,
|
||||
string[] rawResults,
|
||||
SuperstepState state,
|
||||
ILogger logger)
|
||||
{
|
||||
for (int i = 0; i < inputs.Count; i++)
|
||||
{
|
||||
string executorId = inputs[i].ExecutorId;
|
||||
(string result, List<SentMessageInfo> sentMessages) = ParseActivityResult(rawResults[i]);
|
||||
|
||||
logger.LogExecutorResultReceived(executorId, result.Length, sentMessages.Count);
|
||||
|
||||
state.LastResults[executorId] = result;
|
||||
RouteOutputToSuccessors(executorId, result, sentMessages, state, logger);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Routes executor output (explicit messages or return value) to successor executors.
|
||||
/// </summary>
|
||||
private static void RouteOutputToSuccessors(
|
||||
string executorId,
|
||||
string result,
|
||||
List<SentMessageInfo> sentMessages,
|
||||
SuperstepState state,
|
||||
ILogger logger)
|
||||
{
|
||||
if (sentMessages.Count > 0)
|
||||
{
|
||||
// Only route messages that have content
|
||||
foreach (SentMessageInfo message in sentMessages.Where(m => !string.IsNullOrEmpty(m.Message)))
|
||||
{
|
||||
state.EdgeMap.RouteMessage(executorId, message.Message!, message.TypeName, state.MessageQueues, logger);
|
||||
}
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
if (!string.IsNullOrEmpty(result))
|
||||
{
|
||||
state.EdgeMap.RouteMessage(executorId, result, inputTypeName: null, state.MessageQueues, logger);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Serializes a list of messages into a JSON array.
|
||||
/// </summary>
|
||||
[UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Serializing string array.")]
|
||||
[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Serializing string array.")]
|
||||
private static string SerializeToJsonArray(List<string> messages)
|
||||
{
|
||||
return JsonSerializer.Serialize(messages);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a <see cref="WorkflowExecutorInfo"/> for the given executor ID.
|
||||
/// </summary>
|
||||
/// <exception cref="InvalidOperationException">Thrown when the executor ID is not found in bindings.</exception>
|
||||
private static WorkflowExecutorInfo CreateExecutorInfo(
|
||||
string executorId,
|
||||
Dictionary<string, ExecutorBinding> executorBindings)
|
||||
{
|
||||
if (!executorBindings.TryGetValue(executorId, out ExecutorBinding? binding))
|
||||
{
|
||||
throw new InvalidOperationException($"Executor '{executorId}' not found in workflow bindings.");
|
||||
}
|
||||
|
||||
bool isAgentic = WorkflowAnalyzer.IsAgentExecutorType(binding.ExecutorType);
|
||||
RequestPort? requestPort = (binding is RequestPortBinding rpb) ? rpb.Port : null;
|
||||
Workflow? subWorkflow = (binding is SubworkflowBinding swb) ? swb.WorkflowInstance : null;
|
||||
|
||||
return new WorkflowExecutorInfo(executorId, isAgentic, requestPort, subWorkflow);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Returns the last non-empty result from executed steps, or empty string if none.
|
||||
/// </summary>
|
||||
private static string GetFinalResult(Dictionary<string, string> lastResults)
|
||||
{
|
||||
return lastResults.Values.LastOrDefault(value => !string.IsNullOrEmpty(value)) ?? string.Empty;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Parses the raw activity result to extract the result string and any sent messages.
|
||||
/// </summary>
|
||||
private static (string Result, List<SentMessageInfo> SentMessages) ParseActivityResult(string rawResult)
|
||||
{
|
||||
if (string.IsNullOrEmpty(rawResult))
|
||||
{
|
||||
return (rawResult, []);
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
DurableActivityOutput? output = JsonSerializer.Deserialize(
|
||||
rawResult,
|
||||
DurableWorkflowJsonContext.Default.DurableActivityOutput);
|
||||
|
||||
if (output is null || !HasMeaningfulContent(output))
|
||||
{
|
||||
return (rawResult, []);
|
||||
}
|
||||
|
||||
return (output.Result ?? string.Empty, output.SentMessages);
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
return (rawResult, []);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Determines whether the activity output contains meaningful content.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Distinguishes actual activity output from arbitrary JSON that deserialized
|
||||
/// successfully but with all default/empty values.
|
||||
/// </remarks>
|
||||
private static bool HasMeaningfulContent(DurableActivityOutput output)
|
||||
{
|
||||
return output.Result is not null || output.SentMessages.Count > 0;
|
||||
}
|
||||
}
|
||||
+156
@@ -0,0 +1,156 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
// Routing decision flow for a single edge.
|
||||
// Example: the B→D edge from a workflow like below:
|
||||
//
|
||||
// [A] ──► [B] ──► [C] ──► [E] (B→D has condition: x => x.NeedsReview)
|
||||
// │ ▲
|
||||
// └──► [D] ──────┘
|
||||
//
|
||||
// (condition: x => x.NeedsReview, _sourceOutputType: typeof(Order))
|
||||
//
|
||||
// RouteMessage(envelope) envelope.Message = "{\"NeedsReview\":true, ...}"
|
||||
// │
|
||||
// ▼
|
||||
// Has condition? ──── No ────► Enqueue to sink's queue
|
||||
// │
|
||||
// Yes (B→D has one)
|
||||
// │
|
||||
// ▼
|
||||
// Deserialize message JSON string → Order object using _sourceOutputType
|
||||
// │
|
||||
// ▼
|
||||
// Evaluate _condition(order) order => order.NeedsReview
|
||||
// │
|
||||
// ┌──┴──┐
|
||||
// true false
|
||||
// │ │
|
||||
// ▼ └──► Skip (log and return, D will not run)
|
||||
// Enqueue to
|
||||
// D's queue
|
||||
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
using System.Text.Json;
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
|
||||
|
||||
/// <summary>
|
||||
/// Routes messages from a source executor to a single target executor with optional condition evaluation.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Created by <see cref="DurableEdgeMap"/> during construction — one instance per (source, sink) edge.
|
||||
/// When an edge has a condition (e.g., <c>order => order.Total > 1000</c>), the router deserialises
|
||||
/// the serialised JSON message back to the source executor's output type so the condition delegate
|
||||
/// can evaluate it against strongly-typed properties. If the condition returns <c>false</c>, the
|
||||
/// message is not forwarded and the target executor will not run for this edge.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// For sources with multiple successors, individual <see cref="DurableDirectEdgeRouter"/> instances
|
||||
/// are wrapped in a <see cref="DurableFanOutEdgeRouter"/> so a single <c>RouteMessage</c> call
|
||||
/// fans the same message out to all targets, each evaluating its own condition independently.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
internal sealed class DurableDirectEdgeRouter : IDurableEdgeRouter
|
||||
{
|
||||
private readonly string _sourceId;
|
||||
private readonly string _sinkId;
|
||||
private readonly Func<object?, bool>? _condition;
|
||||
private readonly Type? _sourceOutputType;
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of <see cref="DurableDirectEdgeRouter"/>.
|
||||
/// </summary>
|
||||
/// <param name="sourceId">The source executor ID.</param>
|
||||
/// <param name="sinkId">The target executor ID.</param>
|
||||
/// <param name="condition">Optional condition function to evaluate before routing.</param>
|
||||
/// <param name="sourceOutputType">The output type of the source executor for deserialization.</param>
|
||||
internal DurableDirectEdgeRouter(
|
||||
string sourceId,
|
||||
string sinkId,
|
||||
Func<object?, bool>? condition,
|
||||
Type? sourceOutputType)
|
||||
{
|
||||
this._sourceId = sourceId;
|
||||
this._sinkId = sinkId;
|
||||
this._condition = condition;
|
||||
this._sourceOutputType = sourceOutputType;
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
public void RouteMessage(
|
||||
DurableMessageEnvelope envelope,
|
||||
Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues,
|
||||
ILogger logger)
|
||||
{
|
||||
if (this._condition is not null)
|
||||
{
|
||||
try
|
||||
{
|
||||
object? messageObj = DeserializeForCondition(envelope.Message, this._sourceOutputType);
|
||||
if (!this._condition(messageObj))
|
||||
{
|
||||
logger.LogEdgeConditionFalse(this._sourceId, this._sinkId);
|
||||
return;
|
||||
}
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
logger.LogEdgeConditionEvaluationFailed(ex, this._sourceId, this._sinkId);
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
logger.LogEdgeRoutingMessage(this._sourceId, this._sinkId);
|
||||
EnqueueMessage(messageQueues, this._sinkId, envelope);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Deserializes a JSON message to an object for condition evaluation.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Messages travel through the durable workflow as serialized JSON strings, but condition
|
||||
/// delegates need typed objects to evaluate (e.g., order => order.Status == "Approved").
|
||||
/// This method converts the JSON back to an object the condition delegate can evaluate.
|
||||
/// </remarks>
|
||||
/// <param name="json">The JSON string representation of the message.</param>
|
||||
/// <param name="targetType">
|
||||
/// The expected type of the message. When provided, enables strongly-typed deserialization
|
||||
/// so the condition function receives the correct type to evaluate against.
|
||||
/// </param>
|
||||
/// <returns>
|
||||
/// The deserialized object, or null if the JSON is empty.
|
||||
/// </returns>
|
||||
/// <exception cref="JsonException">Thrown when the JSON is invalid or cannot be deserialized to the target type.</exception>
|
||||
[UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing workflow types registered at startup.")]
|
||||
[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing workflow types registered at startup.")]
|
||||
private static object? DeserializeForCondition(string json, Type? targetType)
|
||||
{
|
||||
if (string.IsNullOrEmpty(json))
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
// If we know the source executor's output type, deserialize to that specific type
|
||||
// so the condition function can access strongly-typed properties.
|
||||
// Otherwise, deserialize as a generic object for basic inspection.
|
||||
return targetType is null
|
||||
? JsonSerializer.Deserialize<object>(json)
|
||||
: JsonSerializer.Deserialize(json, targetType);
|
||||
}
|
||||
|
||||
private static void EnqueueMessage(
|
||||
Dictionary<string, Queue<DurableMessageEnvelope>> queues,
|
||||
string executorId,
|
||||
DurableMessageEnvelope envelope)
|
||||
{
|
||||
if (!queues.TryGetValue(executorId, out Queue<DurableMessageEnvelope>? queue))
|
||||
{
|
||||
queue = new Queue<DurableMessageEnvelope>();
|
||||
queues[executorId] = queue;
|
||||
}
|
||||
|
||||
queue.Enqueue(envelope);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,205 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
// How WorkflowGraphInfo maps to DurableEdgeMap at runtime.
|
||||
// For a workflow like below:
|
||||
//
|
||||
// [A] ──► [B] ──► [C] ──► [E]
|
||||
// │ ▲
|
||||
// └──► [D] ──────┘
|
||||
// (condition: x => x.NeedsReview)
|
||||
//
|
||||
// WorkflowGraphInfo DurableEdgeMap
|
||||
// ┌──────────────────────────┐ ┌──────────────────────────────────────┐
|
||||
// │ Successors: │ │ _routersBySource: │
|
||||
// │ A → [B] │──constructs──►│ A → [DirectRouter(A→B)] │
|
||||
// │ B → [C, D] │ │ B → [FanOutRouter([C, D])] │
|
||||
// │ C → [E] │ │ C → [DirectRouter(C→E)] │
|
||||
// │ D → [E] │ │ D → [DirectRouter(D→E)] │
|
||||
// └──────────────────────────┘ │ │
|
||||
// ┌──────────────────────────┐ │ _predecessorCounts: │
|
||||
// │ Predecessors: │ │ A → 0 │
|
||||
// │ E → [C, D] (fan-in!) │──constructs──►│ B → 1, C → 1, D → 1 │
|
||||
// └──────────────────────────┘ │ E → 2 ◄── IsFanInExecutor = true │
|
||||
// └──────────────────────────────────────┘
|
||||
//
|
||||
// Usage during superstep execution (continuing the example):
|
||||
//
|
||||
// 1. EnqueueInitialInput(msg) ──► MessageQueues["A"].Enqueue(envelope)
|
||||
//
|
||||
// 2. After B completes, RouteMessage("B", resultB) ──► _routersBySource["B"]
|
||||
// │
|
||||
// ▼
|
||||
// FanOutRouter (B has 2 successors)
|
||||
// ├─► DirectRouter(B→C) ──► no condition ──► enqueue to C
|
||||
// └─► DirectRouter(B→D) ──► evaluate x => x.NeedsReview ──► enqueue to D (or skip)
|
||||
//
|
||||
// 3. Before superstep 4, IsFanInExecutor("E") returns true (count=2)
|
||||
// → CollectExecutorInputs aggregates C and D results into ["resultC","resultD"]
|
||||
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
|
||||
|
||||
/// <summary>
|
||||
/// Manages message routing through workflow edges for durable orchestrations.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This is the durable equivalent of <c>EdgeMap</c> in the in-process runner.
|
||||
/// It is constructed from <see cref="WorkflowGraphInfo"/> (produced by <see cref="WorkflowAnalyzer.BuildGraphInfo"/>)
|
||||
/// and converts the static graph structure into an active routing layer used during superstep execution.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>What it stores:</b>
|
||||
/// </para>
|
||||
/// <list type="bullet">
|
||||
/// <item><description><c>_routersBySource</c> — For each source executor, a list of <see cref="IDurableEdgeRouter"/> instances
|
||||
/// that know how to deliver messages to successor executors. When a source has multiple successors, a single
|
||||
/// <see cref="DurableFanOutEdgeRouter"/> wraps the individual <see cref="DurableDirectEdgeRouter"/> instances.</description></item>
|
||||
/// <item><description><c>_predecessorCounts</c> — The number of predecessors for each executor, used to detect
|
||||
/// fan-in points where multiple incoming messages should be aggregated before execution.</description></item>
|
||||
/// <item><description><c>_startExecutorId</c> — The entry-point executor that receives the initial workflow input.</description></item>
|
||||
/// </list>
|
||||
/// <para>
|
||||
/// <b>How it is used during execution:</b>
|
||||
/// </para>
|
||||
/// <list type="number">
|
||||
/// <item><description><see cref="EnqueueInitialInput"/> seeds the start executor's queue before the first superstep.</description></item>
|
||||
/// <item><description>After each superstep, <c>DurableWorkflowRunner.RouteOutputToSuccessors</c> calls
|
||||
/// <see cref="RouteMessage"/> which looks up the routers for the completed executor and forwards the
|
||||
/// result to successor queues. Each router may evaluate an edge condition before enqueueing.</description></item>
|
||||
/// <item><description><see cref="IsFanInExecutor"/> is checked during input collection to decide whether
|
||||
/// to aggregate multiple queued messages into a single JSON array before dispatching.</description></item>
|
||||
/// </list>
|
||||
/// </remarks>
|
||||
internal sealed class DurableEdgeMap
|
||||
{
|
||||
private readonly Dictionary<string, List<IDurableEdgeRouter>> _routersBySource = [];
|
||||
private readonly Dictionary<string, int> _predecessorCounts = [];
|
||||
private readonly string _startExecutorId;
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of <see cref="DurableEdgeMap"/> from workflow graph info.
|
||||
/// </summary>
|
||||
/// <param name="graphInfo">The workflow graph information containing routing structure.</param>
|
||||
internal DurableEdgeMap(WorkflowGraphInfo graphInfo)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(graphInfo);
|
||||
|
||||
this._startExecutorId = graphInfo.StartExecutorId;
|
||||
|
||||
// Build edge routers for each source executor
|
||||
foreach (KeyValuePair<string, List<string>> entry in graphInfo.Successors)
|
||||
{
|
||||
string sourceId = entry.Key;
|
||||
List<string> successorIds = entry.Value;
|
||||
|
||||
if (successorIds.Count == 0)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
graphInfo.ExecutorOutputTypes.TryGetValue(sourceId, out Type? sourceOutputType);
|
||||
|
||||
List<IDurableEdgeRouter> routers = [];
|
||||
foreach (string sinkId in successorIds)
|
||||
{
|
||||
graphInfo.EdgeConditions.TryGetValue((sourceId, sinkId), out Func<object?, bool>? condition);
|
||||
|
||||
routers.Add(new DurableDirectEdgeRouter(sourceId, sinkId, condition, sourceOutputType));
|
||||
}
|
||||
|
||||
// If multiple successors, wrap in a fan-out router
|
||||
if (routers.Count > 1)
|
||||
{
|
||||
this._routersBySource[sourceId] = [new DurableFanOutEdgeRouter(sourceId, routers)];
|
||||
}
|
||||
else
|
||||
{
|
||||
this._routersBySource[sourceId] = routers;
|
||||
}
|
||||
}
|
||||
|
||||
// Store predecessor counts for fan-in detection
|
||||
foreach (KeyValuePair<string, List<string>> entry in graphInfo.Predecessors)
|
||||
{
|
||||
this._predecessorCounts[entry.Key] = entry.Value.Count;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Routes a message from a source executor to its successors.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Called by <c>DurableWorkflowRunner.RouteOutputToSuccessors</c> after each superstep.
|
||||
/// Wraps the message in a <see cref="DurableMessageEnvelope"/> and delegates to the
|
||||
/// appropriate <see cref="IDurableEdgeRouter"/>(s) for the source executor. Each router
|
||||
/// may evaluate an edge condition and, if satisfied, enqueue the envelope into the
|
||||
/// target executor's message queue for the next superstep.
|
||||
/// </remarks>
|
||||
/// <param name="sourceId">The source executor ID.</param>
|
||||
/// <param name="message">The serialized message to route.</param>
|
||||
/// <param name="inputTypeName">The type name of the message.</param>
|
||||
/// <param name="messageQueues">The message queues to enqueue messages into.</param>
|
||||
/// <param name="logger">The logger for tracing.</param>
|
||||
internal void RouteMessage(
|
||||
string sourceId,
|
||||
string message,
|
||||
string? inputTypeName,
|
||||
Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues,
|
||||
ILogger logger)
|
||||
{
|
||||
if (!this._routersBySource.TryGetValue(sourceId, out List<IDurableEdgeRouter>? routers))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
DurableMessageEnvelope envelope = DurableMessageEnvelope.Create(message, inputTypeName, sourceId);
|
||||
|
||||
foreach (IDurableEdgeRouter router in routers)
|
||||
{
|
||||
router.RouteMessage(envelope, messageQueues, logger);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Enqueues the initial workflow input to the start executor.
|
||||
/// </summary>
|
||||
/// <param name="message">The serialized initial input message.</param>
|
||||
/// <param name="messageQueues">The message queues to enqueue into.</param>
|
||||
/// <remarks>
|
||||
/// This method is used only at workflow startup to provide input to the first executor.
|
||||
/// No input type hint is required because the start executor determines its expected input type from its own <c>InputTypes</c> configuration.
|
||||
/// </remarks>
|
||||
internal void EnqueueInitialInput(
|
||||
string message,
|
||||
Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues)
|
||||
{
|
||||
DurableMessageEnvelope envelope = DurableMessageEnvelope.Create(message, inputTypeName: null);
|
||||
EnqueueMessage(messageQueues, this._startExecutorId, envelope);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Determines if an executor is a fan-in point (has multiple predecessors).
|
||||
/// </summary>
|
||||
/// <param name="executorId">The executor ID to check.</param>
|
||||
/// <returns><c>true</c> if the executor has multiple predecessors; otherwise, <c>false</c>.</returns>
|
||||
internal bool IsFanInExecutor(string executorId)
|
||||
{
|
||||
return this._predecessorCounts.TryGetValue(executorId, out int count) && count > 1;
|
||||
}
|
||||
|
||||
private static void EnqueueMessage(
|
||||
Dictionary<string, Queue<DurableMessageEnvelope>> queues,
|
||||
string executorId,
|
||||
DurableMessageEnvelope envelope)
|
||||
{
|
||||
if (!queues.TryGetValue(executorId, out Queue<DurableMessageEnvelope>? queue))
|
||||
{
|
||||
queue = new Queue<DurableMessageEnvelope>();
|
||||
queues[executorId] = queue;
|
||||
}
|
||||
|
||||
queue.Enqueue(envelope);
|
||||
}
|
||||
}
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
// Fan-out routing: one source message is forwarded to multiple targets.
|
||||
// Example from a workflow like below:
|
||||
//
|
||||
// [A] ──► [B] ──► [C] ──► [E] (B→D has condition: x => x.NeedsReview)
|
||||
// │ ▲
|
||||
// └──► [D] ──────┘
|
||||
//
|
||||
// B has two successors (C and D), so DurableEdgeMap wraps them:
|
||||
//
|
||||
// Executor B completes with resultB (type: Order)
|
||||
// │
|
||||
// ▼
|
||||
// FanOutRouter(B)
|
||||
// ├──► DirectRouter(B→C) ──► no condition ──► enqueue to C
|
||||
// └──► DirectRouter(B→D) ──► x => x.NeedsReview ──► enqueue to D (or skip)
|
||||
//
|
||||
// Each DirectRouter independently evaluates its condition,
|
||||
// so resultB always reaches C, but only reaches D if NeedsReview is true.
|
||||
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
|
||||
|
||||
/// <summary>
|
||||
/// Routes messages from a source executor to multiple target executors (fan-out pattern).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Created by <see cref="DurableEdgeMap"/> when a source executor has more than one successor.
|
||||
/// Wraps the individual <see cref="DurableDirectEdgeRouter"/> instances and delegates
|
||||
/// <see cref="RouteMessage"/> to each of them, so the same message is evaluated and
|
||||
/// potentially enqueued for every target independently.
|
||||
/// </remarks>
|
||||
internal sealed class DurableFanOutEdgeRouter : IDurableEdgeRouter
|
||||
{
|
||||
private readonly string _sourceId;
|
||||
private readonly List<IDurableEdgeRouter> _targetRouters;
|
||||
|
||||
/// <summary>
|
||||
/// Initializes a new instance of <see cref="DurableFanOutEdgeRouter"/>.
|
||||
/// </summary>
|
||||
/// <param name="sourceId">The source executor ID.</param>
|
||||
/// <param name="targetRouters">The routers for each target executor.</param>
|
||||
internal DurableFanOutEdgeRouter(string sourceId, List<IDurableEdgeRouter> targetRouters)
|
||||
{
|
||||
this._sourceId = sourceId;
|
||||
this._targetRouters = targetRouters;
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
public void RouteMessage(
|
||||
DurableMessageEnvelope envelope,
|
||||
Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues,
|
||||
ILogger logger)
|
||||
{
|
||||
if (logger.IsEnabled(LogLevel.Debug))
|
||||
{
|
||||
logger.LogDebug("Fan-Out from {Source}: routing to {Count} targets", this._sourceId, this._targetRouters.Count);
|
||||
}
|
||||
|
||||
foreach (IDurableEdgeRouter targetRouter in this._targetRouters)
|
||||
{
|
||||
targetRouter.RouteMessage(envelope, messageQueues, logger);
|
||||
}
|
||||
}
|
||||
}
|
||||
+26
@@ -0,0 +1,26 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
|
||||
|
||||
/// <summary>
|
||||
/// Defines the contract for routing messages through workflow edges in durable orchestrations.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Implementations include <see cref="DurableDirectEdgeRouter"/> for single-target routing
|
||||
/// and <see cref="DurableFanOutEdgeRouter"/> for multi-target fan-out patterns.
|
||||
/// </remarks>
|
||||
internal interface IDurableEdgeRouter
|
||||
{
|
||||
/// <summary>
|
||||
/// Routes a message from the source executor to its target(s).
|
||||
/// </summary>
|
||||
/// <param name="envelope">The message envelope containing the message and metadata.</param>
|
||||
/// <param name="messageQueues">The message queues to enqueue messages into.</param>
|
||||
/// <param name="logger">The logger for tracing.</param>
|
||||
void RouteMessage(
|
||||
DurableMessageEnvelope envelope,
|
||||
Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues,
|
||||
ILogger logger);
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Provides a registry for executor bindings used in durable workflow orchestrations.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This registry enables lookup of executors by name, decoupled from specific workflow instances.
|
||||
/// Executors are registered when workflows are added to <see cref="DurableWorkflowOptions"/>.
|
||||
/// </remarks>
|
||||
internal sealed class ExecutorRegistry
|
||||
{
|
||||
private readonly Dictionary<string, ExecutorRegistration> _executors = new(StringComparer.OrdinalIgnoreCase);
|
||||
|
||||
/// <summary>
|
||||
/// Gets the number of registered executors.
|
||||
/// </summary>
|
||||
internal int Count => this._executors.Count;
|
||||
|
||||
/// <summary>
|
||||
/// Attempts to get an executor registration by name.
|
||||
/// </summary>
|
||||
/// <param name="executorName">The executor name to look up.</param>
|
||||
/// <param name="registration">When this method returns, contains the registration if found; otherwise, null.</param>
|
||||
/// <returns><see langword="true"/> if the executor was found; otherwise, <see langword="false"/>.</returns>
|
||||
internal bool TryGetExecutor(string executorName, [NotNullWhen(true)] out ExecutorRegistration? registration)
|
||||
{
|
||||
return this._executors.TryGetValue(executorName, out registration);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Registers an executor binding from a workflow.
|
||||
/// </summary>
|
||||
/// <param name="executorName">The executor name (without GUID suffix).</param>
|
||||
/// <param name="executorId">The full executor ID (may include GUID suffix).</param>
|
||||
/// <param name="workflow">The workflow containing the executor.</param>
|
||||
internal void Register(string executorName, string executorId, Workflow workflow)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(executorName);
|
||||
ArgumentException.ThrowIfNullOrEmpty(executorId);
|
||||
ArgumentNullException.ThrowIfNull(workflow);
|
||||
|
||||
Dictionary<string, ExecutorBinding> bindings = workflow.ReflectExecutors();
|
||||
if (!bindings.TryGetValue(executorId, out ExecutorBinding? binding))
|
||||
{
|
||||
throw new InvalidOperationException($"Executor '{executorId}' not found in workflow.");
|
||||
}
|
||||
|
||||
this._executors.TryAdd(executorName, new ExecutorRegistration(executorId, binding));
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Represents a registered executor with its binding information.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The <paramref name="ExecutorId"/> may differ from the registered name when the executor
|
||||
/// ID includes an instance suffix (e.g., "ExecutorName_Guid").
|
||||
/// </remarks>
|
||||
/// <param name="ExecutorId">The full executor ID (may include instance suffix).</param>
|
||||
/// <param name="Binding">The executor binding containing the factory and configuration.</param>
|
||||
internal sealed record ExecutorRegistration(string ExecutorId, ExecutorBinding Binding)
|
||||
{
|
||||
/// <summary>
|
||||
/// Creates an instance of the executor.
|
||||
/// </summary>
|
||||
/// <param name="runId">A unique identifier for the run context.</param>
|
||||
/// <param name="cancellationToken">The cancellation token.</param>
|
||||
/// <returns>The created executor instance.</returns>
|
||||
internal async ValueTask<Executor> CreateExecutorInstanceAsync(string runId, CancellationToken cancellationToken = default)
|
||||
{
|
||||
if (this.Binding.FactoryAsync is null)
|
||||
{
|
||||
throw new InvalidOperationException($"Cannot create executor '{this.ExecutorId}': Binding is a placeholder.");
|
||||
}
|
||||
|
||||
return await this.Binding.FactoryAsync(runId).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a workflow run that can be awaited for completion.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This interface extends <see cref="IWorkflowRun"/> to provide methods for waiting
|
||||
/// until the workflow execution completes. Not all workflow runners support this capability.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Use pattern matching to check if a workflow run supports awaiting:
|
||||
/// <code>
|
||||
/// IWorkflowRun run = await client.RunAsync(workflow, input);
|
||||
/// if (run is IAwaitableWorkflowRun awaitableRun)
|
||||
/// {
|
||||
/// string? result = await awaitableRun.WaitForCompletionAsync<string>();
|
||||
/// }
|
||||
/// </code>
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public interface IAwaitableWorkflowRun : IWorkflowRun
|
||||
{
|
||||
/// <summary>
|
||||
/// Waits for the workflow to complete and returns the result.
|
||||
/// </summary>
|
||||
/// <typeparam name="TResult">The expected result type.</typeparam>
|
||||
/// <param name="cancellationToken">A cancellation token to observe.</param>
|
||||
/// <returns>The result of the workflow execution.</returns>
|
||||
/// <exception cref="InvalidOperationException">Thrown when the workflow failed or was terminated.</exception>
|
||||
ValueTask<TResult?> WaitForCompletionAsync<TResult>(CancellationToken cancellationToken = default);
|
||||
}
|
||||
@@ -0,0 +1,41 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Defines a client for running and managing workflow executions.
|
||||
/// </summary>
|
||||
public interface IWorkflowClient
|
||||
{
|
||||
/// <summary>
|
||||
/// Runs a workflow and returns a handle to monitor its execution.
|
||||
/// </summary>
|
||||
/// <typeparam name="TInput">The type of the input to the workflow.</typeparam>
|
||||
/// <param name="workflow">The workflow to execute.</param>
|
||||
/// <param name="input">The input to pass to the workflow's starting executor.</param>
|
||||
/// <param name="runId">Optional identifier for the run. If not provided, a new ID will be generated.</param>
|
||||
/// <param name="cancellationToken">A cancellation token to observe.</param>
|
||||
/// <returns>An <see cref="IWorkflowRun"/> that can be used to monitor the workflow execution.</returns>
|
||||
ValueTask<IWorkflowRun> RunAsync<TInput>(
|
||||
Workflow workflow,
|
||||
TInput input,
|
||||
string? runId = null,
|
||||
CancellationToken cancellationToken = default)
|
||||
where TInput : notnull;
|
||||
|
||||
/// <summary>
|
||||
/// Runs a workflow with string input and returns a handle to monitor its execution.
|
||||
/// </summary>
|
||||
/// <param name="workflow">The workflow to execute.</param>
|
||||
/// <param name="input">The string input to pass to the workflow.</param>
|
||||
/// <param name="runId">Optional identifier for the run. If not provided, a new ID will be generated.</param>
|
||||
/// <param name="cancellationToken">A cancellation token to observe.</param>
|
||||
/// <returns>An <see cref="IWorkflowRun"/> that can be used to monitor the workflow execution.</returns>
|
||||
ValueTask<IWorkflowRun> RunAsync(
|
||||
Workflow workflow,
|
||||
string input,
|
||||
string? runId = null,
|
||||
CancellationToken cancellationToken = default);
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a running instance of a workflow.
|
||||
/// </summary>
|
||||
public interface IWorkflowRun
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets the unique identifier for the run.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This identifier can be provided at the start of the run, or auto-generated.
|
||||
/// For durable runs, this corresponds to the orchestration instance ID.
|
||||
/// </remarks>
|
||||
string RunId { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets all events that have been emitted by the workflow.
|
||||
/// </summary>
|
||||
IEnumerable<WorkflowEvent> OutgoingEvents { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets the number of events emitted since the last access to <see cref="NewEvents"/>.
|
||||
/// </summary>
|
||||
int NewEventCount { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets all events emitted by the workflow since the last access to this property.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Each access to this property advances the bookmark, so subsequent accesses
|
||||
/// will only return events emitted after the previous access.
|
||||
/// </remarks>
|
||||
IEnumerable<WorkflowEvent> NewEvents { get; }
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Information about a message sent via <see cref="IWorkflowContext.SendMessageAsync"/>.
|
||||
/// </summary>
|
||||
internal sealed class SentMessageInfo
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets or sets the serialized message content.
|
||||
/// </summary>
|
||||
public string? Message { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// Gets or sets the full type name of the message.
|
||||
/// </summary>
|
||||
public string? TypeName { get; set; }
|
||||
}
|
||||
@@ -0,0 +1,245 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Analyzes workflow structure to extract executor metadata and build graph information
|
||||
/// for message-driven execution.
|
||||
/// </summary>
|
||||
internal static class WorkflowAnalyzer
|
||||
{
|
||||
private const string AgentExecutorTypeName = "AIAgentHostExecutor";
|
||||
private const string AgentAssemblyPrefix = "Microsoft.Agents.AI";
|
||||
private const string ExecutorTypePrefix = "Executor";
|
||||
|
||||
/// <summary>
|
||||
/// Analyzes a workflow instance and returns a list of executors with their metadata.
|
||||
/// </summary>
|
||||
/// <param name="workflow">The workflow instance to analyze.</param>
|
||||
/// <returns>A list of executor information in workflow order.</returns>
|
||||
internal static List<WorkflowExecutorInfo> GetExecutorsFromWorkflowInOrder(Workflow workflow)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(workflow);
|
||||
|
||||
return workflow.ReflectExecutors()
|
||||
.Select(kvp => CreateExecutorInfo(kvp.Key, kvp.Value))
|
||||
.ToList();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Builds the workflow graph information needed for message-driven execution.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Extracts routing information including successors, predecessors, edge conditions,
|
||||
/// and output types. Supports cyclic workflows through message-driven superstep execution.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// The returned <see cref="WorkflowGraphInfo"/> is consumed by <c>DurableEdgeMap</c>
|
||||
/// to build the runtime routing layer:
|
||||
/// <c>Successors</c> become <c>IDurableEdgeRouter</c> instances,
|
||||
/// <c>Predecessors</c> become fan-in counts, and
|
||||
/// <c>EdgeConditions</c> / <c>ExecutorOutputTypes</c> are passed into
|
||||
/// <c>DurableDirectEdgeRouter</c> for conditional routing with typed deserialization.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
/// <param name="workflow">The workflow instance to analyze.</param>
|
||||
/// <returns>A graph info object containing routing information.</returns>
|
||||
internal static WorkflowGraphInfo BuildGraphInfo(Workflow workflow)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(workflow);
|
||||
|
||||
Dictionary<string, ExecutorBinding> executors = workflow.ReflectExecutors();
|
||||
|
||||
WorkflowGraphInfo graphInfo = new()
|
||||
{
|
||||
StartExecutorId = workflow.StartExecutorId
|
||||
};
|
||||
|
||||
InitializeExecutorMappings(graphInfo, executors);
|
||||
PopulateGraphFromEdges(graphInfo, workflow.Edges);
|
||||
|
||||
return graphInfo;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Determines whether the specified executor type is an agentic executor.
|
||||
/// </summary>
|
||||
/// <param name="executorType">The executor type to check.</param>
|
||||
/// <returns><c>true</c> if the executor is an agentic executor; otherwise, <c>false</c>.</returns>
|
||||
internal static bool IsAgentExecutorType(Type executorType)
|
||||
{
|
||||
string typeName = executorType.FullName ?? executorType.Name;
|
||||
string assemblyName = executorType.Assembly.GetName().Name ?? string.Empty;
|
||||
|
||||
return typeName.Contains(AgentExecutorTypeName, StringComparison.OrdinalIgnoreCase)
|
||||
&& assemblyName.Contains(AgentAssemblyPrefix, StringComparison.OrdinalIgnoreCase);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Creates a <see cref="WorkflowExecutorInfo"/> from an executor binding.
|
||||
/// </summary>
|
||||
/// <param name="executorId">The unique identifier of the executor.</param>
|
||||
/// <param name="binding">The executor binding containing type and configuration information.</param>
|
||||
/// <returns>A new <see cref="WorkflowExecutorInfo"/> instance with extracted metadata.</returns>
|
||||
private static WorkflowExecutorInfo CreateExecutorInfo(string executorId, ExecutorBinding binding)
|
||||
{
|
||||
bool isAgentic = IsAgentExecutorType(binding.ExecutorType);
|
||||
RequestPort? requestPort = (binding is RequestPortBinding rpb) ? rpb.Port : null;
|
||||
Workflow? subWorkflow = (binding is SubworkflowBinding swb) ? swb.WorkflowInstance : null;
|
||||
|
||||
return new WorkflowExecutorInfo(executorId, isAgentic, requestPort, subWorkflow);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Initializes the graph info with empty collections for each executor.
|
||||
/// </summary>
|
||||
/// <param name="graphInfo">The graph info to initialize.</param>
|
||||
/// <param name="executors">The dictionary of executor bindings.</param>
|
||||
private static void InitializeExecutorMappings(WorkflowGraphInfo graphInfo, Dictionary<string, ExecutorBinding> executors)
|
||||
{
|
||||
foreach ((string executorId, ExecutorBinding binding) in executors)
|
||||
{
|
||||
graphInfo.Successors[executorId] = [];
|
||||
graphInfo.Predecessors[executorId] = [];
|
||||
graphInfo.ExecutorOutputTypes[executorId] = GetExecutorOutputType(binding.ExecutorType);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Populates the graph info with successor/predecessor relationships and edge conditions.
|
||||
/// </summary>
|
||||
/// <param name="graphInfo">The graph info to populate.</param>
|
||||
/// <param name="edges">The dictionary of edges grouped by source executor ID.</param>
|
||||
private static void PopulateGraphFromEdges(WorkflowGraphInfo graphInfo, Dictionary<string, HashSet<Edge>> edges)
|
||||
{
|
||||
foreach ((string sourceId, HashSet<Edge> edgeSet) in edges)
|
||||
{
|
||||
List<string> successors = graphInfo.Successors[sourceId];
|
||||
|
||||
foreach (Edge edge in edgeSet)
|
||||
{
|
||||
AddSuccessorsFromEdge(graphInfo, sourceId, edge, successors);
|
||||
TryAddEdgeCondition(graphInfo, edge);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Adds successor relationships from an edge to the graph info.
|
||||
/// </summary>
|
||||
/// <param name="graphInfo">The graph info to update.</param>
|
||||
/// <param name="sourceId">The source executor ID.</param>
|
||||
/// <param name="edge">The edge containing connection information.</param>
|
||||
/// <param name="successors">The list of successors to append to.</param>
|
||||
private static void AddSuccessorsFromEdge(
|
||||
WorkflowGraphInfo graphInfo,
|
||||
string sourceId,
|
||||
Edge edge,
|
||||
List<string> successors)
|
||||
{
|
||||
foreach (string sinkId in edge.Data.Connection.SinkIds)
|
||||
{
|
||||
if (!graphInfo.Successors.ContainsKey(sinkId))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
successors.Add(sinkId);
|
||||
graphInfo.Predecessors[sinkId].Add(sourceId);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Extracts and adds an edge condition to the graph info if present.
|
||||
/// </summary>
|
||||
/// <param name="graphInfo">The graph info to update.</param>
|
||||
/// <param name="edge">The edge that may contain a condition.</param>
|
||||
private static void TryAddEdgeCondition(WorkflowGraphInfo graphInfo, Edge edge)
|
||||
{
|
||||
DirectEdgeData? directEdge = edge.DirectEdgeData;
|
||||
|
||||
if (directEdge?.Condition is not null)
|
||||
{
|
||||
graphInfo.EdgeConditions[(directEdge.SourceId, directEdge.SinkId)] = directEdge.Condition;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Extracts the output type from an executor type by walking the inheritance chain.
|
||||
/// </summary>
|
||||
/// <param name="executorType">The executor type to analyze.</param>
|
||||
/// <returns>
|
||||
/// The TOutput type for Executor<TInput, TOutput>,
|
||||
/// or <c>null</c> for Executor<TInput> (void output) or non-executor types.
|
||||
/// </returns>
|
||||
private static Type? GetExecutorOutputType(Type executorType)
|
||||
{
|
||||
Type? currentType = executorType;
|
||||
|
||||
while (currentType is not null)
|
||||
{
|
||||
Type? outputType = TryExtractOutputTypeFromGeneric(currentType);
|
||||
if (outputType is not null || IsVoidExecutorType(currentType))
|
||||
{
|
||||
return outputType;
|
||||
}
|
||||
|
||||
currentType = currentType.BaseType;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Attempts to extract the output type from a generic executor type.
|
||||
/// </summary>
|
||||
/// <param name="type">The type to inspect.</param>
|
||||
/// <returns>The TOutput type if this is an Executor<TInput, TOutput>; otherwise, <c>null</c>.</returns>
|
||||
private static Type? TryExtractOutputTypeFromGeneric(Type type)
|
||||
{
|
||||
if (!type.IsGenericType)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
Type genericDefinition = type.GetGenericTypeDefinition();
|
||||
Type[] genericArgs = type.GetGenericArguments();
|
||||
|
||||
bool isExecutorType = genericDefinition.Name.StartsWith(ExecutorTypePrefix, StringComparison.Ordinal);
|
||||
if (!isExecutorType)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
// Executor<TInput, TOutput> - return TOutput
|
||||
if (genericArgs.Length == 2)
|
||||
{
|
||||
return genericArgs[1];
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Determines whether the type is a void-returning executor (Executor<TInput>).
|
||||
/// </summary>
|
||||
/// <param name="type">The type to check.</param>
|
||||
/// <returns><c>true</c> if this is an Executor with a single type parameter; otherwise, <c>false</c>.</returns>
|
||||
private static bool IsVoidExecutorType(Type type)
|
||||
{
|
||||
if (!type.IsGenericType)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
Type genericDefinition = type.GetGenericTypeDefinition();
|
||||
Type[] genericArgs = type.GetGenericArguments();
|
||||
|
||||
// Executor<TInput> with 1 type parameter indicates void return
|
||||
return genericArgs.Length == 1
|
||||
&& genericDefinition.Name.StartsWith(ExecutorTypePrefix, StringComparison.Ordinal);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using Microsoft.Agents.AI.Workflows;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Represents an executor in the workflow with its metadata.
|
||||
/// </summary>
|
||||
/// <param name="ExecutorId">The unique identifier of the executor.</param>
|
||||
/// <param name="IsAgenticExecutor">Indicates whether this executor is an agentic executor.</param>
|
||||
/// <param name="RequestPort">The request port if this executor is a request port executor; otherwise, null.</param>
|
||||
/// <param name="SubWorkflow">The sub-workflow if this executor is a sub-workflow executor; otherwise, null.</param>
|
||||
internal sealed record WorkflowExecutorInfo(
|
||||
string ExecutorId,
|
||||
bool IsAgenticExecutor,
|
||||
RequestPort? RequestPort = null,
|
||||
Workflow? SubWorkflow = null)
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets a value indicating whether this executor is a request port executor (human-in-the-loop).
|
||||
/// </summary>
|
||||
public bool IsRequestPortExecutor => this.RequestPort is not null;
|
||||
|
||||
/// <summary>
|
||||
/// Gets a value indicating whether this executor is a sub-workflow executor.
|
||||
/// </summary>
|
||||
public bool IsSubworkflowExecutor => this.SubWorkflow is not null;
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
// Example: Given this workflow graph with a fan-out from B and a fan-in at E,
|
||||
// plus a conditional edge from B to D:
|
||||
//
|
||||
// [A] ──► [B] ──► [C] ──► [E]
|
||||
// │ ▲
|
||||
// └──► [D] ──────┘
|
||||
// (condition:
|
||||
// x => x.NeedsReview)
|
||||
//
|
||||
// WorkflowAnalyzer.BuildGraphInfo() produces:
|
||||
//
|
||||
// StartExecutorId = "A"
|
||||
//
|
||||
// Successors (who does each executor send output to?):
|
||||
// ┌──────────┬──────────────┐
|
||||
// │ "A" │ ["B"] │
|
||||
// │ "B" │ ["C", "D"] │ ◄── fan-out: B sends to both C and D
|
||||
// │ "C" │ ["E"] │
|
||||
// │ "D" │ ["E"] │
|
||||
// │ "E" │ [] │ ◄── terminal: no successors
|
||||
// └──────────┴──────────────┘
|
||||
//
|
||||
// Predecessors (who feeds into each executor?):
|
||||
// ┌──────────┬──────────────┐
|
||||
// │ "A" │ [] │ ◄── start: no predecessors
|
||||
// │ "B" │ ["A"] │
|
||||
// │ "C" │ ["B"] │
|
||||
// │ "D" │ ["B"] │
|
||||
// │ "E" │ ["C", "D"] │ ◄── fan-in: count=2, messages will be aggregated
|
||||
// └──────────┴──────────────┘
|
||||
//
|
||||
// EdgeConditions (which edges have routing conditions?):
|
||||
// ┌──────────────────┬──────────────────────────┐
|
||||
// │ ("B", "D") │ x => x.NeedsReview │ ◄── D only receives if condition is true
|
||||
// └──────────────────┴──────────────────────────┘
|
||||
// (The B→C edge has no condition, so C always receives B's output.)
|
||||
//
|
||||
// ExecutorOutputTypes (what type does each executor return?):
|
||||
// ┌──────────┬──────────────────┐
|
||||
// │ "A" │ typeof(string) │ ◄── used by DurableDirectEdgeRouter to deserialize
|
||||
// │ "B" │ typeof(Order) │ the JSON message for condition evaluation
|
||||
// │ "C" │ typeof(Report) │
|
||||
// │ "D" │ typeof(Report) │
|
||||
// │ "E" │ typeof(string) │
|
||||
// └──────────┴──────────────────┘
|
||||
//
|
||||
// DurableEdgeMap then consumes this to build the runtime routing layer.
|
||||
|
||||
using System.Diagnostics;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Represents the workflow graph structure needed for message-driven execution.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// This is a simplified representation that contains only the information needed
|
||||
/// for routing messages between executors during superstep execution:
|
||||
/// </para>
|
||||
/// <list type="bullet">
|
||||
/// <item><description>Successors for routing messages forward</description></item>
|
||||
/// <item><description>Predecessors for detecting fan-in points</description></item>
|
||||
/// <item><description>Edge conditions for conditional routing</description></item>
|
||||
/// <item><description>Output types for deserialization during condition evaluation</description></item>
|
||||
/// </list>
|
||||
/// </remarks>
|
||||
[DebuggerDisplay("Start = {StartExecutorId}, Executors = {Successors.Count}")]
|
||||
internal sealed class WorkflowGraphInfo
|
||||
{
|
||||
/// <summary>
|
||||
/// Gets or sets the starting executor ID for the workflow.
|
||||
/// </summary>
|
||||
public string StartExecutorId { get; set; } = string.Empty;
|
||||
|
||||
/// <summary>
|
||||
/// Maps each executor ID to its successors (for message routing).
|
||||
/// </summary>
|
||||
public Dictionary<string, List<string>> Successors { get; } = [];
|
||||
|
||||
/// <summary>
|
||||
/// Maps each executor ID to its predecessors (for fan-in detection).
|
||||
/// </summary>
|
||||
public Dictionary<string, List<string>> Predecessors { get; } = [];
|
||||
|
||||
/// <summary>
|
||||
/// Maps edge connections (sourceId, targetId) to their condition functions.
|
||||
/// The condition function takes the predecessor's result and returns true if the edge should be followed.
|
||||
/// </summary>
|
||||
public Dictionary<(string SourceId, string TargetId), Func<object?, bool>?> EdgeConditions { get; } = [];
|
||||
|
||||
/// <summary>
|
||||
/// Maps executor IDs to their output types (for proper deserialization during condition evaluation).
|
||||
/// </summary>
|
||||
public Dictionary<string, Type?> ExecutorOutputTypes { get; } = [];
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
// Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
|
||||
namespace Microsoft.Agents.AI.DurableTask.Workflows;
|
||||
|
||||
/// <summary>
|
||||
/// Provides helper methods for workflow naming conventions used in durable orchestrations.
|
||||
/// </summary>
|
||||
internal static class WorkflowNamingHelper
|
||||
{
|
||||
internal const string OrchestrationFunctionPrefix = "dafx-";
|
||||
private const char ExecutorIdSuffixSeparator = '_';
|
||||
|
||||
/// <summary>
|
||||
/// Converts a workflow name to its corresponding orchestration function name.
|
||||
/// </summary>
|
||||
/// <param name="workflowName">The workflow name.</param>
|
||||
/// <returns>The orchestration function name.</returns>
|
||||
/// <exception cref="ArgumentException">Thrown when the workflow name is null or empty.</exception>
|
||||
internal static string ToOrchestrationFunctionName(string workflowName)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(workflowName);
|
||||
return string.Concat(OrchestrationFunctionPrefix, workflowName);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Converts an orchestration function name back to its workflow name.
|
||||
/// </summary>
|
||||
/// <param name="orchestrationFunctionName">The orchestration function name.</param>
|
||||
/// <returns>The workflow name.</returns>
|
||||
/// <exception cref="ArgumentException">Thrown when the orchestration function name is null, empty, or doesn't have the expected prefix.</exception>
|
||||
internal static string ToWorkflowName(string orchestrationFunctionName)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(orchestrationFunctionName);
|
||||
|
||||
if (!TryGetWorkflowName(orchestrationFunctionName, out string? workflowName))
|
||||
{
|
||||
throw new ArgumentException(
|
||||
$"Orchestration function name '{orchestrationFunctionName}' does not have the expected '{OrchestrationFunctionPrefix}' prefix or is missing a workflow name.",
|
||||
nameof(orchestrationFunctionName));
|
||||
}
|
||||
|
||||
return workflowName;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Extracts the executor name from an executor ID.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// For non-agentic executors, the executor ID is the same as the executor name (e.g., "OrderParser").
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// For agentic executors, the workflow builder appends a GUID suffix separated by an underscore
|
||||
/// (e.g., "Physicist_8884e71021334ce49517fa2b17b1695b"). This method extracts just the name portion.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
/// <param name="executorId">The executor ID, which may contain a GUID suffix.</param>
|
||||
/// <returns>The executor name without any GUID suffix.</returns>
|
||||
/// <exception cref="ArgumentException">Thrown when the executor ID is null or empty.</exception>
|
||||
internal static string GetExecutorName(string executorId)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(executorId);
|
||||
|
||||
int separatorIndex = executorId.IndexOf(ExecutorIdSuffixSeparator);
|
||||
return separatorIndex > 0 ? executorId[..separatorIndex] : executorId;
|
||||
}
|
||||
|
||||
private static bool TryGetWorkflowName(string? orchestrationFunctionName, [NotNullWhen(true)] out string? workflowName)
|
||||
{
|
||||
workflowName = null;
|
||||
|
||||
if (string.IsNullOrEmpty(orchestrationFunctionName) ||
|
||||
!orchestrationFunctionName.StartsWith(OrchestrationFunctionPrefix, StringComparison.Ordinal))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
workflowName = orchestrationFunctionName[OrchestrationFunctionPrefix.Length..];
|
||||
return workflowName.Length > 0;
|
||||
}
|
||||
}
|
||||
@@ -25,6 +25,7 @@
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<InternalsVisibleTo Include="Microsoft.Agents.AI.DurableTask" />
|
||||
<InternalsVisibleTo Include="Microsoft.Agents.AI.Workflows.UnitTests" />
|
||||
<InternalsVisibleTo Include="Microsoft.Agents.AI.Workflows.Generators.UnitTests" />
|
||||
</ItemGroup>
|
||||
|
||||
Reference in New Issue
Block a user