agent/agent-framework
1
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

.NET: [Feature Branch] Add basic durable workflow support (#3648)

Browse Source 
* 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
2026-02-06 16:02:42 -08:00
committed by GitHub
Unverified
parent 98cd72839e
commit e8d0bd9051
54 changed files with 4863 additions and 505 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dotnet/agent-framework-dotnet.slnx
+6
View File
@@ -47,6 +47,12 @@
<Project Path="samples/Durable/Agents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
<Project Path="samples/Durable/Agents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
</Folder>
<Folder Name="/Samples/Durable/Workflows/">
<Project Path="samples/Durable/Workflow/ConsoleApps/01_SequentialWorkflow/01_SequentialWorkflow.csproj" />
<Project Path="samples/Durable/Workflow/ConsoleApps/02_ConcurrentWorkflow/02_ConcurrentWorkflow.csproj" />
<Project Path="samples/Durable/Workflow/ConsoleApps/03_ConditionalEdges/03_ConditionalEdges.csproj" />
<Project Path="samples/Durable/Workflow/ConsoleApps/04_WorkflowAndAgents/04_WorkflowAndAgents.csproj" />
</Folder>
<Folder Name="/Samples/GettingStarted/">
<File Path="samples/GettingStarted/README.md" />
</Folder>
dotnet/samples/Durable/Workflow/ConsoleApps/01_SequentialWorkflow/01_SequentialWorkflow.csproj
+29
View File
@@ -0,0 +1,29 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net10.0</TargetFrameworks>
<OutputType>Exe</OutputType>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<AssemblyName>SequentialWorkflow</AssemblyName>
<RootNamespace>SequentialWorkflow</RootNamespace>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Azure.Identity" />
<PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
<PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
<PackageReference Include="Microsoft.Extensions.Hosting" />
</ItemGroup>
<!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
<!--
<ItemGroup>
<PackageReference Include="Microsoft.Agents.AI.DurableTask" />
<PackageReference Include="Microsoft.Agents.AI.Workflows" />
</ItemGroup>
-->
<ItemGroup>
<ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
<ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
</ItemGroup>
</Project>
dotnet/samples/Durable/Workflow/ConsoleApps/01_SequentialWorkflow/OrderCancelExecutors.cs
+116
View File
@@ -0,0 +1,116 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI.Workflows;
namespace SequentialWorkflow;
/// <summary>
/// Represents a request to cancel an order.
/// </summary>
/// <param name="OrderId">The ID of the order to cancel.</param>
/// <param name="Reason">The reason for cancellation.</param>
internal sealed record OrderCancelRequest(string OrderId, string Reason);
/// <summary>
/// Looks up an order by its ID and return an Order object.
/// </summary>
internal sealed class OrderLookup() : Executor<OrderCancelRequest, Order>("OrderLookup")
{
public override async ValueTask<Order> HandleAsync(
OrderCancelRequest message,
IWorkflowContext context,
CancellationToken cancellationToken = default)
{
Console.WriteLine();
Console.ForegroundColor = ConsoleColor.Magenta;
Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
Console.WriteLine($"│ [Activity] OrderLookup: Starting lookup for order '{message.OrderId}'");
Console.WriteLine($"│ [Activity] OrderLookup: Cancellation reason: '{message.Reason}'");
Console.ResetColor();
// Simulate database lookup with delay
await Task.Delay(TimeSpan.FromMicroseconds(100), cancellationToken);
Order order = new(
Id: message.OrderId,
OrderDate: DateTime.UtcNow.AddDays(-1),
IsCancelled: false,
CancelReason: message.Reason,
Customer: new Customer(Name: "Jerry", Email: "jerry@example.com"));
Console.ForegroundColor = ConsoleColor.Magenta;
Console.WriteLine($"│ [Activity] OrderLookup: Found order '{message.OrderId}' for customer '{order.Customer.Name}'");
Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
Console.ResetColor();
return order;
}
}
/// <summary>
/// Cancels an order.
/// </summary>
internal sealed class OrderCancel() : Executor<Order, Order>("OrderCancel")
{
public override async ValueTask<Order> HandleAsync(
Order message,
IWorkflowContext context,
CancellationToken cancellationToken = default)
{
// Log that this activity is executing (not replaying)
Console.WriteLine();
Console.ForegroundColor = ConsoleColor.Yellow;
Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
Console.WriteLine($"│ [Activity] OrderCancel: Starting cancellation for order '{message.Id}'");
Console.ResetColor();
// Simulate a slow cancellation process (e.g., calling external payment system)
for (int i = 1; i <= 3; i++)
{
await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);
Console.ForegroundColor = ConsoleColor.DarkYellow;
Console.WriteLine("│ [Activity] OrderCancel: Processing...");
Console.ResetColor();
}
Order cancelledOrder = message with { IsCancelled = true };
Console.ForegroundColor = ConsoleColor.Yellow;
Console.WriteLine($"│ [Activity] OrderCancel: ✓ Order '{cancelledOrder.Id}' has been cancelled");
Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
Console.ResetColor();
return cancelledOrder;
}
}
/// <summary>
/// Sends a cancellation confirmation email to the customer.
/// </summary>
internal sealed class SendEmail() : Executor<Order, string>("SendEmail")
{
public override ValueTask<string> HandleAsync(
Order message,
IWorkflowContext context,
CancellationToken cancellationToken = default)
{
Console.WriteLine();
Console.ForegroundColor = ConsoleColor.Cyan;
Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
Console.WriteLine($"│ [Activity] SendEmail: Sending email to '{message.Customer.Email}'...");
Console.ResetColor();
string result = $"Cancellation email sent for order {message.Id} to {message.Customer.Email}.";
Console.ForegroundColor = ConsoleColor.Cyan;
Console.WriteLine("│ [Activity] SendEmail: ✓ Email sent successfully!");
Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
Console.ResetColor();
return ValueTask.FromResult(result);
}
}
internal sealed record Order(string Id, DateTime OrderDate, bool IsCancelled, string? CancelReason, Customer Customer);
internal sealed record Customer(string Name, string Email);
dotnet/samples/Durable/Workflow/ConsoleApps/01_SequentialWorkflow/Program.cs
+93
View File
@@ -0,0 +1,93 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI.DurableTask;
using Microsoft.Agents.AI.DurableTask.Workflows;
using Microsoft.Agents.AI.Workflows;
using Microsoft.DurableTask.Client.AzureManaged;
using Microsoft.DurableTask.Worker.AzureManaged;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using SequentialWorkflow;
// Get DTS connection string from environment variable
string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
// Define executors for the workflow
OrderLookup orderLookup = new();
OrderCancel orderCancel = new();
SendEmail sendEmail = new();
// Build the CancelOrder workflow: OrderLookup -> OrderCancel -> SendEmail
Workflow cancelOrder = new WorkflowBuilder(orderLookup)
.WithName("CancelOrder")
.WithDescription("Cancel an order and notify the customer")
.AddEdge(orderLookup, orderCancel)
.AddEdge(orderCancel, sendEmail)
.Build();
IHost host = Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
.ConfigureServices(services =>
{
services.ConfigureDurableWorkflows(
workflowOptions => workflowOptions.AddWorkflow(cancelOrder),
workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
})
.Build();
await host.StartAsync();
IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
Console.WriteLine("Durable Workflow Sample");
Console.WriteLine("Workflow: OrderLookup -> OrderCancel -> SendEmail");
Console.WriteLine();
Console.WriteLine("Enter an order ID (or 'exit'):");
while (true)
{
Console.Write("> ");
string? input = Console.ReadLine();
if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
{
break;
}
try
{
OrderCancelRequest request = new(OrderId: input, Reason: "Customer requested cancellation");
await StartNewWorkflowAsync(request, cancelOrder, workflowClient);
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
Console.WriteLine();
}
await host.StopAsync();
// Start a new workflow using IWorkflowClient with typed input
static async Task StartNewWorkflowAsync(OrderCancelRequest request, Workflow workflow, IWorkflowClient client)
{
Console.WriteLine($"Starting workflow for order '{request.OrderId}' (Reason: {request.Reason})...");
// RunAsync returns IWorkflowRun, cast to IAwaitableWorkflowRun for completion waiting
IAwaitableWorkflowRun run = (IAwaitableWorkflowRun)await client.RunAsync(workflow, request);
Console.WriteLine($"Run ID: {run.RunId}");
try
{
Console.WriteLine("Waiting for workflow to complete...");
string? result = await run.WaitForCompletionAsync<string>();
Console.WriteLine($"Workflow completed. {result}");
}
catch (InvalidOperationException ex)
{
Console.WriteLine($"Failed: {ex.Message}");
}
}
dotnet/samples/Durable/Workflow/ConsoleApps/01_SequentialWorkflow/README.md
+83
View File
@@ -0,0 +1,83 @@
# Sequential Workflow Sample
This sample demonstrates how to run a sequential workflow as a durable orchestration from a console application using the Durable Task Framework. It showcases the **durability** aspect - if the process crashes mid-execution, the workflow automatically resumes without re-executing completed activities.
## Key Concepts Demonstrated
- Building a sequential workflow with the `WorkflowBuilder` API
- Using `ConfigureDurableWorkflows` to register workflows with dependency injection
- Running workflows with `IWorkflowClient`
- **Durability**: Automatic resume of interrupted workflows
- **Activity caching**: Completed activities are not re-executed on replay
## Overview
The sample implements an order cancellation workflow with three executors:
```
OrderLookup --> OrderCancel --> SendEmail
```
| Executor | Description |
|----------|-------------|
| OrderLookup | Looks up an order by ID |
| OrderCancel | Marks the order as cancelled |
| SendEmail | Sends a cancellation confirmation email |
## Durability Demonstration
The key feature of Durable Task Framework is **durability**:
- **Activity results are persisted**: When an activity completes, its result is saved
- **Orchestrations replay**: On restart, the orchestration replays from the beginning
- **Completed activities skip execution**: The framework uses cached results
- **Automatic resume**: The worker automatically picks up pending work on startup
### Try It Yourself
> **Tip:** To give yourself more time to stop the application during `OrderCancel`, consider increasing the loop iteration count or `Task.Delay` duration in the `OrderCancel` executor in `OrderCancelExecutors.cs`.
1. Start the application and enter an order ID (e.g., `12345`)
2. Wait for `OrderLookup` to complete, then stop the app (Ctrl+C) during `OrderCancel`
3. Restart the application
4. Observe:
- `OrderLookup` is **NOT** re-executed (result was cached)
- `OrderCancel` **restarts** (it didn't complete before the interruption)
- `SendEmail` runs after `OrderCancel` completes
## Environment Setup
See the [README.md](../README.md) file in the parent directory for information on configuring the environment, including how to install and run the Durable Task Scheduler.
## Running the Sample
```bash
cd dotnet/samples/Durable/Workflow/ConsoleApps/01_SequentialWorkflow
dotnet run --framework net10.0
```
### Sample Output
```text
Durable Workflow Sample
Workflow: OrderLookup -> OrderCancel -> SendEmail
Enter an order ID (or 'exit'):
> 12345
Starting workflow for order: 12345
Run ID: abc123...
[OrderLookup] Looking up order '12345'...
[OrderLookup] Found order for customer 'Jerry'
[OrderCancel] Cancelling order '12345'...
[OrderCancel] Order cancelled successfully
[SendEmail] Sending email to 'jerry@example.com'...
[SendEmail] Email sent successfully
Workflow completed!
> exit
```
dotnet/samples/Durable/Workflow/ConsoleApps/02_ConcurrentWorkflow/02_ConcurrentWorkflow.csproj
+30
View File
@@ -0,0 +1,30 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net10.0</TargetFrameworks>
<OutputType>Exe</OutputType>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<AssemblyName>WorkflowConcurrency</AssemblyName>
<RootNamespace>WorkflowConcurrency</RootNamespace>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Azure.Identity" />
<PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
<PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
<PackageReference Include="Microsoft.Extensions.Hosting" />
<PackageReference Include="Azure.AI.OpenAI" />
</ItemGroup>
<!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
<!--
<ItemGroup>
<PackageReference Include="Microsoft.Agents.AI.DurableTask" />
<PackageReference Include="Microsoft.Agents.AI.Workflows" />
</ItemGroup>
-->
<ItemGroup>
<ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
<ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
</ItemGroup>
</Project>
dotnet/samples/Durable/Workflow/ConsoleApps/02_ConcurrentWorkflow/ExpertExecutors.cs
+73
View File
@@ -0,0 +1,73 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI.Workflows;
namespace WorkflowConcurrency;
/// <summary>
/// Parses and validates the incoming question before sending to AI agents.
/// </summary>
internal sealed class ParseQuestionExecutor() : Executor<string, string>("ParseQuestion")
{
public override ValueTask<string> HandleAsync(
string message,
IWorkflowContext context,
CancellationToken cancellationToken = default)
{
Console.WriteLine();
Console.ForegroundColor = ConsoleColor.Magenta;
Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
Console.WriteLine("│ [ParseQuestion] Preparing question for AI agents...");
string formattedQuestion = message.Trim();
if (!formattedQuestion.EndsWith('?'))
{
formattedQuestion += "?";
}
Console.WriteLine($"│ [ParseQuestion] Question: \"{formattedQuestion}\"");
Console.WriteLine("│ [ParseQuestion] → Sending to Physicist and Chemist in PARALLEL...");
Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
Console.ResetColor();
return ValueTask.FromResult(formattedQuestion);
}
}
/// <summary>
/// Aggregates responses from all AI agents into a comprehensive answer.
/// This is the Fan-in point where parallel results are collected.
/// </summary>
internal sealed class AggregatorExecutor() : Executor<string[], string>("Aggregator")
{
public override ValueTask<string> HandleAsync(
string[] message,
IWorkflowContext context,
CancellationToken cancellationToken = default)
{
Console.WriteLine();
Console.ForegroundColor = ConsoleColor.Cyan;
Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
Console.WriteLine($"│ [Aggregator] 📋 Received {message.Length} AI agent responses");
Console.WriteLine("│ [Aggregator] Combining into comprehensive answer...");
Console.WriteLine("│ [Aggregator] ✓ Aggregation complete!");
Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
Console.ResetColor();
string aggregatedResult = "═══════════════════════════════════════════════════════════════\n" +
" AI EXPERT PANEL RESPONSES\n" +
"═══════════════════════════════════════════════════════════════\n\n";
for (int i = 0; i < message.Length; i++)
{
string expertLabel = i == 0 ? "⚛️ PHYSICIST" : "🧪 CHEMIST";
aggregatedResult += $"{expertLabel}:\n{message[i]}\n\n";
}
aggregatedResult += "═══════════════════════════════════════════════════════════════\n" +
$"Summary: Received perspectives from {message.Length} AI experts.\n" +
"═══════════════════════════════════════════════════════════════";
return ValueTask.FromResult(aggregatedResult);
}
}
dotnet/samples/Durable/Workflow/ConsoleApps/02_ConcurrentWorkflow/Program.cs
+114
View File
@@ -0,0 +1,114 @@
// Copyright (c) Microsoft. All rights reserved.
// This sample demonstrates the Fan-out/Fan-in pattern in a durable workflow.
// The workflow uses 4 executors: 2 class-based executors and 2 AI agents.
//
// WORKFLOW PATTERN:
//
// ParseQuestion (class-based)
// |
// +----------+----------+
// | |
// Physicist Chemist
// (AI Agent) (AI Agent)
// | |
// +----------+----------+
// |
// Aggregator (class-based)
using Azure;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.DurableTask;
using Microsoft.Agents.AI.DurableTask.Workflows;
using Microsoft.Agents.AI.Workflows;
using Microsoft.DurableTask.Client.AzureManaged;
using Microsoft.DurableTask.Worker.AzureManaged;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using OpenAI.Chat;
using WorkflowConcurrency;
// Configuration
string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")
?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT is not set.");
string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
// Create Azure OpenAI client
AzureOpenAIClient openAiClient = !string.IsNullOrEmpty(azureOpenAiKey)
? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
: new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
ChatClient chatClient = openAiClient.GetChatClient(deploymentName);
// Define the 4 executors for the workflow
ParseQuestionExecutor parseQuestion = new();
AIAgent physicist = chatClient.AsAIAgent("You are a physics expert. Be concise (2-3 sentences).", "Physicist");
AIAgent chemist = chatClient.AsAIAgent("You are a chemistry expert. Be concise (2-3 sentences).", "Chemist");
AggregatorExecutor aggregator = new();
// Build workflow: ParseQuestion -> [Physicist, Chemist] (parallel) -> Aggregator
Workflow workflow = new WorkflowBuilder(parseQuestion)
.WithName("ExpertReview")
.AddFanOutEdge(parseQuestion, [physicist, chemist])
.AddFanInEdge([physicist, chemist], aggregator)
.Build();
// Configure and start the host
IHost host = Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
.ConfigureServices(services =>
{
services.ConfigureDurableOptions(
options => options.Workflows.AddWorkflow(workflow),
workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
})
.Build();
await host.StartAsync();
IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
Console.WriteLine("Fan-out/Fan-in Workflow Sample");
Console.WriteLine("ParseQuestion -> [Physicist, Chemist] -> Aggregator");
Console.WriteLine();
Console.WriteLine("Enter a science question (or 'exit' to quit):");
while (true)
{
Console.Write("> ");
string? input = Console.ReadLine();
if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
{
break;
}
try
{
IWorkflowRun run = await workflowClient.RunAsync(workflow, input);
Console.WriteLine($"Run ID: {run.RunId}");
if (run is IAwaitableWorkflowRun awaitableRun)
{
string? result = await awaitableRun.WaitForCompletionAsync<string>();
Console.WriteLine("Workflow completed!");
Console.WriteLine(result);
}
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
Console.WriteLine();
}
await host.StopAsync();
dotnet/samples/Durable/Workflow/ConsoleApps/02_ConcurrentWorkflow/README.md
+100
View File
@@ -0,0 +1,100 @@
# Concurrent Workflow Sample (Fan-Out/Fan-In)
This sample demonstrates the **fan-out/fan-in** pattern in a durable workflow, combining class-based executors with AI agents running in parallel.
## Key Concepts Demonstrated
- **Fan-out/Fan-in pattern**: Parallel execution with result aggregation
- **Mixed executor types**: Class-based executors and AI agents in the same workflow
- **AI agents as executors**: Using `ChatClient.AsAIAgent()` to create workflow-compatible agents
- **Workflow registration**: Auto-registration of agents used within workflows
- **Standalone agents**: Registering agents outside of workflows
## Overview
The sample implements an expert review workflow with four executors:
```
ParseQuestion
|
+----------+----------+
| |
Physicist Chemist
(AI Agent) (AI Agent)
| |
+----------+----------+
|
Aggregator
```
| Executor | Type | Description |
|----------|------|-------------|
| ParseQuestion | Class-based | Parses the user's question for expert review |
| Physicist | AI Agent | Provides physics perspective (runs in parallel) |
| Chemist | AI Agent | Provides chemistry perspective (runs in parallel) |
| Aggregator | Class-based | Combines expert responses into a final answer |
## Fan-Out/Fan-In Pattern
The workflow demonstrates the fan-out/fan-in pattern:
1. **Fan-out**: `ParseQuestion` sends the question to both `Physicist` and `Chemist` simultaneously
2. **Parallel execution**: Both AI agents process the question concurrently
3. **Fan-in**: `Aggregator` waits for both agents to complete, then combines their responses
This pattern is useful for:
- Gathering multiple perspectives on a problem
- Parallel processing of independent tasks
- Reducing overall execution time through concurrency
## Environment Setup
See the [README.md](../README.md) file in the parent directory for information on configuring the environment.
### Required Environment Variables
```bash
# Durable Task Scheduler (optional, defaults to localhost)
DURABLE_TASK_SCHEDULER_CONNECTION_STRING="Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
# Azure OpenAI (required)
AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
AZURE_OPENAI_DEPLOYMENT="gpt-4o"
AZURE_OPENAI_KEY="your-key" # Optional if using Azure CLI credentials
```
## Running the Sample
```bash
cd dotnet/samples/Durable/Workflow/ConsoleApps/02_ConcurrentWorkflow
dotnet run --framework net10.0
```
### Sample Output
```text
+-----------------------------------------------------------------------+
| Fan-out/Fan-in Workflow Sample (4 Executors) |
| |
| ParseQuestion -> [Physicist, Chemist] -> Aggregator |
| (class-based) (AI agents, parallel) (class-based) |
+-----------------------------------------------------------------------+
Enter a science question (or 'exit' to quit):
Question: Why is the sky blue?
Instance: abc123...
[ParseQuestion] Parsing question for expert review...
[Physicist] Analyzing from physics perspective...
[Chemist] Analyzing from chemistry perspective...
[Aggregator] Combining expert responses...
Workflow completed!
Physics perspective: The sky appears blue due to Rayleigh scattering...
Chemistry perspective: The molecular composition of our atmosphere...
Combined answer: ...
Question: exit
```
dotnet/samples/Durable/Workflow/ConsoleApps/03_ConditionalEdges/03_ConditionalEdges.csproj
+29
View File
@@ -0,0 +1,29 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net10.0</TargetFrameworks>
<OutputType>Exe</OutputType>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<AssemblyName>ConditionalEdges</AssemblyName>
<RootNamespace>ConditionalEdges</RootNamespace>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Azure.Identity" />
<PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
<PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
<PackageReference Include="Microsoft.Extensions.Hosting" />
</ItemGroup>
<!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
<!--
<ItemGroup>
<PackageReference Include="Microsoft.Agents.AI.DurableTask" />
<PackageReference Include="Microsoft.Agents.AI.Workflows" />
</ItemGroup>
-->
<ItemGroup>
<ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
<ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
</ItemGroup>
</Project>
dotnet/samples/Durable/Workflow/ConsoleApps/03_ConditionalEdges/NotifyFraud.cs
+85
View File
@@ -0,0 +1,85 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI.Workflows;
namespace ConditionalEdges;
internal sealed class Order
{
public Order(string id, decimal amount)
{
this.Id = id;
this.Amount = amount;
}
public string Id { get; }
public decimal Amount { get; }
public Customer? Customer { get; set; }
public string? PaymentReferenceNumber { get; set; }
}
public sealed record Customer(int Id, string Name, bool IsBlocked);
internal sealed class OrderIdParser() : Executor<string, Order>("OrderIdParser")
{
public override async ValueTask<Order> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
{
return GetOrder(message);
}
private static Order GetOrder(string id)
{
// Simulate fetching order details
return new Order(id, 100.0m);
}
}
internal sealed class OrderEnrich() : Executor<Order, Order>("EnrichOrder")
{
public override async ValueTask<Order> HandleAsync(Order message, IWorkflowContext context, CancellationToken cancellationToken = default)
{
message.Customer = GetCustomerForOrder(message.Id);
return message;
}
private static Customer GetCustomerForOrder(string orderId)
{
if (orderId.Contains('B'))
{
return new Customer(101, "George", true);
}
return new Customer(201, "Jerry", false);
}
}
internal sealed class PaymentProcesser() : Executor<Order, Order>("PaymentProcesser")
{
public override async ValueTask<Order> HandleAsync(Order message, IWorkflowContext context, CancellationToken cancellationToken = default)
{
// Call payment gateway.
message.PaymentReferenceNumber = Guid.NewGuid().ToString().Substring(0, 4);
return message;
}
}
internal sealed class NotifyFraud() : Executor<Order, string>("NotifyFraud")
{
public override async ValueTask<string> HandleAsync(Order message, IWorkflowContext context, CancellationToken cancellationToken = default)
{
// Notify fraud team.
return $"Order {message.Id} flagged as fraudulent for customer {message.Customer?.Name}.";
}
}
internal static class OrderRouteConditions
{
/// <summary>
/// Returns a condition that evaluates to true when the customer is blocked.
/// </summary>
internal static Func<Order?, bool> WhenBlocked() => order => order?.Customer?.IsBlocked == true;
/// <summary>
/// Returns a condition that evaluates to true when the customer is not blocked.
/// </summary>
internal static Func<Order?, bool> WhenNotBlocked() => order => order?.Customer?.IsBlocked == false;
}
dotnet/samples/Durable/Workflow/ConsoleApps/03_ConditionalEdges/Program.cs
+97
View File
@@ -0,0 +1,97 @@
// Copyright (c) Microsoft. All rights reserved.
// This sample demonstrates conditional edges in a workflow.
// Orders are routed to different executors based on customer status:
// - Blocked customers → NotifyFraud
// - Valid customers → PaymentProcessor
using ConditionalEdges;
using Microsoft.Agents.AI.DurableTask;
using Microsoft.Agents.AI.DurableTask.Workflows;
using Microsoft.Agents.AI.Workflows;
using Microsoft.DurableTask.Client.AzureManaged;
using Microsoft.DurableTask.Worker.AzureManaged;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
// Create executor instances
OrderIdParser orderParser = new();
OrderEnrich orderEnrich = new();
PaymentProcesser paymentProcessor = new();
NotifyFraud notifyFraud = new();
// Build workflow with conditional edges
// The condition functions evaluate the Order output from OrderEnrich
WorkflowBuilder builder = new(orderParser);
builder
.AddEdge(orderParser, orderEnrich)
.AddEdge(orderEnrich, notifyFraud, condition: OrderRouteConditions.WhenBlocked())
.AddEdge(orderEnrich, paymentProcessor, condition: OrderRouteConditions.WhenNotBlocked());
Workflow auditOrder = builder.WithName("AuditOrder").Build();
IHost host = Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
.ConfigureServices(services =>
{
services.ConfigureDurableWorkflows(
workflowOptions => workflowOptions.AddWorkflow(auditOrder),
workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
})
.Build();
await host.StartAsync();
IWorkflowClient workflowClient = host.Services.GetRequiredService<IWorkflowClient>();
Console.WriteLine("Enter an order ID (or 'exit'):");
Console.WriteLine("Tip: Order IDs containing 'B' are flagged as blocked customers.\n");
while (true)
{
Console.Write("> ");
string? input = Console.ReadLine();
if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
{
break;
}
try
{
await StartNewWorkflowAsync(input, auditOrder, workflowClient);
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
Console.WriteLine();
}
await host.StopAsync();
// Start a new workflow and wait for completion
static async Task StartNewWorkflowAsync(string orderId, Workflow workflow, IWorkflowClient client)
{
Console.WriteLine($"Starting workflow for order '{orderId}'...");
// Cast to IAwaitableWorkflowRun to access WaitForCompletionAsync
IAwaitableWorkflowRun run = (IAwaitableWorkflowRun)await client.RunAsync(workflow, orderId);
Console.WriteLine($"Run ID: {run.RunId}");
try
{
Console.WriteLine("Waiting for workflow to complete...");
string? result = await run.WaitForCompletionAsync<string>();
Console.WriteLine($"Workflow completed. {result}");
}
catch (InvalidOperationException ex)
{
Console.WriteLine($"Failed: {ex.Message}");
}
}
dotnet/samples/Durable/Workflow/ConsoleApps/03_ConditionalEdges/README.md
+92
View File
@@ -0,0 +1,92 @@
# Conditional Edges Workflow Sample
This sample demonstrates how to build a workflow with **conditional edges** that route execution to different paths based on runtime conditions. The workflow evaluates conditions on the output of an executor to determine which downstream executor to run.
## Key Concepts Demonstrated
- Building workflows with **conditional edges** using `AddEdge` with a `condition` parameter
- Defining reusable condition functions for routing logic
- Branching workflow execution based on data-driven decisions
- Using `ConfigureDurableWorkflows` to register workflows with dependency injection
## Overview
The sample implements an order audit workflow that routes orders differently based on whether the customer is blocked (flagged for fraud):
```
OrderIdParser --> OrderEnrich --[IsBlocked]--> NotifyFraud
|
+--[NotBlocked]--> PaymentProcessor
```
| Executor | Description |
|----------|-------------|
| OrderIdParser | Parses the order ID and retrieves order details |
| OrderEnrich | Enriches the order with customer information |
| PaymentProcessor | Processes payment for valid orders |
| NotifyFraud | Notifies the fraud team for blocked customers |
## How Conditional Edges Work
Conditional edges allow you to specify a condition function that determines whether the edge should be traversed:
```csharp
builder
.AddEdge(orderParser, orderEnrich)
.AddEdge(orderEnrich, notifyFraud, condition: OrderRouteConditions.WhenBlocked())
.AddEdge(orderEnrich, paymentProcessor, condition: OrderRouteConditions.WhenNotBlocked());
```
The condition functions receive the output of the source executor and return a boolean:
```csharp
internal static class OrderRouteConditions
{
// Routes to NotifyFraud when customer is blocked
internal static Func<Order?, bool> WhenBlocked() =>
order => order?.Customer?.IsBlocked == true;
// Routes to PaymentProcessor when customer is not blocked
internal static Func<Order?, bool> WhenNotBlocked() =>
order => order?.Customer?.IsBlocked == false;
}
```
### Routing Logic
In this sample, the routing is based on the order ID:
- Order IDs containing the letter **'B'** are associated with blocked customers ? routed to `NotifyFraud`
- All other order IDs are associated with valid customers ? routed to `PaymentProcessor`
## Environment Setup
See the [README.md](../README.md) file in the parent directory for information on configuring the environment, including how to install and run the Durable Task Scheduler.
## Running the Sample
```bash
cd dotnet/samples/Durable/Workflow/ConsoleApps/03_ConditionalEdges
dotnet run --framework net10.0
```
### Sample Output
**Valid order (routes to PaymentProcessor):**
```text
Enter an order ID (or 'exit'):
> 12345
Starting workflow for order '12345'...
Run ID: abc123...
Waiting for workflow to complete...
Workflow completed. {"Id":"12345","Amount":100.0,"Customer":{"Id":201,"Name":"Jerry","IsBlocked":false},"PaymentReferenceNumber":"a1b2"}
```
**Blocked order (routes to NotifyFraud):**
```text
Enter an order ID (or 'exit'):
> 12345B
Starting workflow for order '12345B'...
Run ID: def456...
Waiting for workflow to complete...
Workflow completed. Order 12345B flagged as fraudulent for customer George.
```
dotnet/samples/Durable/Workflow/ConsoleApps/04_WorkflowAndAgents/04_WorkflowAndAgents.csproj
+30
View File
@@ -0,0 +1,30 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net10.0</TargetFrameworks>
<OutputType>Exe</OutputType>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<AssemblyName>WorkflowConcurrency</AssemblyName>
<RootNamespace>WorkflowConcurrency</RootNamespace>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Azure.Identity" />
<PackageReference Include="Microsoft.DurableTask.Client.AzureManaged" />
<PackageReference Include="Microsoft.DurableTask.Worker.AzureManaged" />
<PackageReference Include="Microsoft.Extensions.Hosting" />
<PackageReference Include="Azure.AI.OpenAI" />
</ItemGroup>
<!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
<!--
<ItemGroup>
<PackageReference Include="Microsoft.Agents.AI.DurableTask" />
<PackageReference Include="Microsoft.Agents.AI.Workflows" />
</ItemGroup>
-->
<ItemGroup>
<ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
<ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
</ItemGroup>
</Project>
dotnet/samples/Durable/Workflow/ConsoleApps/04_WorkflowAndAgents/ParseQuestionExecutor.cs
+73
View File
@@ -0,0 +1,73 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI.Workflows;
namespace WorkflowConcurrency;
/// <summary>
/// Parses and validates the incoming question before sending to AI agents.
/// </summary>
internal sealed class ParseQuestionExecutor() : Executor<string, string>("ParseQuestion")
{
public override ValueTask<string> HandleAsync(
string message,
IWorkflowContext context,
CancellationToken cancellationToken = default)
{
Console.WriteLine();
Console.ForegroundColor = ConsoleColor.Magenta;
Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
Console.WriteLine("│ [ParseQuestion] Preparing question for AI agents...");
string formattedQuestion = message.Trim();
if (!formattedQuestion.EndsWith('?'))
{
formattedQuestion += "?";
}
Console.WriteLine($"│ [ParseQuestion] Question: \"{formattedQuestion}\"");
Console.WriteLine("│ [ParseQuestion] → Sending to experts...");
Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
Console.ResetColor();
return ValueTask.FromResult(formattedQuestion);
}
}
/// <summary>
/// Aggregates responses from multiple AI agents into a unified response.
/// This executor collects all expert opinions and synthesizes them.
/// </summary>
internal sealed class ResponseAggregatorExecutor() : Executor<string[], string>("ResponseAggregator")
{
public override ValueTask<string> HandleAsync(
string[] message,
IWorkflowContext context,
CancellationToken cancellationToken = default)
{
Console.WriteLine();
Console.ForegroundColor = ConsoleColor.Cyan;
Console.WriteLine("┌─────────────────────────────────────────────────────────────────┐");
Console.WriteLine($"│ [Aggregator] 📋 Received {message.Length} AI agent responses");
Console.WriteLine("│ [Aggregator] Combining into comprehensive answer...");
Console.WriteLine("│ [Aggregator] ✓ Aggregation complete!");
Console.WriteLine("└─────────────────────────────────────────────────────────────────┘");
Console.ResetColor();
string aggregatedResult = "═══════════════════════════════════════════════════════════════\n" +
" AI EXPERT PANEL RESPONSES\n" +
"═══════════════════════════════════════════════════════════════\n\n";
for (int i = 0; i < message.Length; i++)
{
string expertLabel = i == 0 ? "⚛️ PHYSICIST" : "🧪 CHEMIST";
aggregatedResult += $"{expertLabel}:\n{message[i]}\n\n";
}
aggregatedResult += "═══════════════════════════════════════════════════════════════\n" +
$"Summary: Received perspectives from {message.Length} AI experts.\n" +
"═══════════════════════════════════════════════════════════════";
return ValueTask.FromResult(aggregatedResult);
}
}
dotnet/samples/Durable/Workflow/ConsoleApps/04_WorkflowAndAgents/Program.cs
+133
View File
@@ -0,0 +1,133 @@
// Copyright (c) Microsoft. All rights reserved.
// This sample demonstrates the THREE ways to configure durable agents and workflows:
//
// 1. ConfigureDurableAgents() - For standalone agents only
// 2. ConfigureDurableWorkflows() - For workflows only
// 3. ConfigureDurableOptions() - For both agents AND workflows
//
// KEY: All methods can be called MULTIPLE times - configurations are ADDITIVE.
using Azure;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.DurableTask;
using Microsoft.Agents.AI.DurableTask.Workflows;
using Microsoft.Agents.AI.Workflows;
using Microsoft.DurableTask.Client.AzureManaged;
using Microsoft.DurableTask.Worker.AzureManaged;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using OpenAI.Chat;
using WorkflowConcurrency;
// Configuration
string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING")
?? "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None";
string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")
?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT is not set.");
string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
// Create AI agents
AzureOpenAIClient openAiClient = !string.IsNullOrEmpty(azureOpenAiKey)
? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
: new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
ChatClient chatClient = openAiClient.GetChatClient(deploymentName);
AIAgent biologist = chatClient.AsAIAgent("You are a biology expert. Explain concepts clearly in 2-3 sentences.", "Biologist");
AIAgent physicist = chatClient.AsAIAgent("You are a physics expert. Explain concepts clearly in 2-3 sentences.", "Physicist");
AIAgent chemist = chatClient.AsAIAgent("You are a chemistry expert. Explain concepts clearly in 2-3 sentences.", "Chemist");
// Create workflows
ParseQuestionExecutor questionParser = new();
ResponseAggregatorExecutor responseAggregator = new();
Workflow physicsWorkflow = new WorkflowBuilder(questionParser)
.WithName("PhysicsExpertReview")
.AddEdge(questionParser, physicist)
.Build();
Workflow expertTeamWorkflow = new WorkflowBuilder(questionParser)
.WithName("ExpertTeamReview")
.AddFanOutEdge(questionParser, [biologist, physicist])
.AddFanInEdge([biologist, physicist], responseAggregator)
.Build();
Workflow chemistryWorkflow = new WorkflowBuilder(questionParser)
.WithName("ChemistryExpertReview")
.AddEdge(questionParser, chemist)
.Build();
// Configure services - demonstrating all 3 methods (each can be called multiple times)
IHost host = Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
.ConfigureServices(services =>
{
// METHOD 1: ConfigureDurableAgents - for standalone agents only
services.ConfigureDurableAgents(
options => options.AddAIAgent(biologist),
workerBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString),
clientBuilder: builder => builder.UseDurableTaskScheduler(dtsConnectionString));
// METHOD 2: ConfigureDurableWorkflows - for workflows only
services.ConfigureDurableWorkflows(options => options.AddWorkflow(physicsWorkflow));
// METHOD 3: ConfigureDurableOptions - for both agents AND workflows
services.ConfigureDurableOptions(options =>
{
options.Agents.AddAIAgent(chemist);
options.Workflows.AddWorkflow(expertTeamWorkflow);
});
// Second call to ConfigureDurableOptions (additive - adds to existing config)
services.ConfigureDurableOptions(options => options.Workflows.AddWorkflow(chemistryWorkflow));
})
.Build();
await host.StartAsync();
IServiceProvider services = host.Services;
IWorkflowClient workflowClient = services.GetRequiredService<IWorkflowClient>();
// DEMO 1: Direct agent conversation (standalone agents)
Console.WriteLine("\n═══ DEMO 1: Direct Agent Conversation ═══\n");
AIAgent biologistProxy = services.GetRequiredKeyedService<AIAgent>("Biologist");
AgentSession session = await biologistProxy.GetNewSessionAsync();
AgentResponse response = await biologistProxy.RunAsync("What is photosynthesis?", session);
Console.WriteLine($"🧬 Biologist: {response.Text}\n");
AIAgent chemistProxy = services.GetRequiredKeyedService<AIAgent>("Chemist");
session = await chemistProxy.GetNewSessionAsync();
response = await chemistProxy.RunAsync("What is a chemical bond?", session);
Console.WriteLine($"🧪 Chemist: {response.Text}\n");
// DEMO 2: Single-agent workflow
Console.WriteLine("═══ DEMO 2: Single-Agent Workflow ═══\n");
await RunWorkflowAsync(workflowClient, physicsWorkflow, "What is the relationship between energy and mass?");
// DEMO 3: Multi-agent workflow
Console.WriteLine("═══ DEMO 3: Multi-Agent Workflow ═══\n");
await RunWorkflowAsync(workflowClient, expertTeamWorkflow, "How does radiation affect living cells?");
// DEMO 4: Workflow from second ConfigureDurableOptions call
Console.WriteLine("═══ DEMO 4: Workflow (added via 2nd ConfigureDurableOptions) ═══\n");
await RunWorkflowAsync(workflowClient, chemistryWorkflow, "What happens during combustion?");
Console.WriteLine("\n✅ All demos completed!");
await host.StopAsync();
// Helper method
static async Task RunWorkflowAsync(IWorkflowClient client, Workflow workflow, string question)
{
Console.WriteLine($"📋 {workflow.Name}: \"{question}\"");
IWorkflowRun run = await client.RunAsync(workflow, question);
if (run is IAwaitableWorkflowRun awaitable)
{
string? result = await awaitable.WaitForCompletionAsync<string>();
Console.WriteLine($"✅ {result}\n");
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAgentsOptions.cs
+11
View File
@@ -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);
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/DurableDataConverter.cs
+66
View File
@@ -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);
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/DurableOptions.cs
+31
View File
@@ -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; }
}
dotnet/src/Microsoft.Agents.AI.DurableTask/DurableServicesMarker.cs
+34
View File
@@ -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;
dotnet/src/Microsoft.Agents.AI.DurableTask/Logs.cs
+111
View File
@@ -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);
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj
+1
View File
@@ -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>
dotnet/src/Microsoft.Agents.AI.DurableTask/ServiceCollectionExtensions.cs
+292 -109
View File
@@ -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);
}
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableActivityContext.cs
+107
View File
@@ -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;
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableActivityExecutor.cs
+146
View File
@@ -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);
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableActivityInput.cs
+24
View File
@@ -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; } = [];
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableActivityOutput.cs
+19
View File
@@ -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; } = [];
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableExecutorDispatcher.cs
+99
View File
@@ -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;
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableMessageEnvelope.cs
+51
View File
@@ -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
};
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowClient.cs
+61
View File
@@ -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);
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowInput.cs
+16
View File
@@ -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; }
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowJsonContext.cs
+34
View File
@@ -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;
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowOptions.cs
+107
View File
@@ -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);
}
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowRun.cs
+116
View File
@@ -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);
}
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowRunner.cs
+440
View File
@@ -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;
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/EdgeRouters/DurableDirectEdgeRouter.cs
+156
View File
@@ -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 =&gt; order.Total &gt; 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);
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/EdgeRouters/DurableEdgeMap.cs
+205
View File
@@ -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);
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/EdgeRouters/DurableFanOutEdgeRouter.cs
+67
View File
@@ -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);
}
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/EdgeRouters/IDurableEdgeRouter.cs
+26
View File
@@ -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);
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/ExecutorRegistry.cs
+83
View File
@@ -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);
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/IAwaitableWorkflowRun.cs
+34
View File
@@ -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&lt;string&gt;();
/// }
/// </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);
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/IWorkflowClient.cs
+41
View File
@@ -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);
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/IWorkflowRun.cs
+39
View File
@@ -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; }
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/SentMessageInfo.cs
+21
View File
@@ -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; }
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/WorkflowAnalyzer.cs
+245
View File
@@ -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&lt;TInput, TOutput&gt;,
/// or <c>null</c> for Executor&lt;TInput&gt; (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&lt;TInput, TOutput&gt;; 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&lt;TInput&gt;).
/// </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);
}
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/WorkflowExecutorInfo.cs
+29
View File
@@ -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;
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/WorkflowGraphInfo.cs
+98
View File
@@ -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; } = [];
}
dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/WorkflowNamingHelper.cs
+83
View File
@@ -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;
}
}
dotnet/src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj
+1
View File
@@ -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>
dotnet/tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/ConsoleAppSamplesValidation.cs
+20 -396
View File
@@ -2,47 +2,32 @@
using System.Collections.Concurrent;
using System.Diagnostics;
using System.Reflection;
using System.Text;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
using Xunit.Abstractions;
namespace Microsoft.Agents.AI.DurableTask.IntegrationTests;
/// <summary>
/// Integration tests for validating the durable agent console app samples
/// located in samples/Durable/Agents/ConsoleApps.
/// </summary>
[Collection("Samples")]
[Trait("Category", "SampleValidation")]
public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper) : IAsyncLifetime
public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper) : SamplesValidationBase(outputHelper)
{
private const string DtsPort = "8080";
private const string RedisPort = "6379";
private static readonly string s_dotnetTargetFramework = GetTargetFramework();
private static readonly IConfiguration s_configuration =
new ConfigurationBuilder()
.AddUserSecrets(Assembly.GetExecutingAssembly())
.AddEnvironmentVariables()
.Build();
private static bool s_infrastructureStarted;
private static readonly string s_samplesPath = Path.GetFullPath(
Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "..", "..", "..", "..", "..", "samples", "Durable", "Agents", "ConsoleApps"));
private readonly ITestOutputHelper _outputHelper = outputHelper;
/// <inheritdoc />
protected override string SamplesPath => s_samplesPath;
async Task IAsyncLifetime.InitializeAsync()
{
if (!s_infrastructureStarted)
{
await this.StartSharedInfrastructureAsync();
s_infrastructureStarted = true;
}
}
/// <inheritdoc />
protected override bool RequiresRedis => true;
async Task IAsyncLifetime.DisposeAsync()
/// <inheritdoc />
protected override void ConfigureAdditionalEnvironmentVariables(ProcessStartInfo startInfo, Action<string, string> setEnvVar)
{
// Nothing to clean up
await Task.CompletedTask;
setEnvVar("REDIS_CONNECTION_STRING", $"localhost:{RedisPort}");
}
[Fact]
@@ -475,7 +460,7 @@ public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper)
// (streams can complete very quickly, so we need to interrupt early)
if (foundConversationStart && !interrupted && contentLinesBeforeInterrupt >= 2)
{
this._outputHelper.WriteLine($"Interrupting stream after {contentLinesBeforeInterrupt} content lines");
this.OutputHelper.WriteLine($"Interrupting stream after {contentLinesBeforeInterrupt} content lines");
interrupted = true;
interruptTime = DateTime.Now;
@@ -493,7 +478,7 @@ public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper)
foundLastCursor = true;
// Send Enter again to resume
this._outputHelper.WriteLine("Resuming stream from last cursor");
this.OutputHelper.WriteLine("Resuming stream from last cursor");
await this.WriteInputAsync(process, string.Empty, testTimeoutCts.Token);
resumed = true;
}
@@ -521,7 +506,7 @@ public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper)
if (timeSinceInterrupt < TimeSpan.FromSeconds(2))
{
// Continue reading for a bit more to catch the cancellation message
this._outputHelper.WriteLine("Stream completed naturally, but waiting for Last cursor message after interrupt...");
this.OutputHelper.WriteLine("Stream completed naturally, but waiting for Last cursor message after interrupt...");
continue;
}
}
@@ -536,7 +521,7 @@ public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper)
// Stop once we've verified the interrupt/resume flow works
if (resumed && foundResumeMessage && contentLinesAfterResume >= 5)
{
this._outputHelper.WriteLine($"Successfully verified interrupt/resume: {contentLinesBeforeInterrupt} lines before, {contentLinesAfterResume} lines after");
this.OutputHelper.WriteLine($"Successfully verified interrupt/resume: {contentLinesBeforeInterrupt} lines before, {contentLinesAfterResume} lines after");
break;
}
}
@@ -547,7 +532,7 @@ public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper)
TimeSpan timeSinceInterrupt = DateTime.Now - interruptTime.Value;
if (timeSinceInterrupt < TimeSpan.FromSeconds(3))
{
this._outputHelper.WriteLine("Waiting for Last cursor message after interrupt...");
this.OutputHelper.WriteLine("Waiting for Last cursor message after interrupt...");
using CancellationTokenSource waitCts = new(TimeSpan.FromSeconds(2));
try
{
@@ -558,7 +543,7 @@ public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper)
foundLastCursor = true;
if (!resumed)
{
this._outputHelper.WriteLine("Resuming stream from last cursor");
this.OutputHelper.WriteLine("Resuming stream from last cursor");
await this.WriteInputAsync(process, string.Empty, testTimeoutCts.Token);
resumed = true;
}
@@ -576,7 +561,7 @@ public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper)
catch (OperationCanceledException)
{
// Timeout - check if we got enough to verify the flow
this._outputHelper.WriteLine($"Read timeout reached. Interrupted: {interrupted}, Resumed: {resumed}, Content before: {contentLinesBeforeInterrupt}, Content after: {contentLinesAfterResume}");
this.OutputHelper.WriteLine($"Read timeout reached. Interrupted: {interrupted}, Resumed: {resumed}, Content before: {contentLinesBeforeInterrupt}, Content after: {contentLinesAfterResume}");
}
Assert.True(foundConversationStart, "Conversation start message not found.");
@@ -586,7 +571,7 @@ public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper)
// but we should still verify we got the conversation started
if (!interrupted)
{
this._outputHelper.WriteLine("WARNING: Stream completed before interrupt could be sent. This may indicate the stream is too fast.");
this.OutputHelper.WriteLine("WARNING: Stream completed before interrupt could be sent. This may indicate the stream is too fast.");
}
Assert.True(interrupted, "Stream was not interrupted (may have completed too quickly).");
@@ -596,365 +581,4 @@ public sealed class ConsoleAppSamplesValidation(ITestOutputHelper outputHelper)
Assert.True(contentLinesAfterResume > 0, "No content received after resume (expected to continue from cursor, not restart).");
});
}
private static string GetTargetFramework()
{
string filePath = new Uri(typeof(ConsoleAppSamplesValidation).Assembly.Location).LocalPath;
string directory = Path.GetDirectoryName(filePath)!;
string tfm = Path.GetFileName(directory);
if (tfm.StartsWith("net", StringComparison.OrdinalIgnoreCase))
{
return tfm;
}
throw new InvalidOperationException($"Unable to find target framework in path: {filePath}");
}
private async Task StartSharedInfrastructureAsync()
{
this._outputHelper.WriteLine("Starting shared infrastructure for console app samples...");
// Start DTS emulator
await this.StartDtsEmulatorAsync();
// Start Redis
await this.StartRedisAsync();
// Wait for infrastructure to be ready
await Task.Delay(TimeSpan.FromSeconds(5));
}
private async Task StartDtsEmulatorAsync()
{
// Start DTS emulator if it's not already running
if (!await this.IsDtsEmulatorRunningAsync())
{
this._outputHelper.WriteLine("Starting DTS emulator...");
await this.RunCommandAsync("docker", [
"run", "-d",
"--name", "dts-emulator",
"-p", $"{DtsPort}:8080",
"-e", "DTS_USE_DYNAMIC_TASK_HUBS=true",
"mcr.microsoft.com/dts/dts-emulator:latest"
]);
}
}
private async Task StartRedisAsync()
{
if (!await this.IsRedisRunningAsync())
{
this._outputHelper.WriteLine("Starting Redis...");
await this.RunCommandAsync("docker", [
"run", "-d",
"--name", "redis",
"-p", $"{RedisPort}:6379",
"redis:latest"
]);
}
}
private async Task<bool> IsDtsEmulatorRunningAsync()
{
this._outputHelper.WriteLine($"Checking if DTS emulator is running at http://localhost:{DtsPort}/healthz...");
// DTS emulator doesn't support HTTP/1.1, so we need to use HTTP/2.0
using HttpClient http2Client = new()
{
DefaultRequestVersion = new Version(2, 0),
DefaultVersionPolicy = HttpVersionPolicy.RequestVersionExact
};
try
{
using CancellationTokenSource timeoutCts = new(TimeSpan.FromSeconds(30));
using HttpResponseMessage response = await http2Client.GetAsync(new Uri($"http://localhost:{DtsPort}/healthz"), timeoutCts.Token);
if (response.Content.Headers.ContentLength > 0)
{
string content = await response.Content.ReadAsStringAsync(timeoutCts.Token);
this._outputHelper.WriteLine($"DTS emulator health check response: {content}");
}
if (response.IsSuccessStatusCode)
{
this._outputHelper.WriteLine("DTS emulator is running");
return true;
}
this._outputHelper.WriteLine($"DTS emulator is not running. Status code: {response.StatusCode}");
return false;
}
catch (HttpRequestException ex)
{
this._outputHelper.WriteLine($"DTS emulator is not running: {ex.Message}");
return false;
}
}
private async Task<bool> IsRedisRunningAsync()
{
this._outputHelper.WriteLine($"Checking if Redis is running at localhost:{RedisPort}...");
try
{
using CancellationTokenSource timeoutCts = new(TimeSpan.FromSeconds(30));
ProcessStartInfo startInfo = new()
{
FileName = "docker",
Arguments = "exec redis redis-cli ping",
UseShellExecute = false,
RedirectStandardOutput = true,
RedirectStandardError = true,
CreateNoWindow = true
};
using Process process = new() { StartInfo = startInfo };
if (!process.Start())
{
this._outputHelper.WriteLine("Failed to start docker exec command");
return false;
}
string output = await process.StandardOutput.ReadToEndAsync(timeoutCts.Token);
await process.WaitForExitAsync(timeoutCts.Token);
if (process.ExitCode == 0 && output.Contains("PONG", StringComparison.OrdinalIgnoreCase))
{
this._outputHelper.WriteLine("Redis is running");
return true;
}
this._outputHelper.WriteLine($"Redis is not running. Exit code: {process.ExitCode}, Output: {output}");
return false;
}
catch (Exception ex)
{
this._outputHelper.WriteLine($"Redis is not running: {ex.Message}");
return false;
}
}
private async Task RunSampleTestAsync(string samplePath, Func<Process, BlockingCollection<OutputLog>, Task> testAction)
{
// Generate a unique TaskHub name for this sample test to prevent cross-test interference
// when multiple tests run together and share the same DTS emulator.
string uniqueTaskHubName = $"sample-{Guid.NewGuid().ToString("N").Substring(0, 6)}";
// Start the console app
// Use BlockingCollection to safely read logs asynchronously captured from the process
using BlockingCollection<OutputLog> logsContainer = [];
using Process appProcess = this.StartConsoleApp(samplePath, logsContainer, uniqueTaskHubName);
try
{
// Run the test
await testAction(appProcess, logsContainer);
}
catch (OperationCanceledException e)
{
throw new TimeoutException("Core test logic timed out!", e);
}
finally
{
logsContainer.CompleteAdding();
await this.StopProcessAsync(appProcess);
}
}
private sealed record OutputLog(DateTime Timestamp, LogLevel Level, string Message);
/// <summary>
/// Writes a line to the process's stdin and flushes it.
/// Logs the input being sent for debugging purposes.
/// </summary>
private async Task WriteInputAsync(Process process, string input, CancellationToken cancellationToken)
{
this._outputHelper.WriteLine($"{DateTime.Now:HH:mm:ss.fff} [{process.ProcessName}(in)]: {input}");
await process.StandardInput.WriteLineAsync(input);
await process.StandardInput.FlushAsync(cancellationToken);
}
/// <summary>
/// Reads a line from the logs queue, filtering for Information level logs (stdout).
/// Returns null if the collection is completed and empty, or if cancellation is requested.
/// </summary>
private string? ReadLogLine(BlockingCollection<OutputLog> logs, CancellationToken cancellationToken)
{
try
{
while (!cancellationToken.IsCancellationRequested)
{
// Block until a log entry is available or cancellation is requested
// Take will throw OperationCanceledException if cancelled, or InvalidOperationException if collection is completed
OutputLog log = logs.Take(cancellationToken);
// Check for unhandled exceptions in the logs, which are never expected (but can happen)
if (log.Message.Contains("Unhandled exception"))
{
Assert.Fail("Console app encountered an unhandled exception.");
}
// Only return Information level logs (stdout), skip Error logs (stderr)
if (log.Level == LogLevel.Information)
{
return log.Message;
}
}
}
catch (OperationCanceledException)
{
// Cancellation requested
return null;
}
catch (InvalidOperationException)
{
// Collection is completed and empty
return null;
}
return null;
}
private Process StartConsoleApp(string samplePath, BlockingCollection<OutputLog> logs, string taskHubName)
{
ProcessStartInfo startInfo = new()
{
FileName = "dotnet",
Arguments = $"run --framework {s_dotnetTargetFramework}",
WorkingDirectory = samplePath,
UseShellExecute = false,
RedirectStandardOutput = true,
RedirectStandardError = true,
RedirectStandardInput = true,
};
string openAiEndpoint = s_configuration["AZURE_OPENAI_ENDPOINT"] ??
throw new InvalidOperationException("The required AZURE_OPENAI_ENDPOINT env variable is not set.");
string openAiDeployment = s_configuration["AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"] ??
throw new InvalidOperationException("The required AZURE_OPENAI_CHAT_DEPLOYMENT_NAME env variable is not set.");
void SetAndLogEnvironmentVariable(string key, string value)
{
this._outputHelper.WriteLine($"Setting environment variable for {startInfo.FileName} sub-process: {key}={value}");
startInfo.EnvironmentVariables[key] = value;
}
// Set required environment variables for the app
SetAndLogEnvironmentVariable("AZURE_OPENAI_ENDPOINT", openAiEndpoint);
SetAndLogEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT", openAiDeployment);
SetAndLogEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING",
$"Endpoint=http://localhost:{DtsPort};TaskHub={taskHubName};Authentication=None");
SetAndLogEnvironmentVariable("REDIS_CONNECTION_STRING", $"localhost:{RedisPort}");
Process process = new() { StartInfo = startInfo };
// Capture the output and error streams asynchronously
// These events fire asynchronously, so we add to the blocking collection which is thread-safe
process.ErrorDataReceived += (sender, e) =>
{
if (e.Data != null)
{
string logMessage = $"{DateTime.Now:HH:mm:ss.fff} [{startInfo.FileName}(err)]: {e.Data}";
this._outputHelper.WriteLine(logMessage);
Debug.WriteLine(logMessage);
try
{
logs.Add(new OutputLog(DateTime.Now, LogLevel.Error, e.Data));
}
catch (InvalidOperationException)
{
// Collection is completed, ignore
}
}
};
process.OutputDataReceived += (sender, e) =>
{
if (e.Data != null)
{
string logMessage = $"{DateTime.Now:HH:mm:ss.fff} [{startInfo.FileName}(out)]: {e.Data}";
this._outputHelper.WriteLine(logMessage);
Debug.WriteLine(logMessage);
try
{
logs.Add(new OutputLog(DateTime.Now, LogLevel.Information, e.Data));
}
catch (InvalidOperationException)
{
// Collection is completed, ignore
}
}
};
if (!process.Start())
{
throw new InvalidOperationException("Failed to start the console app");
}
process.BeginErrorReadLine();
process.BeginOutputReadLine();
return process;
}
private async Task RunCommandAsync(string command, string[] args)
{
await this.RunCommandAsync(command, workingDirectory: null, args: args);
}
private async Task RunCommandAsync(string command, string? workingDirectory, string[] args)
{
ProcessStartInfo startInfo = new()
{
FileName = command,
Arguments = string.Join(" ", args),
WorkingDirectory = workingDirectory,
UseShellExecute = false,
RedirectStandardOutput = true,
RedirectStandardError = true,
CreateNoWindow = true
};
this._outputHelper.WriteLine($"Running command: {command} {string.Join(" ", args)}");
using Process process = new() { StartInfo = startInfo };
process.ErrorDataReceived += (sender, e) => this._outputHelper.WriteLine($"[{command}(err)]: {e.Data}");
process.OutputDataReceived += (sender, e) => this._outputHelper.WriteLine($"[{command}(out)]: {e.Data}");
if (!process.Start())
{
throw new InvalidOperationException("Failed to start the command");
}
process.BeginErrorReadLine();
process.BeginOutputReadLine();
using CancellationTokenSource cancellationTokenSource = new(TimeSpan.FromMinutes(1));
await process.WaitForExitAsync(cancellationTokenSource.Token);
this._outputHelper.WriteLine($"Command completed with exit code: {process.ExitCode}");
}
private async Task StopProcessAsync(Process process)
{
try
{
if (!process.HasExited)
{
this._outputHelper.WriteLine($"{DateTime.Now:HH:mm:ss.fff} Killing process {process.ProcessName}#{process.Id}");
process.Kill(entireProcessTree: true);
using CancellationTokenSource timeoutCts = new(TimeSpan.FromSeconds(10));
await process.WaitForExitAsync(timeoutCts.Token);
this._outputHelper.WriteLine($"{DateTime.Now:HH:mm:ss.fff} Process exited: {process.Id}");
}
}
catch (Exception ex)
{
this._outputHelper.WriteLine($"{DateTime.Now:HH:mm:ss.fff} Failed to stop process: {ex.Message}");
}
}
private CancellationTokenSource CreateTestTimeoutCts(TimeSpan? timeout = null)
{
TimeSpan testTimeout = Debugger.IsAttached ? TimeSpan.FromMinutes(5) : timeout ?? TimeSpan.FromSeconds(60);
return new CancellationTokenSource(testTimeout);
}
}
dotnet/tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/SamplesValidationBase.cs
+449
View File
@@ -0,0 +1,449 @@
// Copyright (c) Microsoft. All rights reserved.
using System.Collections.Concurrent;
using System.Diagnostics;
using System.Reflection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
using Xunit.Abstractions;
namespace Microsoft.Agents.AI.DurableTask.IntegrationTests;
/// <summary>
/// Base class for sample validation integration tests providing shared infrastructure
/// setup and utility methods for running console app samples.
/// </summary>
public abstract class SamplesValidationBase : IAsyncLifetime
{
protected const string DtsPort = "8080";
protected const string RedisPort = "6379";
protected static readonly string DotnetTargetFramework = GetTargetFramework();
protected static readonly IConfiguration Configuration =
new ConfigurationBuilder()
.AddUserSecrets(Assembly.GetExecutingAssembly())
.AddEnvironmentVariables()
.Build();
// Semaphores for thread-safe initialization of shared infrastructure.
// xUnit may run tests in parallel, so we need to ensure that DTS emulator and Redis
// are started only once across all test instances. Using SemaphoreSlim allows async-safe
// locking, and the double-check pattern (check flag, acquire lock, check flag again)
// minimizes lock contention after initialization is complete.
private static readonly SemaphoreSlim s_dtsInitLock = new(1, 1);
private static readonly SemaphoreSlim s_redisInitLock = new(1, 1);
private static bool s_dtsInfrastructureStarted;
private static bool s_redisInfrastructureStarted;
protected SamplesValidationBase(ITestOutputHelper outputHelper)
{
this.OutputHelper = outputHelper;
}
/// <summary>
/// Gets the test output helper for logging.
/// </summary>
protected ITestOutputHelper OutputHelper { get; }
/// <summary>
/// Gets the base path to the samples directory for this test class.
/// </summary>
protected abstract string SamplesPath { get; }
/// <summary>
/// Gets whether this test class requires Redis infrastructure.
/// </summary>
protected virtual bool RequiresRedis => false;
/// <summary>
/// Gets the task hub name prefix for this test class.
/// </summary>
protected virtual string TaskHubPrefix => "sample";
/// <inheritdoc />
public async Task InitializeAsync()
{
await EnsureDtsInfrastructureStartedAsync(this.OutputHelper, this.StartDtsEmulatorAsync);
if (this.RequiresRedis)
{
await EnsureRedisInfrastructureStartedAsync(this.OutputHelper, this.StartRedisAsync);
}
await Task.Delay(TimeSpan.FromSeconds(5));
}
/// <summary>
/// Ensures DTS infrastructure is started exactly once across all test instances.
/// Static method writes to static field to avoid the code smell of instance methods modifying shared state.
/// </summary>
private static async Task EnsureDtsInfrastructureStartedAsync(ITestOutputHelper outputHelper, Func<Task> startAction)
{
if (s_dtsInfrastructureStarted)
{
return;
}
await s_dtsInitLock.WaitAsync();
try
{
if (!s_dtsInfrastructureStarted)
{
outputHelper.WriteLine("Starting shared DTS infrastructure...");
await startAction();
s_dtsInfrastructureStarted = true;
}
}
finally
{
s_dtsInitLock.Release();
}
}
/// <summary>
/// Ensures Redis infrastructure is started exactly once across all test instances.
/// Static method writes to static field to avoid the code smell of instance methods modifying shared state.
/// </summary>
private static async Task EnsureRedisInfrastructureStartedAsync(ITestOutputHelper outputHelper, Func<Task> startAction)
{
if (s_redisInfrastructureStarted)
{
return;
}
await s_redisInitLock.WaitAsync();
try
{
if (!s_redisInfrastructureStarted)
{
outputHelper.WriteLine("Starting shared Redis infrastructure...");
await startAction();
s_redisInfrastructureStarted = true;
}
}
finally
{
s_redisInitLock.Release();
}
}
/// <inheritdoc />
public Task DisposeAsync() => Task.CompletedTask;
protected sealed record OutputLog(DateTime Timestamp, LogLevel Level, string Message);
/// <summary>
/// Runs a sample test by starting the console app and executing the provided test action.
/// </summary>
protected async Task RunSampleTestAsync(string samplePath, Func<Process, BlockingCollection<OutputLog>, Task> testAction)
{
string uniqueTaskHubName = $"{this.TaskHubPrefix}-{Guid.NewGuid():N}"[..^26];
using BlockingCollection<OutputLog> logsContainer = [];
using Process appProcess = this.StartConsoleApp(samplePath, logsContainer, uniqueTaskHubName);
try
{
await testAction(appProcess, logsContainer);
}
catch (OperationCanceledException e)
{
throw new TimeoutException("Core test logic timed out!", e);
}
finally
{
logsContainer.CompleteAdding();
await this.StopProcessAsync(appProcess);
}
}
/// <summary>
/// Writes a line to the process's stdin and flushes it.
/// </summary>
protected async Task WriteInputAsync(Process process, string input, CancellationToken cancellationToken)
{
this.OutputHelper.WriteLine($"{DateTime.Now:HH:mm:ss.fff} [{process.ProcessName}(in)]: {input}");
await process.StandardInput.WriteLineAsync(input);
await process.StandardInput.FlushAsync(cancellationToken);
}
/// <summary>
/// Reads the next Information-level log line from the queue.
/// Returns null if cancelled or collection is completed.
/// </summary>
protected string? ReadLogLine(BlockingCollection<OutputLog> logs, CancellationToken cancellationToken)
{
try
{
while (!cancellationToken.IsCancellationRequested)
{
OutputLog log = logs.Take(cancellationToken);
if (log.Message.Contains("Unhandled exception"))
{
Assert.Fail("Console app encountered an unhandled exception.");
}
if (log.Level == LogLevel.Information)
{
return log.Message;
}
}
}
catch (OperationCanceledException)
{
return null;
}
catch (InvalidOperationException)
{
return null;
}
return null;
}
/// <summary>
/// Creates a cancellation token source with the specified timeout for test operations.
/// </summary>
protected CancellationTokenSource CreateTestTimeoutCts(TimeSpan? timeout = null)
{
TimeSpan testTimeout = Debugger.IsAttached ? TimeSpan.FromMinutes(5) : timeout ?? TimeSpan.FromSeconds(60);
return new CancellationTokenSource(testTimeout);
}
/// <summary>
/// Allows derived classes to set additional environment variables for the console app process.
/// </summary>
protected virtual void ConfigureAdditionalEnvironmentVariables(ProcessStartInfo startInfo, Action<string, string> setEnvVar)
{
}
private static string GetTargetFramework()
{
string filePath = new Uri(typeof(SamplesValidationBase).Assembly.Location).LocalPath;
string directory = Path.GetDirectoryName(filePath)!;
string tfm = Path.GetFileName(directory);
if (tfm.StartsWith("net", StringComparison.OrdinalIgnoreCase))
{
return tfm;
}
throw new InvalidOperationException($"Unable to find target framework in path: {filePath}");
}
private async Task StartDtsEmulatorAsync()
{
if (!await this.IsDtsEmulatorRunningAsync())
{
this.OutputHelper.WriteLine("Starting DTS emulator...");
await this.RunCommandAsync("docker", "run", "-d",
"--name", "dts-emulator",
"-p", $"{DtsPort}:8080",
"-e", "DTS_USE_DYNAMIC_TASK_HUBS=true",
"mcr.microsoft.com/dts/dts-emulator:latest");
}
}
private async Task StartRedisAsync()
{
if (!await this.IsRedisRunningAsync())
{
this.OutputHelper.WriteLine("Starting Redis...");
await this.RunCommandAsync("docker", "run", "-d",
"--name", "redis",
"-p", $"{RedisPort}:6379",
"redis:latest");
}
}
private async Task<bool> IsDtsEmulatorRunningAsync()
{
this.OutputHelper.WriteLine($"Checking if DTS emulator is running at http://localhost:{DtsPort}/healthz...");
using HttpClient http2Client = new()
{
DefaultRequestVersion = new Version(2, 0),
DefaultVersionPolicy = HttpVersionPolicy.RequestVersionExact
};
try
{
using CancellationTokenSource timeoutCts = new(TimeSpan.FromSeconds(30));
using HttpResponseMessage response = await http2Client.GetAsync(
new Uri($"http://localhost:{DtsPort}/healthz"), timeoutCts.Token);
if (response.Content.Headers.ContentLength > 0)
{
string content = await response.Content.ReadAsStringAsync(timeoutCts.Token);
this.OutputHelper.WriteLine($"DTS emulator health check response: {content}");
}
bool isRunning = response.IsSuccessStatusCode;
this.OutputHelper.WriteLine(isRunning ? "DTS emulator is running" : $"DTS emulator not running. Status: {response.StatusCode}");
return isRunning;
}
catch (HttpRequestException ex)
{
this.OutputHelper.WriteLine($"DTS emulator is not running: {ex.Message}");
return false;
}
}
private async Task<bool> IsRedisRunningAsync()
{
this.OutputHelper.WriteLine($"Checking if Redis is running at localhost:{RedisPort}...");
try
{
using CancellationTokenSource timeoutCts = new(TimeSpan.FromSeconds(30));
ProcessStartInfo startInfo = new()
{
FileName = "docker",
Arguments = "exec redis redis-cli ping",
UseShellExecute = false,
RedirectStandardOutput = true,
RedirectStandardError = true,
CreateNoWindow = true
};
using Process process = new() { StartInfo = startInfo };
if (!process.Start())
{
this.OutputHelper.WriteLine("Failed to start docker exec command");
return false;
}
string output = await process.StandardOutput.ReadToEndAsync(timeoutCts.Token);
await process.WaitForExitAsync(timeoutCts.Token);
bool isRunning = process.ExitCode == 0 && output.Contains("PONG", StringComparison.OrdinalIgnoreCase);
this.OutputHelper.WriteLine(isRunning ? "Redis is running" : $"Redis not running. Exit: {process.ExitCode}, Output: {output}");
return isRunning;
}
catch (Exception ex)
{
this.OutputHelper.WriteLine($"Redis is not running: {ex.Message}");
return false;
}
}
private Process StartConsoleApp(string samplePath, BlockingCollection<OutputLog> logs, string taskHubName)
{
ProcessStartInfo startInfo = new()
{
FileName = "dotnet",
Arguments = $"run --framework {DotnetTargetFramework}",
WorkingDirectory = samplePath,
UseShellExecute = false,
RedirectStandardOutput = true,
RedirectStandardError = true,
RedirectStandardInput = true,
};
string openAiEndpoint = Configuration["AZURE_OPENAI_ENDPOINT"] ??
throw new InvalidOperationException("The required AZURE_OPENAI_ENDPOINT env variable is not set.");
string openAiDeployment = Configuration["AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"] ??
throw new InvalidOperationException("The required AZURE_OPENAI_CHAT_DEPLOYMENT_NAME env variable is not set.");
void SetAndLogEnvironmentVariable(string key, string value)
{
this.OutputHelper.WriteLine($"Setting environment variable for {startInfo.FileName} sub-process: {key}={value}");
startInfo.EnvironmentVariables[key] = value;
}
SetAndLogEnvironmentVariable("AZURE_OPENAI_ENDPOINT", openAiEndpoint);
SetAndLogEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT", openAiDeployment);
SetAndLogEnvironmentVariable("DURABLE_TASK_SCHEDULER_CONNECTION_STRING",
$"Endpoint=http://localhost:{DtsPort};TaskHub={taskHubName};Authentication=None");
this.ConfigureAdditionalEnvironmentVariables(startInfo, SetAndLogEnvironmentVariable);
Process process = new() { StartInfo = startInfo };
process.ErrorDataReceived += (sender, e) => this.HandleProcessOutput(e.Data, startInfo.FileName, "err", LogLevel.Error, logs);
process.OutputDataReceived += (sender, e) => this.HandleProcessOutput(e.Data, startInfo.FileName, "out", LogLevel.Information, logs);
if (!process.Start())
{
throw new InvalidOperationException("Failed to start the console app");
}
process.BeginErrorReadLine();
process.BeginOutputReadLine();
return process;
}
private void HandleProcessOutput(string? data, string processName, string stream, LogLevel level, BlockingCollection<OutputLog> logs)
{
if (data is null)
{
return;
}
string logMessage = $"{DateTime.Now:HH:mm:ss.fff} [{processName}({stream})]: {data}";
this.OutputHelper.WriteLine(logMessage);
Debug.WriteLine(logMessage);
try
{
logs.Add(new OutputLog(DateTime.Now, level, data));
}
catch (InvalidOperationException)
{
// Collection completed
}
}
private async Task RunCommandAsync(string command, params string[] args)
{
ProcessStartInfo startInfo = new()
{
FileName = command,
Arguments = string.Join(" ", args),
UseShellExecute = false,
RedirectStandardOutput = true,
RedirectStandardError = true,
CreateNoWindow = true
};
this.OutputHelper.WriteLine($"Running command: {command} {string.Join(" ", args)}");
using Process process = new() { StartInfo = startInfo };
process.ErrorDataReceived += (sender, e) => this.OutputHelper.WriteLine($"[{command}(err)]: {e.Data}");
process.OutputDataReceived += (sender, e) => this.OutputHelper.WriteLine($"[{command}(out)]: {e.Data}");
if (!process.Start())
{
throw new InvalidOperationException("Failed to start the command");
}
process.BeginErrorReadLine();
process.BeginOutputReadLine();
using CancellationTokenSource cts = new(TimeSpan.FromMinutes(1));
await process.WaitForExitAsync(cts.Token);
this.OutputHelper.WriteLine($"Command completed with exit code: {process.ExitCode}");
}
private async Task StopProcessAsync(Process process)
{
try
{
if (!process.HasExited)
{
this.OutputHelper.WriteLine($"{DateTime.Now:HH:mm:ss.fff} Killing process {process.ProcessName}#{process.Id}");
process.Kill(entireProcessTree: true);
using CancellationTokenSource cts = new(TimeSpan.FromSeconds(10));
await process.WaitForExitAsync(cts.Token);
this.OutputHelper.WriteLine($"{DateTime.Now:HH:mm:ss.fff} Process exited: {process.Id}");
}
}
catch (Exception ex)
{
this.OutputHelper.WriteLine($"{DateTime.Now:HH:mm:ss.fff} Failed to stop process: {ex.Message}");
}
}
}
dotnet/tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/WorkflowConsoleAppSamplesValidation.cs
+242
View File
@@ -0,0 +1,242 @@
// Copyright (c) Microsoft. All rights reserved.
using Xunit.Abstractions;
namespace Microsoft.Agents.AI.DurableTask.IntegrationTests;
/// <summary>
/// Integration tests for validating the durable workflow console app samples
/// located in samples/Durable/Workflow/ConsoleApps.
/// </summary>
[Collection("Samples")]
[Trait("Category", "SampleValidation")]
public sealed class WorkflowConsoleAppSamplesValidation(ITestOutputHelper outputHelper) : SamplesValidationBase(outputHelper)
{
private static readonly string s_samplesPath = Path.GetFullPath(
Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "..", "..", "..", "..", "..", "samples", "Durable", "Workflow", "ConsoleApps"));
/// <inheritdoc />
protected override string SamplesPath => s_samplesPath;
/// <inheritdoc />
protected override string TaskHubPrefix => "workflow";
[Fact]
public async Task SequentialWorkflowSampleValidationAsync()
{
using CancellationTokenSource testTimeoutCts = this.CreateTestTimeoutCts();
string samplePath = Path.Combine(s_samplesPath, "01_SequentialWorkflow");
await this.RunSampleTestAsync(samplePath, async (process, logs) =>
{
bool inputSent = false;
bool workflowCompleted = false;
bool foundOrderLookup = false;
bool foundOrderCancel = false;
bool foundSendEmail = false;
string? line;
while ((line = this.ReadLogLine(logs, testTimeoutCts.Token)) != null)
{
if (!inputSent && line.Contains("Enter an order ID", StringComparison.OrdinalIgnoreCase))
{
await this.WriteInputAsync(process, "12345", testTimeoutCts.Token);
inputSent = true;
}
if (inputSent)
{
foundOrderLookup |= line.Contains("[Activity] OrderLookup:", StringComparison.Ordinal);
foundOrderCancel |= line.Contains("[Activity] OrderCancel:", StringComparison.Ordinal);
foundSendEmail |= line.Contains("[Activity] SendEmail:", StringComparison.Ordinal);
if (line.Contains("Workflow completed. Cancellation email sent for order 12345", StringComparison.OrdinalIgnoreCase))
{
workflowCompleted = true;
break;
}
}
this.AssertNoError(line);
}
Assert.True(inputSent, "Input was not sent to the workflow.");
Assert.True(foundOrderLookup, "OrderLookup executor log entry not found.");
Assert.True(foundOrderCancel, "OrderCancel executor log entry not found.");
Assert.True(foundSendEmail, "SendEmail executor log entry not found.");
Assert.True(workflowCompleted, "Workflow did not complete successfully.");
await this.WriteInputAsync(process, "exit", testTimeoutCts.Token);
});
}
[Fact]
public async Task ConcurrentWorkflowSampleValidationAsync()
{
using CancellationTokenSource testTimeoutCts = this.CreateTestTimeoutCts();
string samplePath = Path.Combine(s_samplesPath, "02_ConcurrentWorkflow");
await this.RunSampleTestAsync(samplePath, async (process, logs) =>
{
bool inputSent = false;
bool workflowCompleted = false;
bool foundParseQuestion = false;
bool foundAggregator = false;
bool foundAggregatorReceived2Responses = false;
string? line;
while ((line = this.ReadLogLine(logs, testTimeoutCts.Token)) != null)
{
if (!inputSent && line.Contains("Enter a science question", StringComparison.OrdinalIgnoreCase))
{
await this.WriteInputAsync(process, "What is gravity?", testTimeoutCts.Token);
inputSent = true;
}
if (inputSent)
{
foundParseQuestion |= line.Contains("[ParseQuestion]", StringComparison.Ordinal);
foundAggregator |= line.Contains("[Aggregator]", StringComparison.Ordinal);
foundAggregatorReceived2Responses |= line.Contains("Received 2 AI agent responses", StringComparison.Ordinal);
if (line.Contains("Aggregation complete", StringComparison.OrdinalIgnoreCase))
{
workflowCompleted = true;
break;
}
}
this.AssertNoError(line);
}
Assert.True(inputSent, "Input was not sent to the workflow.");
Assert.True(foundParseQuestion, "ParseQuestion executor log entry not found.");
Assert.True(foundAggregator, "Aggregator executor log entry not found.");
Assert.True(foundAggregatorReceived2Responses, "Aggregator did not receive 2 AI agent responses.");
Assert.True(workflowCompleted, "Workflow did not complete successfully.");
await this.WriteInputAsync(process, "exit", testTimeoutCts.Token);
});
}
[Fact]
public async Task ConditionalEdgesWorkflowSampleValidationAsync()
{
using CancellationTokenSource testTimeoutCts = this.CreateTestTimeoutCts();
string samplePath = Path.Combine(s_samplesPath, "03_ConditionalEdges");
await this.RunSampleTestAsync(samplePath, async (process, logs) =>
{
bool validOrderSent = false;
bool blockedOrderSent = false;
bool validOrderCompleted = false;
bool blockedOrderCompleted = false;
string? line;
while ((line = this.ReadLogLine(logs, testTimeoutCts.Token)) != null)
{
// Send a valid order first (no 'B' in ID)
if (!validOrderSent && line.Contains("Enter an order ID", StringComparison.OrdinalIgnoreCase))
{
await this.WriteInputAsync(process, "12345", testTimeoutCts.Token);
validOrderSent = true;
}
// Check valid order completed (routed to PaymentProcessor)
if (validOrderSent && !validOrderCompleted &&
line.Contains("PaymentReferenceNumber", StringComparison.OrdinalIgnoreCase))
{
validOrderCompleted = true;
// Send a blocked order (contains 'B')
await this.WriteInputAsync(process, "ORDER-B-999", testTimeoutCts.Token);
blockedOrderSent = true;
}
// Check blocked order completed (routed to NotifyFraud)
if (blockedOrderSent && line.Contains("flagged as fraudulent", StringComparison.OrdinalIgnoreCase))
{
blockedOrderCompleted = true;
break;
}
this.AssertNoError(line);
}
Assert.True(validOrderSent, "Valid order input was not sent.");
Assert.True(validOrderCompleted, "Valid order did not complete (PaymentProcessor path).");
Assert.True(blockedOrderSent, "Blocked order input was not sent.");
Assert.True(blockedOrderCompleted, "Blocked order did not complete (NotifyFraud path).");
await this.WriteInputAsync(process, "exit", testTimeoutCts.Token);
});
}
private void AssertNoError(string line)
{
if (line.Contains("Failed:", StringComparison.OrdinalIgnoreCase) ||
line.Contains("Error:", StringComparison.OrdinalIgnoreCase))
{
Assert.Fail($"Workflow failed: {line}");
}
}
[Fact]
public async Task WorkflowAndAgentsSampleValidationAsync()
{
using CancellationTokenSource testTimeoutCts = this.CreateTestTimeoutCts();
string samplePath = Path.Combine(s_samplesPath, "04_WorkflowAndAgents");
await this.RunSampleTestAsync(samplePath, (process, logs) =>
{
// Arrange
bool foundDemo1 = false;
bool foundBiologistResponse = false;
bool foundChemistResponse = false;
bool foundDemo2 = false;
bool foundPhysicsWorkflow = false;
bool foundDemo3 = false;
bool foundExpertTeamWorkflow = false;
bool foundDemo4 = false;
bool foundChemistryWorkflow = false;
bool allDemosCompleted = false;
// Act
string? line;
while ((line = this.ReadLogLine(logs, testTimeoutCts.Token)) != null)
{
foundDemo1 |= line.Contains("DEMO 1:", StringComparison.Ordinal);
foundBiologistResponse |= line.Contains("Biologist:", StringComparison.Ordinal);
foundChemistResponse |= line.Contains("Chemist:", StringComparison.Ordinal);
foundDemo2 |= line.Contains("DEMO 2:", StringComparison.Ordinal);
foundPhysicsWorkflow |= line.Contains("PhysicsExpertReview", StringComparison.Ordinal);
foundDemo3 |= line.Contains("DEMO 3:", StringComparison.Ordinal);
foundExpertTeamWorkflow |= line.Contains("ExpertTeamReview", StringComparison.Ordinal);
foundDemo4 |= line.Contains("DEMO 4:", StringComparison.Ordinal);
foundChemistryWorkflow |= line.Contains("ChemistryExpertReview", StringComparison.Ordinal);
if (line.Contains("All demos completed", StringComparison.OrdinalIgnoreCase))
{
allDemosCompleted = true;
break;
}
this.AssertNoError(line);
}
// Assert
Assert.True(foundDemo1, "DEMO 1 (Direct Agent Conversation) not found.");
Assert.True(foundBiologistResponse, "Biologist agent response not found.");
Assert.True(foundChemistResponse, "Chemist agent response not found.");
Assert.True(foundDemo2, "DEMO 2 (Single-Agent Workflow) not found.");
Assert.True(foundPhysicsWorkflow, "PhysicsExpertReview workflow not found.");
Assert.True(foundDemo3, "DEMO 3 (Multi-Agent Workflow) not found.");
Assert.True(foundExpertTeamWorkflow, "ExpertTeamReview workflow not found.");
Assert.True(foundDemo4, "DEMO 4 (Chemistry Workflow) not found.");
Assert.True(foundChemistryWorkflow, "ChemistryExpertReview workflow not found.");
Assert.True(allDemosCompleted, "Sample did not complete all demos successfully.");
return Task.CompletedTask;
});
}
}
dotnet/tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj
+1
View File
@@ -8,6 +8,7 @@
<ItemGroup>
<ProjectReference Include="..\..\src\Microsoft.Agents.AI.DurableTask\Microsoft.Agents.AI.DurableTask.csproj" />
<ProjectReference Include="..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
</ItemGroup>
</Project>
dotnet/tests/Microsoft.Agents.AI.DurableTask.UnitTests/Workflows/WorkflowNamingHelperTests.cs
+74
View File
@@ -0,0 +1,74 @@
// Copyright (c) Microsoft. All rights reserved.
using Microsoft.Agents.AI.DurableTask.Workflows;
namespace Microsoft.Agents.AI.DurableTask.UnitTests.Workflows;
public sealed class WorkflowNamingHelperTests
{
[Fact]
public void ToOrchestrationFunctionName_ValidWorkflowName_ReturnsPrefixedName()
{
string result = WorkflowNamingHelper.ToOrchestrationFunctionName("MyWorkflow");
Assert.Equal("dafx-MyWorkflow", result);
}
[Theory]
[InlineData(null)]
[InlineData("")]
public void ToOrchestrationFunctionName_NullOrEmpty_ThrowsArgumentException(string? workflowName)
{
Assert.ThrowsAny<ArgumentException>(() => WorkflowNamingHelper.ToOrchestrationFunctionName(workflowName!));
}
[Fact]
public void ToWorkflowName_ValidOrchestrationFunctionName_ReturnsWorkflowName()
{
string result = WorkflowNamingHelper.ToWorkflowName("dafx-MyWorkflow");
Assert.Equal("MyWorkflow", result);
}
[Theory]
[InlineData(null)]
[InlineData("")]
public void ToWorkflowName_NullOrEmpty_ThrowsArgumentException(string? orchestrationFunctionName)
{
Assert.ThrowsAny<ArgumentException>(() => WorkflowNamingHelper.ToWorkflowName(orchestrationFunctionName!));
}
[Theory]
[InlineData("MyWorkflow")]
[InlineData("invalid-prefix-MyWorkflow")]
[InlineData("dafx")]
[InlineData("dafx-")]
public void ToWorkflowName_InvalidOrMissingPrefix_ThrowsArgumentException(string orchestrationFunctionName)
{
Assert.Throws<ArgumentException>(() => WorkflowNamingHelper.ToWorkflowName(orchestrationFunctionName));
}
[Fact]
public void GetExecutorName_SimpleExecutorId_ReturnsSameName()
{
string result = WorkflowNamingHelper.GetExecutorName("OrderParser");
Assert.Equal("OrderParser", result);
}
[Fact]
public void GetExecutorName_ExecutorIdWithGuidSuffix_ReturnsNameWithoutSuffix()
{
string result = WorkflowNamingHelper.GetExecutorName("Physicist_8884e71021334ce49517fa2b17b1695b");
Assert.Equal("Physicist", result);
}
[Theory]
[InlineData(null)]
[InlineData("")]
public void GetExecutorName_NullOrEmpty_ThrowsArgumentException(string? executorId)
{
Assert.ThrowsAny<ArgumentException>(() => WorkflowNamingHelper.GetExecutorName(executorId!));
}
}