chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="..\..\Resources\*">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+      <Link>Resources\%(Filename)%(Extension)</Link>
+    </None>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,275 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowEdgeConditionSample;
+
+/// <summary>
+/// This sample introduces conditional routing using edge conditions to create decision-based workflows.
+///
+/// This workflow creates an automated email response system that routes emails down different paths based
+/// on spam detection results:
+///
+/// 1. Spam Detection Agent analyzes incoming emails and classifies them as spam or legitimate
+/// 2. Based on the classification:
+///    - Legitimate emails → Email Assistant Agent → Send Email Executor
+///    - Spam emails → Handle Spam Executor (marks as spam)
+///
+/// Edge conditions enable workflows to make intelligent routing decisions, allowing you to
+/// build sophisticated automation that responds differently based on the data being processed.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - Shared state is used in this sample to persist email data between executors.
+/// - An Azure OpenAI chat completion deployment that supports structured outputs must be configured.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Set up the Azure AI Foundry client
+        var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+        var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+        AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+        // Create agents
+        AIAgent spamDetectionAgent = GetSpamDetectionAgent(aiProjectClient, deploymentName);
+        AIAgent emailAssistantAgent = GetEmailAssistantAgent(aiProjectClient, deploymentName);
+
+        // Create executors
+        var spamDetectionExecutor = new SpamDetectionExecutor(spamDetectionAgent);
+        var emailAssistantExecutor = new EmailAssistantExecutor(emailAssistantAgent);
+        var sendEmailExecutor = new SendEmailExecutor();
+        var handleSpamExecutor = new HandleSpamExecutor();
+
+        // Build the workflow by adding executors and connecting them
+        var workflow = new WorkflowBuilder(spamDetectionExecutor)
+            .AddEdge(spamDetectionExecutor, emailAssistantExecutor, condition: GetCondition(expectedResult: false))
+            .AddEdge(emailAssistantExecutor, sendEmailExecutor)
+            .AddEdge(spamDetectionExecutor, handleSpamExecutor, condition: GetCondition(expectedResult: true))
+            .WithOutputFrom(handleSpamExecutor, sendEmailExecutor)
+            .Build();
+
+        // Read a email from a text file
+        string email = Resources.Read("spam.txt");
+
+        // Execute the workflow
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, new ChatMessage(ChatRole.User, email));
+        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            if (evt is WorkflowOutputEvent outputEvent)
+            {
+                Console.WriteLine($"{outputEvent}");
+            }
+            else if (evt is WorkflowErrorEvent workflowError)
+            {
+                Console.ForegroundColor = ConsoleColor.Red;
+                Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                Console.ResetColor();
+            }
+            else if (evt is ExecutorFailedEvent executorFailed)
+            {
+                Console.ForegroundColor = ConsoleColor.Red;
+                Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                Console.ResetColor();
+            }
+        }
+    }
+
+    /// <summary>
+    /// Creates a condition for routing messages based on the expected spam detection result.
+    /// </summary>
+    /// <param name="expectedResult">The expected spam detection result</param>
+    /// <returns>A function that evaluates whether a message meets the expected result</returns>
+    private static Func<object?, bool> GetCondition(bool expectedResult) =>
+        detectionResult => detectionResult is DetectionResult result && result.IsSpam == expectedResult;
+
+    /// <summary>
+    /// Creates a spam detection agent.
+    /// </summary>
+    /// <returns>A ChatClientAgent configured for spam detection</returns>
+    private static ChatClientAgent GetSpamDetectionAgent(AIProjectClient client, string model) =>
+        client.AsAIAgent(new ChatClientAgentOptions()
+        {
+            ChatOptions = new()
+            {
+                ModelId = model,
+                Instructions = "You are a spam detection assistant that identifies spam emails.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<DetectionResult>()
+            }
+        });
+
+    /// <summary>
+    /// Creates an email assistant agent.
+    /// </summary>
+    /// <returns>A ChatClientAgent configured for email assistance</returns>
+    private static ChatClientAgent GetEmailAssistantAgent(AIProjectClient client, string model) =>
+        client.AsAIAgent(new ChatClientAgentOptions()
+        {
+            ChatOptions = new()
+            {
+                ModelId = model,
+                Instructions = "You are an email assistant that helps users draft responses to emails with professionalism.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<EmailResponse>()
+            }
+        });
+}
+
+/// <summary>
+/// Constants for shared state scopes.
+/// </summary>
+internal static class EmailStateConstants
+{
+    public const string EmailStateScope = "EmailState";
+}
+
+/// <summary>
+/// Represents the result of spam detection.
+/// </summary>
+public sealed class DetectionResult
+{
+    [JsonPropertyName("is_spam")]
+    public bool IsSpam { get; set; }
+
+    [JsonPropertyName("reason")]
+    public string Reason { get; set; } = string.Empty;
+
+    // Email ID is generated by the executor not the agent
+    [JsonIgnore]
+    public string EmailId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Represents an email.
+/// </summary>
+internal sealed class Email
+{
+    [JsonPropertyName("email_id")]
+    public string EmailId { get; set; } = string.Empty;
+
+    [JsonPropertyName("email_content")]
+    public string EmailContent { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Executor that detects spam using an AI agent.
+/// </summary>
+internal sealed class SpamDetectionExecutor : Executor<ChatMessage, DetectionResult>
+{
+    private readonly AIAgent _spamDetectionAgent;
+
+    /// <summary>
+    /// Creates a new instance of the <see cref="SpamDetectionExecutor"/> class.
+    /// </summary>
+    /// <param name="spamDetectionAgent">The AI agent used for spam detection</param>
+    public SpamDetectionExecutor(AIAgent spamDetectionAgent) : base("SpamDetectionExecutor")
+    {
+        this._spamDetectionAgent = spamDetectionAgent;
+    }
+
+    public override async ValueTask<DetectionResult> HandleAsync(ChatMessage message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Generate a random email ID and store the email content to the shared state
+        var newEmail = new Email
+        {
+            EmailId = Guid.NewGuid().ToString("N"),
+            EmailContent = message.Text
+        };
+        await context.QueueStateUpdateAsync(newEmail.EmailId, newEmail, scopeName: EmailStateConstants.EmailStateScope, cancellationToken);
+
+        // Invoke the agent
+        var response = await this._spamDetectionAgent.RunAsync(message, cancellationToken: cancellationToken);
+        var detectionResult = JsonSerializer.Deserialize<DetectionResult>(response.Text);
+
+        detectionResult!.EmailId = newEmail.EmailId;
+
+        return detectionResult;
+    }
+}
+
+/// <summary>
+/// Represents the response from the email assistant.
+/// </summary>
+public sealed class EmailResponse
+{
+    [JsonPropertyName("response")]
+    public string Response { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Executor that assists with email responses using an AI agent.
+/// </summary>
+internal sealed class EmailAssistantExecutor : Executor<DetectionResult, EmailResponse>
+{
+    private readonly AIAgent _emailAssistantAgent;
+
+    /// <summary>
+    /// Creates a new instance of the <see cref="EmailAssistantExecutor"/> class.
+    /// </summary>
+    /// <param name="emailAssistantAgent">The AI agent used for email assistance</param>
+    public EmailAssistantExecutor(AIAgent emailAssistantAgent) : base("EmailAssistantExecutor")
+    {
+        this._emailAssistantAgent = emailAssistantAgent;
+    }
+
+    public override async ValueTask<EmailResponse> HandleAsync(DetectionResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        if (message.IsSpam)
+        {
+            throw new InvalidOperationException("This executor should only handle non-spam messages.");
+        }
+
+        // Retrieve the email content from the shared state
+        var email = await context.ReadStateAsync<Email>(message.EmailId, scopeName: EmailStateConstants.EmailStateScope, cancellationToken)
+            ?? throw new InvalidOperationException("Email not found.");
+
+        // Invoke the agent
+        var response = await this._emailAssistantAgent.RunAsync(email.EmailContent, cancellationToken: cancellationToken);
+        var emailResponse = JsonSerializer.Deserialize<EmailResponse>(response.Text);
+
+        return emailResponse!;
+    }
+}
+
+/// <summary>
+/// Executor that sends emails.
+/// </summary>
+[YieldsOutput(typeof(string))]
+internal sealed class SendEmailExecutor() : Executor<EmailResponse>("SendEmailExecutor")
+{
+    /// <summary>
+    /// Simulate the sending of an email.
+    /// </summary>
+    public override async ValueTask HandleAsync(EmailResponse message, IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        await context.YieldOutputAsync($"Email sent: {message.Response}", cancellationToken);
+}
+
+/// <summary>
+/// Executor that handles spam messages.
+/// </summary>
+[YieldsOutput(typeof(string))]
+internal sealed class HandleSpamExecutor() : Executor<DetectionResult>("HandleSpamExecutor")
+{
+    /// <summary>
+    /// Simulate the handling of a spam message.
+    /// </summary>
+    public override async ValueTask HandleAsync(DetectionResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        if (message.IsSpam)
+        {
+            await context.YieldOutputAsync($"Email marked as spam: {message.Reason}", cancellationToken);
+        }
+        else
+        {
+            throw new InvalidOperationException("This executor should only handle spam messages.");
+        }
+    }
+}
@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace WorkflowEdgeConditionSample;
+
+/// <summary>
+/// Resource helper to load resources.
+/// </summary>
+internal static class Resources
+{
+    private const string ResourceFolder = "Resources";
+
+    public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
+}
@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="..\..\Resources\*">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+      <Link>Resources\%(Filename)%(Extension)</Link>
+    </None>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,322 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowSwitchCaseSample;
+
+/// <summary>
+/// This sample introduces conditional routing using switch-case logic for complex decision trees.
+///
+/// Building on the previous email automation examples, this workflow adds a third decision path
+/// to handle ambiguous cases where spam detection is uncertain. Now the workflow can route emails
+/// three ways based on the detection result:
+///
+/// 1. Not Spam → Email Assistant → Send Email
+/// 2. Spam → Handle Spam Executor
+/// 3. Uncertain → Handle Uncertain Executor (default case)
+///
+/// The switch-case pattern provides cleaner syntax than multiple individual edge conditions,
+/// especially when dealing with multiple possible outcomes. This approach scales well for
+/// workflows that need to handle many different scenarios.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - Shared state is used in this sample to persist email data between executors.
+/// - An Azure OpenAI chat completion deployment that supports structured outputs must be configured.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Set up the Azure AI Foundry client
+        var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+        var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+        AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+        // Create agents
+        AIAgent spamDetectionAgent = GetSpamDetectionAgent(aiProjectClient, deploymentName);
+        AIAgent emailAssistantAgent = GetEmailAssistantAgent(aiProjectClient, deploymentName);
+
+        // Create executors
+        var spamDetectionExecutor = new SpamDetectionExecutor(spamDetectionAgent);
+        var emailAssistantExecutor = new EmailAssistantExecutor(emailAssistantAgent);
+        var sendEmailExecutor = new SendEmailExecutor();
+        var handleSpamExecutor = new HandleSpamExecutor();
+        var handleUncertainExecutor = new HandleUncertainExecutor();
+
+        // Build the workflow by adding executors and connecting them
+        WorkflowBuilder builder = new(spamDetectionExecutor);
+        builder.AddSwitch(spamDetectionExecutor, switchBuilder =>
+            switchBuilder
+            .AddCase(
+                GetCondition(expectedDecision: SpamDecision.NotSpam),
+                emailAssistantExecutor
+            )
+            .AddCase(
+                GetCondition(expectedDecision: SpamDecision.Spam),
+                handleSpamExecutor
+            )
+            .WithDefault(
+                handleUncertainExecutor
+            )
+        )
+        // After the email assistant writes a response, it will be sent to the send email executor
+        .AddEdge(emailAssistantExecutor, sendEmailExecutor)
+        .WithOutputFrom(handleSpamExecutor, sendEmailExecutor, handleUncertainExecutor);
+
+        var workflow = builder.Build();
+
+        // Read a email from a text file
+        string email = Resources.Read("ambiguous_email.txt");
+
+        // Execute the workflow
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, new ChatMessage(ChatRole.User, email));
+        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            if (evt is WorkflowOutputEvent outputEvent)
+            {
+                Console.WriteLine($"{outputEvent}");
+            }
+            else if (evt is WorkflowErrorEvent workflowError)
+            {
+                Console.ForegroundColor = ConsoleColor.Red;
+                Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                Console.ResetColor();
+            }
+            else if (evt is ExecutorFailedEvent executorFailed)
+            {
+                Console.ForegroundColor = ConsoleColor.Red;
+                Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                Console.ResetColor();
+            }
+        }
+    }
+
+    /// <summary>
+    /// Creates a condition for routing messages based on the expected spam detection result.
+    /// </summary>
+    /// <param name="expectedDecision">The expected spam detection decision</param>
+    /// <returns>A function that evaluates whether a message meets the expected result</returns>
+    private static Func<object?, bool> GetCondition(SpamDecision expectedDecision) => detectionResult => detectionResult is DetectionResult result && result.spamDecision == expectedDecision;
+
+    /// <summary>
+    /// Creates a spam detection agent.
+    /// </summary>
+    /// <returns>A ChatClientAgent configured for spam detection</returns>
+    private static ChatClientAgent GetSpamDetectionAgent(AIProjectClient client, string model) =>
+        client.AsAIAgent(new ChatClientAgentOptions()
+        {
+            ChatOptions = new()
+            {
+                ModelId = model,
+                Instructions = "You are a spam detection assistant that identifies spam emails. Be less confident in your assessments.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<DetectionResult>()
+            }
+        });
+
+    /// <summary>
+    /// Creates an email assistant agent.
+    /// </summary>
+    /// <returns>A ChatClientAgent configured for email assistance</returns>
+    private static ChatClientAgent GetEmailAssistantAgent(AIProjectClient client, string model) =>
+        client.AsAIAgent(new ChatClientAgentOptions()
+        {
+            ChatOptions = new()
+            {
+                ModelId = model,
+                Instructions = "You are an email assistant that helps users draft responses to emails with professionalism.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<EmailResponse>()
+            }
+        });
+}
+
+/// <summary>
+/// Constants for shared email state.
+/// </summary>
+internal static class EmailStateConstants
+{
+    public const string EmailStateScope = "EmailState";
+}
+
+/// <summary>
+/// Represents the possible decisions for spam detection.
+/// </summary>
+public enum SpamDecision
+{
+    NotSpam,
+    Spam,
+    Uncertain
+}
+
+/// <summary>
+/// Represents the result of spam detection.
+/// </summary>
+public sealed class DetectionResult
+{
+    [JsonPropertyName("spam_decision")]
+    [JsonConverter(typeof(JsonStringEnumConverter))]
+    public SpamDecision spamDecision { get; set; }
+
+    [JsonPropertyName("reason")]
+    public string Reason { get; set; } = string.Empty;
+
+    [JsonIgnore]
+    public string EmailId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Represents an email.
+/// </summary>
+internal sealed class Email
+{
+    [JsonPropertyName("email_id")]
+    public string EmailId { get; set; } = string.Empty;
+
+    [JsonPropertyName("email_content")]
+    public string EmailContent { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Executor that detects spam using an AI agent.
+/// </summary>
+internal sealed class SpamDetectionExecutor : Executor<ChatMessage, DetectionResult>
+{
+    private readonly AIAgent _spamDetectionAgent;
+
+    /// <summary>
+    /// Creates a new instance of the <see cref="SpamDetectionExecutor"/> class.
+    /// </summary>
+    /// <param name="spamDetectionAgent">The AI agent used for spam detection</param>
+    public SpamDetectionExecutor(AIAgent spamDetectionAgent) : base("SpamDetectionExecutor")
+    {
+        this._spamDetectionAgent = spamDetectionAgent;
+    }
+
+    public override async ValueTask<DetectionResult> HandleAsync(ChatMessage message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Generate a random email ID and store the email content
+        var newEmail = new Email
+        {
+            EmailId = Guid.NewGuid().ToString("N"),
+            EmailContent = message.Text
+        };
+        await context.QueueStateUpdateAsync(newEmail.EmailId, newEmail, scopeName: EmailStateConstants.EmailStateScope, cancellationToken);
+
+        // Invoke the agent
+        var response = await this._spamDetectionAgent.RunAsync(message, cancellationToken: cancellationToken);
+        var detectionResult = JsonSerializer.Deserialize<DetectionResult>(response.Text);
+
+        detectionResult!.EmailId = newEmail.EmailId;
+
+        return detectionResult;
+    }
+}
+
+/// <summary>
+/// Represents the response from the email assistant.
+/// </summary>
+public sealed class EmailResponse
+{
+    [JsonPropertyName("response")]
+    public string Response { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Executor that assists with email responses using an AI agent.
+/// </summary>
+internal sealed class EmailAssistantExecutor : Executor<DetectionResult, EmailResponse>
+{
+    private readonly AIAgent _emailAssistantAgent;
+
+    /// <summary>
+    /// Creates a new instance of the <see cref="EmailAssistantExecutor"/> class.
+    /// </summary>
+    /// <param name="emailAssistantAgent">The AI agent used for email assistance</param>
+    public EmailAssistantExecutor(AIAgent emailAssistantAgent) : base("EmailAssistantExecutor")
+    {
+        this._emailAssistantAgent = emailAssistantAgent;
+    }
+
+    public override async ValueTask<EmailResponse> HandleAsync(DetectionResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        if (message.spamDecision == SpamDecision.Spam)
+        {
+            throw new InvalidOperationException("This executor should only handle non-spam messages.");
+        }
+
+        // Retrieve the email content from the context
+        var email = await context.ReadStateAsync<Email>(message.EmailId, scopeName: EmailStateConstants.EmailStateScope, cancellationToken);
+
+        // Invoke the agent
+        var response = await this._emailAssistantAgent.RunAsync(email!.EmailContent, cancellationToken: cancellationToken);
+        var emailResponse = JsonSerializer.Deserialize<EmailResponse>(response.Text);
+
+        return emailResponse!;
+    }
+}
+
+/// <summary>
+/// Executor that sends emails.
+/// </summary>
+[YieldsOutput(typeof(string))]
+internal sealed class SendEmailExecutor() : Executor<EmailResponse>("SendEmailExecutor")
+{
+    /// <summary>
+    /// Simulate the sending of an email.
+    /// </summary>
+    public override async ValueTask HandleAsync(EmailResponse message, IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        await context.YieldOutputAsync($"Email sent: {message.Response}", cancellationToken);
+}
+
+/// <summary>
+/// Executor that handles spam messages.
+/// </summary>
+[YieldsOutput(typeof(string))]
+internal sealed class HandleSpamExecutor() : Executor<DetectionResult>("HandleSpamExecutor")
+{
+    /// <summary>
+    /// Simulate the handling of a spam message.
+    /// </summary>
+    public override async ValueTask HandleAsync(DetectionResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        if (message.spamDecision == SpamDecision.Spam)
+        {
+            await context.YieldOutputAsync($"Email marked as spam: {message.Reason}", cancellationToken);
+        }
+        else
+        {
+            throw new InvalidOperationException("This executor should only handle spam messages.");
+        }
+    }
+}
+
+/// <summary>
+/// Executor that handles uncertain emails.
+/// </summary>
+[YieldsOutput(typeof(string))]
+internal sealed class HandleUncertainExecutor() : Executor<DetectionResult>("HandleUncertainExecutor")
+{
+    /// <summary>
+    /// Simulate the handling of an uncertain spam decision.
+    /// </summary>
+    public override async ValueTask HandleAsync(DetectionResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        if (message.spamDecision == SpamDecision.Uncertain)
+        {
+            var email = await context.ReadStateAsync<Email>(message.EmailId, scopeName: EmailStateConstants.EmailStateScope, cancellationToken);
+            await context.YieldOutputAsync($"Email marked as uncertain: {message.Reason}. Email content: {email?.EmailContent}", cancellationToken);
+        }
+        else
+        {
+            throw new InvalidOperationException("This executor should only handle uncertain spam decisions.");
+        }
+    }
+}
@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace WorkflowSwitchCaseSample;
+
+/// <summary>
+/// Resource helper to load resources.
+/// </summary>
+internal static class Resources
+{
+    private const string ResourceFolder = "Resources";
+
+    public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
+}
@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="..\..\Resources\*">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+      <Link>Resources\%(Filename)%(Extension)</Link>
+    </None>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,460 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowMultiSelectionSample;
+
+/// <summary>
+/// This sample introduces multi-selection routing where one executor can trigger multiple downstream executors.
+///
+/// Extending the switch-case pattern from the previous sample, the workflow can now
+/// trigger multiple executors simultaneously when certain conditions are met.
+///
+/// Key features:
+/// - For legitimate emails: triggers Email Assistant (always) + Email Summary (if email is long)
+/// - For spam emails: triggers Handle Spam executor only
+/// - For uncertain emails: triggers Handle Uncertain executor only
+/// - Database logging happens for both short emails and summarized long emails
+///
+/// This pattern is powerful for workflows that need parallel processing based on data characteristics,
+/// such as triggering different analytics pipelines or multiple notification systems.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - Shared state is used in this sample to persist email data between executors.
+/// - An Azure OpenAI chat completion deployment that supports structured outputs must be configured.
+/// </remarks>
+public static class Program
+{
+    private const int LongEmailThreshold = 100;
+
+    private static async Task Main()
+    {
+        // Set up the Azure AI Foundry client
+        var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+        var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+        AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+        // Create agents
+        AIAgent emailAnalysisAgent = GetEmailAnalysisAgent(aiProjectClient, deploymentName);
+        AIAgent emailAssistantAgent = GetEmailAssistantAgent(aiProjectClient, deploymentName);
+        AIAgent emailSummaryAgent = GetEmailSummaryAgent(aiProjectClient, deploymentName);
+
+        // Create executors
+        var emailAnalysisExecutor = new EmailAnalysisExecutor(emailAnalysisAgent);
+        var emailAssistantExecutor = new EmailAssistantExecutor(emailAssistantAgent);
+        var emailSummaryExecutor = new EmailSummaryExecutor(emailSummaryAgent);
+        var sendEmailExecutor = new SendEmailExecutor();
+        var handleSpamExecutor = new HandleSpamExecutor();
+        var handleUncertainExecutor = new HandleUncertainExecutor();
+        var databaseAccessExecutor = new DatabaseAccessExecutor();
+
+        // Build the workflow by adding executors and connecting them
+        WorkflowBuilder builder = new(emailAnalysisExecutor);
+        builder.AddFanOutEdge(
+            emailAnalysisExecutor,
+            [
+                handleSpamExecutor,
+                emailAssistantExecutor,
+                emailSummaryExecutor,
+                handleUncertainExecutor,
+            ],
+            GetTargetAssigner()
+        )
+        // After the email assistant writes a response, it will be sent to the send email executor
+        .AddEdge(emailAssistantExecutor, sendEmailExecutor)
+        // Save the analysis result to the database if summary is not needed
+        .AddEdge<AnalysisResult>(
+            emailAnalysisExecutor,
+            databaseAccessExecutor,
+            condition: analysisResult => analysisResult?.EmailLength <= LongEmailThreshold)
+        // Save the analysis result to the database with summary
+        .AddEdge(emailSummaryExecutor, databaseAccessExecutor)
+        .WithOutputFrom(handleUncertainExecutor, handleSpamExecutor, sendEmailExecutor);
+
+        var workflow = builder.Build();
+
+        // Read a email from a text file
+        string email = Resources.Read("email.txt");
+
+        // Execute the workflow
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, new ChatMessage(ChatRole.User, email));
+        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            if (evt is WorkflowOutputEvent outputEvent)
+            {
+                Console.WriteLine($"{outputEvent}");
+            }
+            else if (evt is ClassificationEvent classificationEvent)
+            {
+                Console.WriteLine($"{classificationEvent}");
+            }
+            else if (evt is DatabaseEvent databaseEvent)
+            {
+                Console.WriteLine($"{databaseEvent}");
+            }
+            else if (evt is WorkflowErrorEvent workflowError)
+            {
+                Console.ForegroundColor = ConsoleColor.Red;
+                Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                Console.ResetColor();
+            }
+            else if (evt is ExecutorFailedEvent executorFailed)
+            {
+                Console.ForegroundColor = ConsoleColor.Red;
+                Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                Console.ResetColor();
+            }
+        }
+    }
+
+    /// <summary>
+    /// Creates a partitioner for routing messages based on the analysis result.
+    /// </summary>
+    /// <returns>A function that takes an analysis result and returns the target partitions.</returns>
+    private static Func<AnalysisResult?, int, IEnumerable<int>> GetTargetAssigner()
+    {
+        return (analysisResult, targetCount) =>
+        {
+            if (analysisResult is not null)
+            {
+                if (analysisResult.spamDecision == SpamDecision.Spam)
+                {
+                    return [0]; // Route to spam handler
+                }
+                else if (analysisResult.spamDecision == SpamDecision.NotSpam)
+                {
+                    List<int> targets = [1]; // Route to the email assistant
+
+                    if (analysisResult.EmailLength > LongEmailThreshold)
+                    {
+                        targets.Add(2); // Route to the email summarizer too
+                    }
+
+                    return targets;
+                }
+                else
+                {
+                    return [3];
+                }
+            }
+            throw new InvalidOperationException("Invalid analysis result.");
+        };
+    }
+
+    /// <summary>
+    /// Create an email analysis agent.
+    /// </summary>
+    /// <returns>A ChatClientAgent configured for email analysis</returns>
+    private static ChatClientAgent GetEmailAnalysisAgent(AIProjectClient client, string model) =>
+        client.AsAIAgent(new ChatClientAgentOptions()
+        {
+            ChatOptions = new()
+            {
+                ModelId = model,
+                Instructions = "You are a spam detection assistant that identifies spam emails.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<AnalysisResult>()
+            }
+        });
+
+    /// <summary>
+    /// Creates an email assistant agent.
+    /// </summary>
+    /// <returns>A ChatClientAgent configured for email assistance</returns>
+    private static ChatClientAgent GetEmailAssistantAgent(AIProjectClient client, string model) =>
+        client.AsAIAgent(new ChatClientAgentOptions()
+        {
+            ChatOptions = new()
+            {
+                ModelId = model,
+                Instructions = "You are an email assistant that helps users draft responses to emails with professionalism.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<EmailResponse>()
+            }
+        });
+
+    /// <summary>
+    /// Creates an agent that summarizes emails.
+    /// </summary>
+    /// <returns>A ChatClientAgent configured for email summarization</returns>
+    private static ChatClientAgent GetEmailSummaryAgent(AIProjectClient client, string model) =>
+        client.AsAIAgent(new ChatClientAgentOptions()
+        {
+            ChatOptions = new()
+            {
+                ModelId = model,
+                Instructions = "You are an assistant that helps users summarize emails.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<EmailSummary>()
+            }
+        });
+}
+
+internal static class EmailStateConstants
+{
+    public const string EmailStateScope = "EmailState";
+}
+
+/// <summary>
+/// Represents the possible decisions for spam detection.
+/// </summary>
+public enum SpamDecision
+{
+    NotSpam,
+    Spam,
+    Uncertain
+}
+
+/// <summary>
+/// Represents the result of email analysis.
+/// </summary>
+public sealed class AnalysisResult
+{
+    [JsonPropertyName("spam_decision")]
+    [JsonConverter(typeof(JsonStringEnumConverter))]
+    public SpamDecision spamDecision { get; set; }
+
+    [JsonPropertyName("reason")]
+    public string Reason { get; set; } = string.Empty;
+
+    [JsonIgnore]
+    public int EmailLength { get; set; }
+
+    [JsonIgnore]
+    public string EmailSummary { get; set; } = string.Empty;
+
+    [JsonIgnore]
+    public string EmailId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Represents an email.
+/// </summary>
+internal sealed class Email
+{
+    [JsonPropertyName("email_id")]
+    public string EmailId { get; set; } = string.Empty;
+
+    [JsonPropertyName("email_content")]
+    public string EmailContent { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Executor that analyzes emails using an AI agent.
+/// </summary>
+internal sealed class EmailAnalysisExecutor : Executor<ChatMessage, AnalysisResult>
+{
+    private readonly AIAgent _emailAnalysisAgent;
+
+    /// <summary>
+    /// Creates a new instance of the <see cref="EmailAnalysisExecutor"/> class.
+    /// </summary>
+    /// <param name="emailAnalysisAgent">The AI agent used for email analysis</param>
+    public EmailAnalysisExecutor(AIAgent emailAnalysisAgent) : base("EmailAnalysisExecutor")
+    {
+        this._emailAnalysisAgent = emailAnalysisAgent;
+    }
+
+    public override async ValueTask<AnalysisResult> HandleAsync(ChatMessage message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Generate a random email ID and store the email content
+        var newEmail = new Email
+        {
+            EmailId = Guid.NewGuid().ToString("N"),
+            EmailContent = message.Text
+        };
+        await context.QueueStateUpdateAsync(newEmail.EmailId, newEmail, scopeName: EmailStateConstants.EmailStateScope, cancellationToken);
+
+        // Invoke the agent
+        var response = await this._emailAnalysisAgent.RunAsync(message, cancellationToken: cancellationToken);
+        var AnalysisResult = JsonSerializer.Deserialize<AnalysisResult>(response.Text);
+
+        AnalysisResult!.EmailId = newEmail.EmailId;
+        AnalysisResult!.EmailLength = newEmail.EmailContent.Length;
+
+        // Emit a classification event so the workflow output shows the spam decision.
+        await context.AddEventAsync(
+            new ClassificationEvent($"Email classified as: {AnalysisResult.spamDecision} — {AnalysisResult.Reason}"),
+            cancellationToken);
+
+        return AnalysisResult;
+    }
+}
+
+/// <summary>
+/// Represents the response from the email assistant.
+/// </summary>
+public sealed class EmailResponse
+{
+    [JsonPropertyName("response")]
+    public string Response { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Executor that assists with email responses using an AI agent.
+/// </summary>
+internal sealed class EmailAssistantExecutor : Executor<AnalysisResult, EmailResponse>
+{
+    private readonly AIAgent _emailAssistantAgent;
+
+    /// <summary>
+    /// Creates a new instance of the <see cref="EmailAssistantExecutor"/> class.
+    /// </summary>
+    /// <param name="emailAssistantAgent">The AI agent used for email assistance</param>
+    public EmailAssistantExecutor(AIAgent emailAssistantAgent) : base("EmailAssistantExecutor")
+    {
+        this._emailAssistantAgent = emailAssistantAgent;
+    }
+
+    public override async ValueTask<EmailResponse> HandleAsync(AnalysisResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        if (message.spamDecision == SpamDecision.Spam)
+        {
+            throw new InvalidOperationException("This executor should only handle non-spam messages.");
+        }
+
+        // Retrieve the email content from the context
+        var email = await context.ReadStateAsync<Email>(message.EmailId, scopeName: EmailStateConstants.EmailStateScope, cancellationToken);
+
+        // Invoke the agent
+        var response = await this._emailAssistantAgent.RunAsync(email!.EmailContent, cancellationToken: cancellationToken);
+        var emailResponse = JsonSerializer.Deserialize<EmailResponse>(response.Text);
+
+        return emailResponse!;
+    }
+}
+
+/// <summary>
+/// Executor that sends emails.
+/// </summary>
+[YieldsOutput(typeof(string))]
+internal sealed class SendEmailExecutor() : Executor<EmailResponse>("SendEmailExecutor")
+{
+    /// <summary>
+    /// Simulate the sending of an email.
+    /// </summary>
+    public override async ValueTask HandleAsync(EmailResponse message, IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        await context.YieldOutputAsync($"Email sent: {message.Response}", cancellationToken);
+}
+
+/// <summary>
+/// Executor that handles spam messages.
+/// </summary>
+[YieldsOutput(typeof(string))]
+internal sealed class HandleSpamExecutor() : Executor<AnalysisResult>("HandleSpamExecutor")
+{
+    /// <summary>
+    /// Simulate the handling of a spam message.
+    /// </summary>
+    public override async ValueTask HandleAsync(AnalysisResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        if (message.spamDecision == SpamDecision.Spam)
+        {
+            await context.YieldOutputAsync($"Email marked as spam: {message.Reason}", cancellationToken);
+        }
+        else
+        {
+            throw new InvalidOperationException("This executor should only handle spam messages.");
+        }
+    }
+}
+
+/// <summary>
+/// Executor that handles uncertain messages.
+/// </summary>
+[YieldsOutput(typeof(string))]
+internal sealed class HandleUncertainExecutor() : Executor<AnalysisResult>("HandleUncertainExecutor")
+{
+    /// <summary>
+    /// Simulate the handling of an uncertain spam decision.
+    /// </summary>
+    public override async ValueTask HandleAsync(AnalysisResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        if (message.spamDecision == SpamDecision.Uncertain)
+        {
+            var email = await context.ReadStateAsync<Email>(message.EmailId, scopeName: EmailStateConstants.EmailStateScope, cancellationToken);
+            await context.YieldOutputAsync($"Email marked as uncertain: {message.Reason}. Email content: {email?.EmailContent}", cancellationToken);
+        }
+        else
+        {
+            throw new InvalidOperationException("This executor should only handle uncertain spam decisions.");
+        }
+    }
+}
+
+/// <summary>
+/// Represents the response from the email summary agent.
+/// </summary>
+public sealed class EmailSummary
+{
+    [JsonPropertyName("summary")]
+    public string Summary { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// Executor that summarizes emails using an AI agent.
+/// </summary>
+internal sealed class EmailSummaryExecutor : Executor<AnalysisResult, AnalysisResult>
+{
+    private readonly AIAgent _emailSummaryAgent;
+
+    /// <summary>
+    /// Creates a new instance of the <see cref="EmailSummaryExecutor"/> class.
+    /// </summary>
+    /// <param name="emailSummaryAgent">The AI agent used for email summarization</param>
+    public EmailSummaryExecutor(AIAgent emailSummaryAgent) : base("EmailSummaryExecutor")
+    {
+        this._emailSummaryAgent = emailSummaryAgent;
+    }
+
+    public override async ValueTask<AnalysisResult> HandleAsync(AnalysisResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Read the email content from the shared states
+        var email = await context.ReadStateAsync<Email>(message.EmailId, scopeName: EmailStateConstants.EmailStateScope, cancellationToken);
+
+        // Invoke the agent
+        var response = await this._emailSummaryAgent.RunAsync(email!.EmailContent, cancellationToken: cancellationToken);
+        var emailSummary = JsonSerializer.Deserialize<EmailSummary>(response.Text);
+        message.EmailSummary = emailSummary!.Summary;
+
+        return message;
+    }
+}
+
+/// <summary>
+/// A custom workflow event for classification operations.
+/// </summary>
+/// <param name="message">The classification message</param>
+internal sealed class ClassificationEvent(string message) : WorkflowEvent(message) { }
+
+/// <summary>
+/// A custom workflow event for database operations.
+/// </summary>
+/// <param name="message">The message associated with the event</param>
+internal sealed class DatabaseEvent(string message) : WorkflowEvent(message) { }
+
+/// <summary>
+/// Executor that handles database access.
+/// </summary>
+internal sealed class DatabaseAccessExecutor() : Executor<AnalysisResult>("DatabaseAccessExecutor")
+{
+    public override async ValueTask HandleAsync(AnalysisResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // 1. Save the email content
+        await context.ReadStateAsync<Email>(message.EmailId, scopeName: EmailStateConstants.EmailStateScope, cancellationToken);
+        await Task.Delay(100, cancellationToken); // Simulate database access delay
+
+        // 2. Save the analysis result
+        await Task.Delay(100, cancellationToken); // Simulate database access delay
+
+        // Not using the `WorkflowCompletedEvent` because this is not the end of the workflow.
+        // The end of the workflow is signaled by the `SendEmailExecutor` or the `HandleUnknownExecutor`.
+        await context.AddEventAsync(new DatabaseEvent($"Email {message.EmailId} saved to database."), cancellationToken);
+    }
+}
@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace WorkflowMultiSelectionSample;
+
+/// <summary>
+/// Resource helper to load resources.
+/// </summary>
+internal static class Resources
+{
+    private const string ResourceFolder = "Resources";
+
+    public static string Read(string fileName) => File.ReadAllText(Path.Combine(AppContext.BaseDirectory, ResourceFolder, fileName));
+}