chore: import upstream snapshot with attribution

dotnet/samples/03-workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj

@@ -0,0 +1,21 @@
+<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.Workflows.Generators\Microsoft.Agents.AI.Workflows.Generators.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Agents/CustomAgentExecutors/Program.cs

@@ -0,0 +1,250 @@
+// 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 WorkflowCustomAgentExecutorsSample;
+
+/// <summary>
+/// This sample demonstrates how to create custom executors for AI agents.
+/// This is useful when you want more control over the agent's behaviors in a workflow.
+///
+/// In this example, we create two custom executors:
+/// 1. SloganWriterExecutor: An AI agent that generates slogans based on a given task.
+/// 2. FeedbackExecutor: An AI agent that provides feedback on the generated slogans.
+/// (These two executors manage the agent instances and their conversation threads.)
+///
+/// The workflow alternates between these two executors until the slogan meets a certain
+/// quality threshold or a maximum number of attempts is reached.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - 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 the executors
+        var sloganWriter = new SloganWriterExecutor("SloganWriter", aiProjectClient, deploymentName);
+        var feedbackProvider = new FeedbackExecutor("FeedbackProvider", aiProjectClient, deploymentName);
+
+        // Build the workflow by adding executors and connecting them
+        var workflow = new WorkflowBuilder(sloganWriter)
+            .AddEdge(sloganWriter, feedbackProvider)
+            .AddEdge(feedbackProvider, sloganWriter)
+            .WithOutputFrom(feedbackProvider)
+            .Build();
+
+        // Execute the workflow
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input: "Create a slogan for a new electric SUV that is affordable and fun to drive.");
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            if (evt is SloganGeneratedEvent or FeedbackEvent)
+            {
+                // Custom events to allow us to monitor the progress of the workflow.
+                Console.WriteLine($"{evt}");
+            }
+
+            if (evt is WorkflowOutputEvent outputEvent)
+            {
+                Console.WriteLine($"{outputEvent}");
+            }
+
+            if (evt is WorkflowErrorEvent errorEvent)
+            {
+                Console.WriteLine($"Workflow error: {errorEvent.Exception?.Message}");
+                Console.WriteLine($"Details: {errorEvent.Exception}");
+            }
+        }
+    }
+}
+
+/// <summary>
+/// A class representing the output of the slogan writer agent.
+/// </summary>
+public sealed class SloganResult
+{
+    [JsonPropertyName("task")]
+    public required string Task { get; set; }
+
+    [JsonPropertyName("slogan")]
+    public required string Slogan { get; set; }
+}
+
+/// <summary>
+/// A class representing the output of the feedback agent.
+/// </summary>
+public sealed class FeedbackResult
+{
+    [JsonPropertyName("comments")]
+    public string Comments { get; set; } = string.Empty;
+
+    [JsonPropertyName("rating")]
+    public int Rating { get; set; }
+
+    [JsonPropertyName("actions")]
+    public string Actions { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// A custom event to indicate that a slogan has been generated.
+/// </summary>
+internal sealed class SloganGeneratedEvent(SloganResult sloganResult) : WorkflowEvent(sloganResult)
+{
+    public override string ToString() => $"Slogan: {sloganResult.Slogan}";
+}
+
+/// <summary>
+/// A custom executor that uses an AI agent to generate slogans based on a given task.
+/// Note that this executor has two message handlers:
+/// 1. HandleAsync(string message): Handles the initial task to create a slogan.
+/// 2. HandleAsync(Feedback message): Handles feedback to improve the slogan.
+/// </summary>
+internal sealed partial class SloganWriterExecutor : Executor
+{
+    private readonly AIAgent _agent;
+    private AgentSession? _session;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SloganWriterExecutor"/> class.
+    /// </summary>
+    /// <param name="id">A unique identifier for the executor.</param>
+    /// <param name="chatClient">The AI project client to use for the AI agent.</param>
+    /// <param name="model">The model deployment name.</param>
+    public SloganWriterExecutor(string id, AIProjectClient chatClient, string model) : base(id)
+    {
+        ChatClientAgentOptions agentOptions = new()
+        {
+            ChatOptions = new()
+            {
+                ModelId = model,
+                Instructions = "You are a professional slogan writer. You will be given a task to create a slogan.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<SloganResult>()
+            }
+        };
+
+        this._agent = chatClient.AsAIAgent(agentOptions);
+    }
+
+    [MessageHandler]
+    public async ValueTask<SloganResult> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._session ??= await this._agent.CreateSessionAsync(cancellationToken);
+
+        var result = await this._agent.RunAsync(message, this._session, cancellationToken: cancellationToken);
+
+        var sloganResult = JsonSerializer.Deserialize<SloganResult>(result.Text) ?? throw new InvalidOperationException("Failed to deserialize slogan result.");
+
+        await context.AddEventAsync(new SloganGeneratedEvent(sloganResult), cancellationToken);
+        return sloganResult;
+    }
+
+    [MessageHandler]
+    public async ValueTask<SloganResult> HandleAsync(FeedbackResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        var feedbackMessage = $"""
+            Here is the feedback on your previous slogan:
+            Comments: {message.Comments}
+            Rating: {message.Rating}
+            Suggested Actions: {message.Actions}
+
+            Please use this feedback to improve your slogan.
+            """;
+
+        var result = await this._agent.RunAsync(feedbackMessage, this._session, cancellationToken: cancellationToken);
+        var sloganResult = JsonSerializer.Deserialize<SloganResult>(result.Text) ?? throw new InvalidOperationException("Failed to deserialize slogan result.");
+
+        await context.AddEventAsync(new SloganGeneratedEvent(sloganResult), cancellationToken);
+        return sloganResult;
+    }
+}
+
+/// <summary>
+/// A custom event to indicate that feedback has been provided.
+/// </summary>
+internal sealed class FeedbackEvent(FeedbackResult feedbackResult) : WorkflowEvent(feedbackResult)
+{
+    private readonly JsonSerializerOptions _options = new() { WriteIndented = true };
+    public override string ToString() => $"Feedback:\n{JsonSerializer.Serialize(feedbackResult, this._options)}";
+}
+
+/// <summary>
+/// A custom executor that uses an AI agent to provide feedback on a slogan.
+/// </summary>
+[SendsMessage(typeof(FeedbackResult))]
+[YieldsOutput(typeof(string))]
+internal sealed partial class FeedbackExecutor : Executor<SloganResult>
+{
+    private readonly AIAgent _agent;
+    private AgentSession? _session;
+
+    public int MinimumRating { get; init; } = 8;
+
+    public int MaxAttempts { get; init; } = 3;
+
+    private int _attempts;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FeedbackExecutor"/> class.
+    /// </summary>
+    /// <param name="id">A unique identifier for the executor.</param>
+    /// <param name="chatClient">The AI project client to use for the AI agent.</param>
+    /// <param name="model">The model deployment name.</param>
+    public FeedbackExecutor(string id, AIProjectClient chatClient, string model) : base(id)
+    {
+        ChatClientAgentOptions agentOptions = new()
+        {
+            ChatOptions = new()
+            {
+                ModelId = model,
+                Instructions = "You are a professional editor. You will be given a slogan and the task it is meant to accomplish.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<FeedbackResult>()
+            }
+        };
+
+        this._agent = chatClient.AsAIAgent(agentOptions);
+    }
+
+    public override async ValueTask HandleAsync(SloganResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._session ??= await this._agent.CreateSessionAsync(cancellationToken);
+
+        var sloganMessage = $"""
+            Here is a slogan for the task '{message.Task}':
+            Slogan: {message.Slogan}
+            Please provide feedback on this slogan, including comments, a rating from 1 to 10, and suggested actions for improvement.
+            """;
+
+        var response = await this._agent.RunAsync(sloganMessage, this._session, cancellationToken: cancellationToken);
+        var feedback = JsonSerializer.Deserialize<FeedbackResult>(response.Text) ?? throw new InvalidOperationException("Failed to deserialize feedback.");
+
+        await context.AddEventAsync(new FeedbackEvent(feedback), cancellationToken);
+
+        if (feedback.Rating >= this.MinimumRating)
+        {
+            await context.YieldOutputAsync($"The following slogan was accepted:\n\n{message.Slogan}", cancellationToken);
+            return;
+        }
+
+        if (this._attempts >= this.MaxAttempts)
+        {
+            await context.YieldOutputAsync($"The slogan was rejected after {this.MaxAttempts} attempts. Final slogan:\n\n{message.Slogan}", cancellationToken);
+            return;
+        }
+
+        await context.SendMessageAsync(feedback, cancellationToken: cancellationToken);
+        this._attempts++;
+    }
+}

dotnet/samples/03-workflows/Agents/FoundryAgent/FoundryAgent.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Agents/FoundryAgent/Program.cs

@@ -0,0 +1,103 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowFoundryAgentSample;
+
+/// <summary>
+/// This sample shows how to use Microsoft Foundry Agents within a workflow.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - A Microsoft Foundry project endpoint and model ID.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Set up the Azure AI Project 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";
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
+
+        // Create agents
+        AIAgent frenchAgent = await CreateTranslationAgentAsync("French", aiProjectClient, deploymentName);
+        AIAgent spanishAgent = await CreateTranslationAgentAsync("Spanish", aiProjectClient, deploymentName);
+        AIAgent englishAgent = await CreateTranslationAgentAsync("English", aiProjectClient, deploymentName);
+
+        try
+        {
+            // Build the workflow by adding executors and connecting them
+            var workflow = new WorkflowBuilder(frenchAgent)
+                .AddEdge(frenchAgent, spanishAgent)
+                .AddEdge(spanishAgent, englishAgent)
+                .Build();
+
+            // Execute the workflow
+            await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, new ChatMessage(ChatRole.User, "Hello World!"));
+            // Must send the turn token to trigger the agents.
+            // The agents are wrapped as executors. When they receive messages,
+            // they will cache the messages and only start processing when they receive a TurnToken.
+            await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+            await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+            {
+                if (evt is AgentResponseUpdateEvent executorComplete)
+                {
+                    Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
+                }
+                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();
+                }
+            }
+        }
+        finally
+        {
+            // Cleanup the agents created for the sample.
+            await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(frenchAgent.Name);
+            await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(spanishAgent.Name);
+            await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(englishAgent.Name);
+        }
+    }
+
+    /// <summary>
+    /// Creates a translation agent for the specified target language.
+    /// </summary>
+    /// <param name="targetLanguage">The target language for translation</param>
+    /// <param name="aiProjectClient">The <see cref="AIProjectClient"/> to create the agent with.</param>
+    /// <param name="model">The model to use for the agent</param>
+    /// <returns>A FoundryAgent configured for the specified language</returns>
+    private static async Task<FoundryAgent> CreateTranslationAgentAsync(
+        string targetLanguage,
+        AIProjectClient aiProjectClient,
+        string model)
+    {
+        ProjectsAgentVersion agentVersion = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
+            $"{targetLanguage}Translator",
+            new ProjectsAgentVersionCreationOptions(
+                new DeclarativeAgentDefinition(model: model)
+                {
+                    Instructions = $"You are a translation assistant that translates the provided text to {targetLanguage}.",
+                }));
+        return aiProjectClient.AsAIAgent(agentVersion);
+    }
+}

dotnet/samples/03-workflows/Agents/GroupChatToolApproval/DeploymentGroupChatManager.cs

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowGroupChatToolApprovalSample;
+
+/// <summary>
+/// Custom GroupChatManager that selects the next speaker based on the conversation flow.
+/// </summary>
+/// <remarks>
+/// This simple selector follows a predefined flow:
+/// 1. QA Engineer runs tests
+/// 2. DevOps Engineer checks staging and creates rollback plan
+/// 3. DevOps Engineer deploys to production (triggers approval)
+/// </remarks>
+internal sealed class DeploymentGroupChatManager : GroupChatManager
+{
+    private readonly IReadOnlyList<AIAgent> _agents;
+
+    public DeploymentGroupChatManager(IReadOnlyList<AIAgent> agents)
+    {
+        this._agents = agents;
+    }
+
+    protected override ValueTask<AIAgent> SelectNextAgentAsync(
+        IReadOnlyList<ChatMessage> history,
+        CancellationToken cancellationToken = default)
+    {
+        if (history.Count == 0)
+        {
+            throw new InvalidOperationException("Conversation is empty; cannot select next speaker.");
+        }
+
+        // First speaker after initial user message
+        if (this.IterationCount == 0)
+        {
+            AIAgent qaAgent = this._agents.First(a => a.Name == "QAEngineer");
+            return new ValueTask<AIAgent>(qaAgent);
+        }
+
+        // Subsequent speakers are DevOps Engineer
+        AIAgent devopsAgent = this._agents.First(a => a.Name == "DevOpsEngineer");
+        return new ValueTask<AIAgent>(devopsAgent);
+    }
+}

dotnet/samples/03-workflows/Agents/GroupChatToolApproval/GroupChatToolApproval.csproj

@@ -0,0 +1,18 @@
+<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>
+
+</Project>

dotnet/samples/03-workflows/Agents/GroupChatToolApproval/Program.cs

@@ -0,0 +1,175 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use GroupChatBuilder with tools that require human
+// approval before execution. A group of specialized agents collaborate on a task, and
+// sensitive tool calls trigger human-in-the-loop approval.
+//
+// This sample works as follows:
+// 1. A GroupChatBuilder workflow is created with multiple specialized agents.
+// 2. A custom manager determines which agent speaks next based on conversation state.
+// 3. Agents collaborate on a software deployment task.
+// 4. When the deployment agent tries to deploy to production, it triggers an approval request.
+// 5. The sample simulates human approval and the workflow completes.
+//
+// Purpose:
+// Show how tool call approvals integrate with multi-agent group chat workflows where
+// different agents have different levels of tool access.
+//
+// Demonstrate:
+// - Using custom GroupChatManager with agents that have approval-required tools.
+// - Handling ToolApprovalRequestContent in group chat scenarios.
+// - Multi-round group chat with tool approval interruption and resumption.
+
+using System.ComponentModel;
+using System.Text.Json;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowGroupChatToolApprovalSample;
+
+/// <summary>
+/// This sample demonstrates how to use GroupChatBuilder with tools that require human
+/// approval before execution.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - An Azure OpenAI chat completion deployment must be configured.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        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";
+
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        // 1. Create AI client
+        AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+        // 2. Create specialized agents with their tools
+        ChatClientAgent qaEngineer = aiProjectClient.AsAIAgent(
+            model: deploymentName,
+            instructions: "You are a QA engineer responsible for running tests before deployment. Run the appropriate test suites and report the results clearly in your response, including pass/fail counts.",
+            name: "QAEngineer",
+            description: "QA engineer who runs tests",
+            tools: [AIFunctionFactory.Create(RunTests)]);
+
+        ChatClientAgent devopsEngineer = aiProjectClient.AsAIAgent(
+            model: deploymentName,
+            instructions: "You are a DevOps engineer responsible for deployments. Call CheckStagingStatus, then CreateRollbackPlan, then DeployToProduction — in that order. Do not ask for confirmation before deploying; deployment approval is handled automatically by the system. After all tools complete, summarize each step and its result in your text response.",
+            name: "DevOpsEngineer",
+            description: "DevOps engineer who handles deployments",
+            tools:
+            [
+                AIFunctionFactory.Create(CheckStagingStatus),
+                AIFunctionFactory.Create(CreateRollbackPlan),
+                new ApprovalRequiredAIFunction(AIFunctionFactory.Create(DeployToProduction))
+            ]);
+
+        // 3. Create custom GroupChatManager with speaker selection logic
+        DeploymentGroupChatManager manager = new([qaEngineer, devopsEngineer])
+        {
+            MaximumIterationCount = 4
+        };
+
+        // 4. Build a group chat workflow with the custom manager
+        Workflow workflow = AgentWorkflowBuilder
+            .CreateGroupChatBuilderWith(_ => manager)
+            .AddParticipants(qaEngineer, devopsEngineer)
+            .Build();
+
+        // 5. Start the workflow
+        Console.WriteLine("Starting group chat workflow for software deployment...");
+        Console.WriteLine($"Agents: [{qaEngineer.Name}, {devopsEngineer.Name}]");
+        Console.WriteLine(new string('-', 60));
+
+        List<ChatMessage> messages = [new(ChatRole.User, "We need to deploy version 2.4.0 to production. Please coordinate the deployment.")];
+
+        await using StreamingRun run = await InProcessExecution.Lockstep.RunStreamingAsync(workflow, messages);
+        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+
+        string? lastExecutorId = null;
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case RequestInfoEvent e:
+                {
+                    if (e.Request.TryGetDataAs(out ToolApprovalRequestContent? approvalRequestContent))
+                    {
+                        Console.WriteLine();
+                        Console.WriteLine($"[APPROVAL REQUIRED] From agent: {e.Request.PortInfo.PortId}");
+                        Console.WriteLine($"  Tool: {((FunctionCallContent)approvalRequestContent.ToolCall).Name}");
+                        Console.WriteLine($"  Arguments: {JsonSerializer.Serialize(((FunctionCallContent)approvalRequestContent.ToolCall).Arguments)}");
+                        Console.WriteLine();
+
+                        // Approve the tool call request
+                        Console.WriteLine($"Tool: {((FunctionCallContent)approvalRequestContent.ToolCall).Name} approved");
+                        await run.SendResponseAsync(e.Request.CreateResponse(approvalRequestContent.CreateResponse(approved: true)));
+                    }
+
+                    break;
+                }
+
+                case AgentResponseUpdateEvent e:
+                {
+                    if (e.ExecutorId != lastExecutorId)
+                    {
+                        if (lastExecutorId is not null)
+                        {
+                            Console.WriteLine();
+                        }
+
+                        Console.WriteLine($"- {e.ExecutorId}: ");
+                        lastExecutorId = e.ExecutorId;
+                    }
+
+                    Console.Write(e.Update.Text);
+
+                    break;
+                }
+
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+
+        Console.WriteLine();
+        Console.WriteLine(new string('-', 60));
+        Console.WriteLine("Deployment workflow completed successfully!");
+        Console.WriteLine("All agents have finished their tasks.");
+    }
+
+    // Tool definitions - These are called by the agents during workflow execution
+    [Description("Run automated tests for the application.")]
+    private static string RunTests([Description("Name of the test suite to run")] string testSuite)
+        => $"Test suite '{testSuite}' completed: 47 passed, 0 failed, 0 skipped";
+
+    [Description("Check the current status of the staging environment.")]
+    private static string CheckStagingStatus()
+        => "Staging environment: Healthy, Version 2.3.0 deployed, All services running";
+
+    [Description("Deploy specified components to production. Requires human approval.")]
+    private static string DeployToProduction(
+        [Description("The version to deploy")] string version,
+        [Description("Comma-separated list of components to deploy")] string components)
+        => $"Production deployment complete: Version {version}, Components: {components}";
+
+    [Description("Create a rollback plan for the deployment.")]
+    private static string CreateRollbackPlan([Description("The version being deployed")] string version)
+        => $"Rollback plan created for version {version}: Automated rollback to v2.2.0 if health checks fail within 5 minutes";
+}

dotnet/samples/03-workflows/Agents/GroupChatToolApproval/README.md

@@ -0,0 +1,70 @@
+# Group Chat with Tool Approval Sample
+
+This sample demonstrates how to use `GroupChatBuilder` with tools that require human approval before execution. A group of specialized agents collaborate on a task, and sensitive tool calls trigger human-in-the-loop approval.
+
+## What This Sample Demonstrates
+
+- Using a custom `GroupChatManager` with agents that have approval-required tools
+- Handling `FunctionApprovalRequestContent` in group chat scenarios
+- Multi-round group chat with tool approval interruption and resumption
+- Integrating tool call approvals with multi-agent workflows where different agents have different levels of tool access
+
+## How It Works
+
+1. A `GroupChatBuilder` workflow is created with multiple specialized agents
+2. A custom `DeploymentGroupChatManager` determines which agent speaks next based on conversation state
+3. Agents collaborate on a software deployment task:
+   - **QA Engineer**: Runs automated tests
+   - **DevOps Engineer**: Checks staging status, creates rollback plan, and deploys to production
+4. When the deployment agent tries to deploy to production, it triggers an approval request
+5. The sample simulates human approval and the workflow completes
+
+## Key Components
+
+### Approval-Required Tools
+
+The `DeployToProduction` function is wrapped with `ApprovalRequiredAIFunction` to require human approval:
+
+```csharp
+new ApprovalRequiredAIFunction(AIFunctionFactory.Create(DeployToProduction))
+```
+
+### Custom Group Chat Manager
+
+The `DeploymentGroupChatManager` implements custom speaker selection logic:
+- First iteration: QA Engineer runs tests
+- Subsequent iterations: DevOps Engineer handles deployment tasks
+
+### Approval Handling
+
+The sample demonstrates continuous event-driven execution with inline approval handling:
+- The workflow runs in a single event loop.
+- When an approval-required tool is invoked, the loop surfaces an approval request, processes the (simulated) human response, and then continues execution without starting a separate phase.
+
+## Prerequisites
+
+- Azure OpenAI or OpenAI configured with the required environment variables
+- `AZURE_OPENAI_ENDPOINT` environment variable set
+- `AZURE_OPENAI_DEPLOYMENT_NAME` environment variable (defaults to "gpt-5.4-mini")
+
+## Running the Sample
+
+```bash
+dotnet run
+```
+
+## Expected Output
+
+The sample will show:
+1. QA Engineer running tests
+2. DevOps Engineer checking staging and creating rollback plan
+3. An approval request for production deployment
+4. Simulated approval response
+5. DevOps Engineer completing the deployment
+6. Workflow completion message
+
+## Related Samples
+
+- [Agent Function Tools with Approvals](../../../02-agents/Agents/Agent_Step01_UsingFunctionToolsWithApprovals) - Basic function approval pattern
+- [Agent Workflow Patterns](../../_StartHere/03_AgentWorkflowPatterns) - Group chat without approvals
+- [Human-in-the-Loop Basic](../../HumanInTheLoop/HumanInTheLoopBasic) - Workflow-level human interaction

dotnet/samples/03-workflows/Agents/WorkflowAsAnAgent/Program.cs

@@ -0,0 +1,97 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowAsAnAgentSample;
+
+/// <summary>
+/// This sample introduces the concept of workflows as agents, where a workflow can be
+/// treated as an <see cref="AIAgent"/>. This allows you to interact with a workflow
+/// as if it were a single agent.
+///
+/// In this example, we create a workflow that uses two language agents to process
+/// input concurrently, one that responds in French and another that responds in English.
+///
+/// You will interact with the workflow in an interactive loop, sending messages and receiving
+/// streaming responses from the workflow as if it were an agent who responds in both languages.
+///
+/// This sample also demonstrates <see cref="IResettableExecutor"/>, which is required
+/// for stateful executors that are shared across multiple workflow runs. Each iteration
+/// of the interactive loop triggers a new workflow run against the same workflow instance.
+/// Between runs, the framework automatically calls <see cref="IResettableExecutor.ResetAsync"/>
+/// on shared executors so that accumulated state (e.g., collected messages) is cleared
+/// before the next run begins. See <c>WorkflowFactory.ConcurrentAggregationExecutor</c>
+/// for the implementation.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - This sample uses concurrent processing.
+/// - An Azure OpenAI endpoint and deployment name.
+/// </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 the workflow and turn it into an agent
+        var workflow = WorkflowFactory.BuildWorkflow(aiProjectClient, deploymentName);
+        var agent = workflow.AsAIAgent("workflow-agent", "Workflow Agent");
+        var session = await agent.CreateSessionAsync();
+
+        // Start an interactive loop to interact with the workflow as if it were an agent.
+        // Each iteration runs the workflow again on the same workflow instance. Between runs,
+        // the framework calls IResettableExecutor.ResetAsync() on shared stateful executors
+        // (like ConcurrentAggregationExecutor) to clear accumulated state from the previous run.
+        while (true)
+        {
+            Console.WriteLine();
+            Console.Write("User (or 'exit' to quit): ");
+            string? input = Console.ReadLine();
+            if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+            {
+                break;
+            }
+
+            await ProcessInputAsync(agent, session, input);
+        }
+
+        // Helper method to process user input and display streaming responses. To display
+        // multiple interleaved responses correctly, we buffer updates by message ID and
+        // re-render all messages on each update.
+        static async Task ProcessInputAsync(AIAgent agent, AgentSession? session, string input)
+        {
+            Dictionary<string, List<AgentResponseUpdate>> buffer = [];
+            await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(input, session))
+            {
+                if (update.MessageId is null || string.IsNullOrEmpty(update.Text))
+                {
+                    // skip updates that don't have a message ID or text
+                    continue;
+                }
+
+                if (!buffer.TryGetValue(update.MessageId, out List<AgentResponseUpdate>? value))
+                {
+                    value = [];
+                    buffer[update.MessageId] = value;
+                }
+                value.Add(update);
+
+                foreach (var (messageId, segments) in buffer)
+                {
+                    string combinedText = string.Concat(segments);
+                    Console.WriteLine($"{segments[0].AuthorName}: {combinedText}");
+                    Console.WriteLine();
+                }
+            }
+        }
+    }
+}

dotnet/samples/03-workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj

@@ -0,0 +1,18 @@
+<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>
+
+</Project>

dotnet/samples/03-workflows/Agents/WorkflowAsAnAgent/WorkflowFactory.cs

@@ -0,0 +1,100 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowAsAnAgentSample;
+
+internal static class WorkflowFactory
+{
+    /// <summary>
+    /// Creates a workflow that uses two language agents to process input concurrently.
+    ///
+    /// In this workflow, the <c>Start</c> <see cref="ChatForwardingExecutor"/> and the
+    /// <see cref="ConcurrentAggregationExecutor"/> are provided as shared instances, meaning
+    /// the same executor objects are reused across multiple workflow runs. The language agents
+    /// (French and English) are created via a factory and instantiated per workflow run.
+    /// Stateful shared executors must implement <see cref="IResettableExecutor"/> so the
+    /// framework can clear their state between runs. Framework-provided executors like
+    /// <see cref="ChatForwardingExecutor"/> already implement this interface.
+    /// </summary>
+    /// <param name="client">The AI project client to use for the agents</param>
+    /// <param name="model">The model deployment name</param>
+    /// <returns>A workflow that processes input using two language agents</returns>
+    internal static Workflow BuildWorkflow(AIProjectClient client, string model)
+    {
+        // Create executors
+        var startExecutor = new ChatForwardingExecutor("Start");
+        var aggregationExecutor = new ConcurrentAggregationExecutor();
+        AIAgent frenchAgent = GetLanguageAgent("French", client, model);
+        AIAgent englishAgent = GetLanguageAgent("English", client, model);
+
+        // Build the workflow by adding executors and connecting them
+        return new WorkflowBuilder(startExecutor)
+            .AddFanOutEdge(startExecutor, [frenchAgent, englishAgent])
+            .AddFanInBarrierEdge([frenchAgent, englishAgent], aggregationExecutor)
+            .WithOutputFrom(aggregationExecutor)
+            .Build();
+    }
+
+    /// <summary>
+    /// Creates a language agent for the specified target language.
+    /// </summary>
+    /// <param name="targetLanguage">The target language for translation</param>
+    /// <param name="client">The AI project client to use for the agent</param>
+    /// <param name="model">The model deployment name</param>
+    /// <returns>A ChatClientAgent configured for the specified language</returns>
+    private static ChatClientAgent GetLanguageAgent(string targetLanguage, AIProjectClient client, string model) =>
+        client.AsAIAgent(model: model, instructions: $"You're a helpful assistant who always responds in {targetLanguage}.", name: $"{targetLanguage}Agent");
+
+    /// <summary>
+    /// Executor that aggregates the results from the concurrent agents.
+    ///
+    /// This executor is stateful — it accumulates messages in <see cref="_messages"/>
+    /// as they arrive from each agent. Because it is provided as a shared instance
+    /// (not via a factory), the same object is reused across workflow runs. Implementing
+    /// <see cref="IResettableExecutor"/> allows the framework to call <see cref="ResetAsync"/>
+    /// between runs, clearing accumulated state so each run starts fresh.
+    ///
+    /// Without <see cref="IResettableExecutor"/>, attempting to reuse a workflow containing
+    /// shared executor instances that do not implement this interface would throw an
+    /// <see cref="InvalidOperationException"/>.
+    /// </summary>
+    [YieldsOutput(typeof(string))]
+    private sealed class ConcurrentAggregationExecutor() :
+        Executor<List<ChatMessage>>("ConcurrentAggregationExecutor"), IResettableExecutor
+    {
+        private readonly List<ChatMessage> _messages = [];
+
+        /// <summary>
+        /// Handles incoming messages from the agents and aggregates their responses.
+        /// </summary>
+        /// <param name="message">The messages from the agent</param>
+        /// <param name="context">Workflow context for accessing workflow services and adding events</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
+        /// The default is <see cref="CancellationToken.None"/>.</param>
+        public override async ValueTask HandleAsync(List<ChatMessage> message, IWorkflowContext context, CancellationToken cancellationToken = default)
+        {
+            this._messages.AddRange(message);
+
+            if (this._messages.Count == 2)
+            {
+                var formattedMessages = string.Join(Environment.NewLine, this._messages.Select(m => $"{m.Text}"));
+                await context.YieldOutputAsync(formattedMessages, cancellationToken);
+            }
+        }
+
+        /// <summary>
+        /// Resets the executor state between workflow runs by clearing accumulated messages.
+        /// The framework calls this automatically when a workflow run completes, before the
+        /// workflow can be used for another run.
+        /// </summary>
+        public ValueTask ResetAsync()
+        {
+            this._messages.Clear();
+            return default;
+        }
+    }
+}

dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/CheckpointAndRehydrate.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/Program.cs

@@ -0,0 +1,119 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointAndRehydrateSample;
+
+/// <summary>
+/// This sample introduces the concepts of check points and shows how to save and restore
+/// the state of a workflow using checkpoints.
+/// This sample demonstrates checkpoints, which allow you to save and restore a workflow's state.
+/// Key concepts:
+/// - Super Steps: A workflow executes in stages called "super steps". Each super step runs
+///   one or more executors and completes when all those executors finish their work.
+/// - Checkpoints: The system automatically saves the workflow's state at the end of each
+///   super step. You can use these checkpoints to resume the workflow from any saved point.
+/// - Rehydration: You can rehydrate a new workflow instance from a saved checkpoint, allowing
+///   you to continue execution from that point.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Create the workflow
+        var workflow = WorkflowFactory.BuildWorkflow();
+
+        // Create checkpoint manager
+        var checkpointManager = CheckpointManager.Default;
+        var checkpoints = new List<CheckpointInfo>();
+
+        // Execute the workflow and save checkpoints
+        await using StreamingRun checkpointedRun = await InProcessExecution
+            .RunStreamingAsync(workflow, NumberSignal.Init, checkpointManager);
+
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case ExecutorCompletedEvent executorCompletedEvt:
+                    Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+                    break;
+
+                case SuperStepCompletedEvent superStepCompletedEvt:
+                {
+                    // Checkpoints are automatically created at the end of each super step when a
+                    // checkpoint manager is provided. You can store the checkpoint info for later use.
+                    CheckpointInfo? checkpoint = superStepCompletedEvt.CompletionInfo!.Checkpoint;
+                    if (checkpoint is not null)
+                    {
+                        checkpoints.Add(checkpoint);
+                        Console.WriteLine($"** Checkpoint created at step {checkpoints.Count}.");
+                    }
+
+                    break;
+                }
+
+                case WorkflowOutputEvent outputEvent:
+                    Console.WriteLine($"Workflow completed with result: {outputEvent.Data}");
+                    break;
+
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+
+        if (checkpoints.Count == 0)
+        {
+            throw new InvalidOperationException("No checkpoints were created during the workflow execution.");
+        }
+        Console.WriteLine($"Number of checkpoints created: {checkpoints.Count}");
+
+        // Rehydrate a new workflow instance from a saved checkpoint and continue execution
+        var newWorkflow = WorkflowFactory.BuildWorkflow();
+        const int CheckpointIndex = 5;
+        Console.WriteLine($"\n\nHydrating a new workflow instance from the {CheckpointIndex + 1}th checkpoint.");
+        CheckpointInfo savedCheckpoint = checkpoints[CheckpointIndex];
+
+        await using StreamingRun newCheckpointedRun =
+            await InProcessExecution.ResumeStreamingAsync(newWorkflow, savedCheckpoint, checkpointManager);
+
+        await foreach (WorkflowEvent evt in newCheckpointedRun.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case ExecutorCompletedEvent executorCompletedEvt:
+                    Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+                    break;
+
+                case WorkflowOutputEvent workflowOutputEvt:
+                    Console.WriteLine($"Workflow completed with result: {workflowOutputEvt.Data}");
+                    break;
+
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+    }
+}

dotnet/samples/03-workflows/Checkpoint/CheckpointAndRehydrate/WorkflowFactory.cs

@@ -0,0 +1,155 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointAndRehydrateSample;
+
+internal static class WorkflowFactory
+{
+    /// <summary>
+    /// Get a workflow that plays a number guessing game with checkpointing support.
+    /// The workflow consists of two executors that are connected in a feedback loop:
+    /// 1. GuessNumberExecutor: Makes a guess based on the current known bounds.
+    /// 2. JudgeExecutor: Evaluates the guess and provides feedback.
+    /// The workflow continues until the correct number is guessed.
+    /// </summary>
+    internal static Workflow BuildWorkflow()
+    {
+        // Create the executors
+        GuessNumberExecutor guessNumberExecutor = new(1, 100);
+        JudgeExecutor judgeExecutor = new(42);
+
+        // Build the workflow by connecting executors in a loop
+        return new WorkflowBuilder(guessNumberExecutor)
+            .AddEdge(guessNumberExecutor, judgeExecutor)
+            .AddEdge(judgeExecutor, guessNumberExecutor)
+            .WithOutputFrom(judgeExecutor)
+            .Build();
+    }
+}
+
+/// <summary>
+/// Signals used for communication between GuessNumberExecutor and JudgeExecutor.
+/// </summary>
+internal enum NumberSignal
+{
+    Init,
+    Above,
+    Below,
+}
+
+/// <summary>
+/// Executor that makes a guess based on the current bounds.
+/// </summary>
+[SendsMessage(typeof(int))]
+internal sealed class GuessNumberExecutor() : Executor<NumberSignal>("Guess")
+{
+    /// <summary>
+    /// The lower bound of the guessing range.
+    /// </summary>
+    public int LowerBound { get; private set; }
+
+    /// <summary>
+    /// The upper bound of the guessing range.
+    /// </summary>
+    public int UpperBound { get; private set; }
+
+    private const string StateKey = "GuessNumberExecutorState";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GuessNumberExecutor"/> class.
+    /// </summary>
+    /// <param name="lowerBound">The initial lower bound of the guessing range.</param>
+    /// <param name="upperBound">The initial upper bound of the guessing range.</param>
+    public GuessNumberExecutor(int lowerBound, int upperBound) : this()
+    {
+        this.LowerBound = lowerBound;
+        this.UpperBound = upperBound;
+    }
+
+    private int NextGuess => (this.LowerBound + this.UpperBound) / 2;
+
+    public override async ValueTask HandleAsync(NumberSignal message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        switch (message)
+        {
+            case NumberSignal.Init:
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+            case NumberSignal.Above:
+                this.UpperBound = this.NextGuess - 1;
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+            case NumberSignal.Below:
+                this.LowerBound = this.NextGuess + 1;
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+        }
+    }
+
+    /// <summary>
+    /// Checkpoint the current state of the executor.
+    /// This must be overridden to save any state that is needed to resume the executor.
+    /// </summary>
+    protected override ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        context.QueueStateUpdateAsync(StateKey, (this.LowerBound, this.UpperBound), cancellationToken: cancellationToken);
+
+    /// <summary>
+    /// Restore the state of the executor from a checkpoint.
+    /// This must be overridden to restore any state that was saved during checkpointing.
+    /// </summary>
+    protected override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        (this.LowerBound, this.UpperBound) = await context.ReadStateAsync<(int, int)>(StateKey, cancellationToken: cancellationToken);
+}
+
+/// <summary>
+/// Executor that judges the guess and provides feedback.
+/// </summary>
+[SendsMessage(typeof(NumberSignal))]
+[YieldsOutput(typeof(string))]
+internal sealed class JudgeExecutor() : Executor<int>("Judge")
+{
+    private readonly int _targetNumber;
+    private int _tries;
+    private const string StateKey = "JudgeExecutorState";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JudgeExecutor"/> class.
+    /// </summary>
+    /// <param name="targetNumber">The number to be guessed.</param>
+    public JudgeExecutor(int targetNumber) : this()
+    {
+        this._targetNumber = targetNumber;
+    }
+
+    public override async ValueTask HandleAsync(int message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._tries++;
+        if (message == this._targetNumber)
+        {
+            await context.YieldOutputAsync($"{this._targetNumber} found in {this._tries} tries!", cancellationToken: cancellationToken);
+        }
+        else if (message < this._targetNumber)
+        {
+            await context.SendMessageAsync(NumberSignal.Below, cancellationToken: cancellationToken);
+        }
+        else
+        {
+            await context.SendMessageAsync(NumberSignal.Above, cancellationToken: cancellationToken);
+        }
+    }
+
+    /// <summary>
+    /// Checkpoint the current state of the executor.
+    /// This must be overridden to save any state that is needed to resume the executor.
+    /// </summary>
+    protected override ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        context.QueueStateUpdateAsync(StateKey, this._tries, cancellationToken: cancellationToken);
+
+    /// <summary>
+    /// Restore the state of the executor from a checkpoint.
+    /// This must be overridden to restore any state that was saved during checkpointing.
+    /// </summary>
+    protected override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        this._tries = await context.ReadStateAsync<int>(StateKey, cancellationToken: cancellationToken);
+}

dotnet/samples/03-workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Checkpoint/CheckpointAndResume/Program.cs

@@ -0,0 +1,113 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointAndResumeSample;
+
+/// <summary>
+/// This sample introduces the concepts of check points and shows how to save and restore
+/// the state of a workflow using checkpoints.
+/// This sample demonstrates checkpoints, which allow you to save and restore a workflow's state.
+/// Key concepts:
+/// - Super Steps: A workflow executes in stages called "super steps". Each super step runs
+///   one or more executors and completes when all those executors finish their work.
+/// - Checkpoints: The system automatically saves the workflow's state at the end of each
+///   super step. You can use these checkpoints to resume the workflow from any saved point.
+/// - Resume: If needed, you can restore a checkpoint and continue execution from that state.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Create the workflow
+        var workflow = WorkflowFactory.BuildWorkflow();
+
+        // Create checkpoint manager
+        var checkpointManager = CheckpointManager.Default;
+        var checkpoints = new List<CheckpointInfo>();
+
+        // Execute the workflow and save checkpoints
+        await using StreamingRun checkpointedRun = await InProcessExecution.RunStreamingAsync(workflow, NumberSignal.Init, checkpointManager);
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case ExecutorCompletedEvent executorCompletedEvt:
+                    Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+                    break;
+
+                case SuperStepCompletedEvent superStepCompletedEvt:
+                {
+                    // Checkpoints are automatically created at the end of each super step when a
+                    // checkpoint manager is provided. You can store the checkpoint info for later use.
+                    CheckpointInfo? checkpoint = superStepCompletedEvt.CompletionInfo!.Checkpoint;
+                    if (checkpoint is not null)
+                    {
+                        checkpoints.Add(checkpoint);
+                        Console.WriteLine($"** Checkpoint created at step {checkpoints.Count}.");
+                    }
+
+                    break;
+                }
+
+                case WorkflowOutputEvent outputEvent:
+                    Console.WriteLine($"Workflow completed with result: {outputEvent.Data}");
+                    break;
+
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+
+        if (checkpoints.Count == 0)
+        {
+            throw new InvalidOperationException("No checkpoints were created during the workflow execution.");
+        }
+        Console.WriteLine($"Number of checkpoints created: {checkpoints.Count}");
+
+        // Restoring from a checkpoint and resuming execution
+        const int CheckpointIndex = 5;
+        Console.WriteLine($"\n\nRestoring from the {CheckpointIndex + 1}th checkpoint.");
+        CheckpointInfo savedCheckpoint = checkpoints[CheckpointIndex];
+        // Note that we are restoring the state directly to the same run instance.
+        await checkpointedRun.RestoreCheckpointAsync(savedCheckpoint, CancellationToken.None);
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case ExecutorCompletedEvent executorCompletedEvt:
+                    Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+                    break;
+
+                case WorkflowOutputEvent workflowOutputEvt:
+                    Console.WriteLine($"Workflow completed with result: {workflowOutputEvt.Data}");
+                    break;
+
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+    }
+}

dotnet/samples/03-workflows/Checkpoint/CheckpointAndResume/WorkflowFactory.cs

@@ -0,0 +1,155 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointAndResumeSample;
+
+internal static class WorkflowFactory
+{
+    /// <summary>
+    /// Get a workflow that plays a number guessing game with checkpointing support.
+    /// The workflow consists of two executors that are connected in a feedback loop:
+    /// 1. GuessNumberExecutor: Makes a guess based on the current known bounds.
+    /// 2. JudgeExecutor: Evaluates the guess and provides feedback.
+    /// The workflow continues until the correct number is guessed.
+    /// </summary>
+    internal static Workflow BuildWorkflow()
+    {
+        // Create the executors
+        GuessNumberExecutor guessNumberExecutor = new(1, 100);
+        JudgeExecutor judgeExecutor = new(42);
+
+        // Build the workflow by connecting executors in a loop
+        return new WorkflowBuilder(guessNumberExecutor)
+            .AddEdge(guessNumberExecutor, judgeExecutor)
+            .AddEdge(judgeExecutor, guessNumberExecutor)
+            .WithOutputFrom(judgeExecutor)
+            .Build();
+    }
+}
+
+/// <summary>
+/// Signals used for communication between GuessNumberExecutor and JudgeExecutor.
+/// </summary>
+internal enum NumberSignal
+{
+    Init,
+    Above,
+    Below,
+}
+
+/// <summary>
+/// Executor that makes a guess based on the current bounds.
+/// </summary>
+[SendsMessage(typeof(int))]
+internal sealed class GuessNumberExecutor() : Executor<NumberSignal>("Guess")
+{
+    /// <summary>
+    /// The lower bound of the guessing range.
+    /// </summary>
+    public int LowerBound { get; private set; }
+
+    /// <summary>
+    /// The upper bound of the guessing range.
+    /// </summary>
+    public int UpperBound { get; private set; }
+
+    private const string StateKey = "GuessNumberExecutorState";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GuessNumberExecutor"/> class.
+    /// </summary>
+    /// <param name="lowerBound">The initial lower bound of the guessing range.</param>
+    /// <param name="upperBound">The initial upper bound of the guessing range.</param>
+    public GuessNumberExecutor(int lowerBound, int upperBound) : this()
+    {
+        this.LowerBound = lowerBound;
+        this.UpperBound = upperBound;
+    }
+
+    private int NextGuess => (this.LowerBound + this.UpperBound) / 2;
+
+    public override async ValueTask HandleAsync(NumberSignal message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        switch (message)
+        {
+            case NumberSignal.Init:
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+            case NumberSignal.Above:
+                this.UpperBound = this.NextGuess - 1;
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+            case NumberSignal.Below:
+                this.LowerBound = this.NextGuess + 1;
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+        }
+    }
+
+    /// <summary>
+    /// Checkpoint the current state of the executor.
+    /// This must be overridden to save any state that is needed to resume the executor.
+    /// </summary>
+    protected override ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        context.QueueStateUpdateAsync(StateKey, (this.LowerBound, this.UpperBound), cancellationToken: cancellationToken);
+
+    /// <summary>
+    /// Restore the state of the executor from a checkpoint.
+    /// This must be overridden to restore any state that was saved during checkpointing.
+    /// </summary>
+    protected override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        (this.LowerBound, this.UpperBound) = await context.ReadStateAsync<(int, int)>(StateKey, cancellationToken: cancellationToken);
+}
+
+/// <summary>
+/// Executor that judges the guess and provides feedback.
+/// </summary>
+[SendsMessage(typeof(NumberSignal))]
+[YieldsOutput(typeof(string))]
+internal sealed class JudgeExecutor() : Executor<int>("Judge")
+{
+    private readonly int _targetNumber;
+    private int _tries;
+    private const string StateKey = "JudgeExecutorState";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JudgeExecutor"/> class.
+    /// </summary>
+    /// <param name="targetNumber">The number to be guessed.</param>
+    public JudgeExecutor(int targetNumber) : this()
+    {
+        this._targetNumber = targetNumber;
+    }
+
+    public override async ValueTask HandleAsync(int message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._tries++;
+        if (message == this._targetNumber)
+        {
+            await context.YieldOutputAsync($"{this._targetNumber} found in {this._tries} tries!", cancellationToken);
+        }
+        else if (message < this._targetNumber)
+        {
+            await context.SendMessageAsync(NumberSignal.Below, cancellationToken: cancellationToken);
+        }
+        else
+        {
+            await context.SendMessageAsync(NumberSignal.Above, cancellationToken: cancellationToken);
+        }
+    }
+
+    /// <summary>
+    /// Checkpoint the current state of the executor.
+    /// This must be overridden to save any state that is needed to resume the executor.
+    /// </summary>
+    protected override ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        context.QueueStateUpdateAsync(StateKey, this._tries, cancellationToken: cancellationToken);
+
+    /// <summary>
+    /// Restore the state of the executor from a checkpoint.
+    /// This must be overridden to restore any state that was saved during checkpointing.
+    /// </summary>
+    protected override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        this._tries = await context.ReadStateAsync<int>(StateKey, cancellationToken: cancellationToken);
+}

dotnet/samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/Program.cs

@@ -0,0 +1,153 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointWithHumanInTheLoopSample;
+
+/// <summary>
+/// This sample demonstrates how to create a workflow with human-in-the-loop interaction and
+/// checkpointing support. The workflow plays a number guessing game where the user provides
+/// guesses based on feedback from the workflow. The workflow state is checkpointed at the end
+/// of each super step, allowing it to be restored and resumed later.
+/// Each RequestPort request and response cycle takes two super steps:
+/// 1. The RequestPort sends a RequestInfoEvent to request input from the external world.
+/// 2. The external world sends a response back to the RequestPort.
+/// Thus, two checkpoints are created for each human-in-the-loop interaction.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - This sample builds upon the HumanInTheLoopBasic sample. It's recommended to go through that
+///   sample first to understand the basics of human-in-the-loop workflows.
+/// - This sample also builds upon the CheckpointAndResume sample. It's recommended to
+///   go through that sample first to understand the basics of checkpointing and resuming workflows.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Create the workflow
+        var workflow = WorkflowFactory.BuildWorkflow();
+
+        // Create checkpoint manager
+        var checkpointManager = CheckpointManager.Default;
+        var checkpoints = new List<CheckpointInfo>();
+
+        // Execute the workflow and save checkpoints
+        await using StreamingRun checkpointedRun = await InProcessExecution
+            .RunStreamingAsync(workflow, new SignalWithNumber(NumberSignal.Init), checkpointManager)
+            ;
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case RequestInfoEvent requestInputEvt:
+                    // Handle `RequestInfoEvent` from the workflow
+                    ExternalResponse response = HandleExternalRequest(requestInputEvt.Request);
+                    await checkpointedRun.SendResponseAsync(response);
+                    break;
+                case ExecutorCompletedEvent executorCompletedEvt:
+                    Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+                    break;
+                case SuperStepCompletedEvent superStepCompletedEvt:
+                    // Checkpoints are automatically created at the end of each super step when a
+                    // checkpoint manager is provided. You can store the checkpoint info for later use.
+                    CheckpointInfo? checkpoint = superStepCompletedEvt.CompletionInfo!.Checkpoint;
+                    if (checkpoint is not null)
+                    {
+                        checkpoints.Add(checkpoint);
+                        Console.WriteLine($"** Checkpoint created at step {checkpoints.Count}.");
+                    }
+                    break;
+                case WorkflowOutputEvent workflowOutputEvt:
+                    Console.WriteLine($"Workflow completed with result: {workflowOutputEvt.Data}");
+                    break;
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+
+        if (checkpoints.Count == 0)
+        {
+            throw new InvalidOperationException("No checkpoints were created during the workflow execution.");
+        }
+        Console.WriteLine($"Number of checkpoints created: {checkpoints.Count}");
+
+        // Restoring from a checkpoint and resuming execution
+        const int CheckpointIndex = 1;
+        Console.WriteLine($"\n\nRestoring from the {CheckpointIndex + 1}th checkpoint.");
+        CheckpointInfo savedCheckpoint = checkpoints[CheckpointIndex];
+        // Note that we are restoring the state directly to the same run instance.
+        await checkpointedRun.RestoreCheckpointAsync(savedCheckpoint, CancellationToken.None);
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case RequestInfoEvent requestInputEvt:
+                    // Handle `RequestInfoEvent` from the workflow
+                    ExternalResponse response = HandleExternalRequest(requestInputEvt.Request);
+                    await checkpointedRun.SendResponseAsync(response);
+                    break;
+                case ExecutorCompletedEvent executorCompletedEvt:
+                    Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+                    break;
+                case WorkflowOutputEvent workflowOutputEvt:
+                    Console.WriteLine($"Workflow completed with result: {workflowOutputEvt.Data}");
+                    break;
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+    }
+
+    private static ExternalResponse HandleExternalRequest(ExternalRequest request)
+    {
+        if (request.TryGetDataAs<SignalWithNumber>(out var signal))
+        {
+            switch (signal.Signal)
+            {
+                case NumberSignal.Init:
+                    int initialGuess = ReadIntegerFromConsole("Please provide your initial guess: ");
+                    return request.CreateResponse(initialGuess);
+                case NumberSignal.Above:
+                    int lowerGuess = ReadIntegerFromConsole($"You previously guessed {signal.Number} too large. Please provide a new guess: ");
+                    return request.CreateResponse(lowerGuess);
+                case NumberSignal.Below:
+                    int higherGuess = ReadIntegerFromConsole($"You previously guessed {signal.Number} too small. Please provide a new guess: ");
+                    return request.CreateResponse(higherGuess);
+            }
+        }
+
+        throw new NotSupportedException($"Request {request.PortInfo.RequestType} is not supported");
+    }
+
+    private static int ReadIntegerFromConsole(string prompt)
+    {
+        while (true)
+        {
+            Console.Write(prompt);
+            string? input = Console.ReadLine();
+            if (int.TryParse(input, out int value))
+            {
+                return value;
+            }
+            Console.WriteLine("Invalid input. Please enter a valid integer.");
+        }
+    }
+}

dotnet/samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/WorkflowFactory.cs

@@ -0,0 +1,103 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointWithHumanInTheLoopSample;
+
+internal static class WorkflowFactory
+{
+    /// <summary>
+    /// Get a workflow that plays a number guessing game with human-in-the-loop interaction.
+    /// An input port allows the external world to provide inputs to the workflow upon requests.
+    /// </summary>
+    internal static Workflow BuildWorkflow()
+    {
+        // Create the executors
+        RequestPort numberRequest = RequestPort.Create<SignalWithNumber, int>("GuessNumber");
+        JudgeExecutor judgeExecutor = new(42);
+
+        // Build the workflow by connecting executors in a loop
+        return new WorkflowBuilder(numberRequest)
+            .AddEdge(numberRequest, judgeExecutor)
+            .AddEdge(judgeExecutor, numberRequest)
+            .WithOutputFrom(judgeExecutor)
+            .Build();
+    }
+}
+
+/// <summary>
+/// Signals indicating if the guess was too high, too low, or an initial guess.
+/// </summary>
+internal enum NumberSignal
+{
+    Init,
+    Above,
+    Below,
+}
+
+/// <summary>
+/// Signals used for communication between guesses and the JudgeExecutor.
+/// </summary>
+internal sealed class SignalWithNumber
+{
+    public NumberSignal Signal { get; }
+    public int? Number { get; }
+
+    public SignalWithNumber(NumberSignal signal, int? number = null)
+    {
+        this.Signal = signal;
+        this.Number = number;
+    }
+}
+
+/// <summary>
+/// Executor that judges the guess and provides feedback.
+/// </summary>
+[SendsMessage(typeof(SignalWithNumber))]
+[YieldsOutput(typeof(string))]
+internal sealed class JudgeExecutor() : Executor<int>("Judge")
+{
+    private readonly int _targetNumber;
+    private int _tries;
+    private const string StateKey = "JudgeExecutorState";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JudgeExecutor"/> class.
+    /// </summary>
+    /// <param name="targetNumber">The number to be guessed.</param>
+    public JudgeExecutor(int targetNumber) : this()
+    {
+        this._targetNumber = targetNumber;
+    }
+
+    public override async ValueTask HandleAsync(int message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._tries++;
+        if (message == this._targetNumber)
+        {
+            await context.YieldOutputAsync($"{this._targetNumber} found in {this._tries} tries!", cancellationToken);
+        }
+        else if (message < this._targetNumber)
+        {
+            await context.SendMessageAsync(new SignalWithNumber(NumberSignal.Below, message), cancellationToken: cancellationToken);
+        }
+        else
+        {
+            await context.SendMessageAsync(new SignalWithNumber(NumberSignal.Above, message), cancellationToken: cancellationToken);
+        }
+    }
+
+    /// <summary>
+    /// Checkpoint the current state of the executor.
+    /// This must be overridden to save any state that is needed to resume the executor.
+    /// </summary>
+    protected override ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        context.QueueStateUpdateAsync(StateKey, this._tries, cancellationToken: cancellationToken);
+
+    /// <summary>
+    /// Restore the state of the executor from a checkpoint.
+    /// This must be overridden to restore any state that was saved during checkpointing.
+    /// </summary>
+    protected override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        this._tries = await context.ReadStateAsync<int>(StateKey, cancellationToken: cancellationToken);
+}

dotnet/samples/03-workflows/Concurrent/Concurrent/Concurrent.csproj

@@ -0,0 +1,27 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <!-- Include Workflows source generator when using [MessageHandler] attribute -->
+    <ProjectReference Include="$(RepoRoot)/dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false"
+                      GlobalPropertiesToRemove="TargetFramework" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Concurrent/Concurrent/Program.cs

@@ -0,0 +1,161 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowConcurrentSample;
+
+/// <summary>
+/// This sample introduces concurrent execution using "fan-out" and "fan-in" patterns.
+///
+/// Unlike sequential workflows where executors run one after another, this workflow
+/// runs multiple executors in parallel to process the same input simultaneously.
+///
+/// The workflow structure:
+/// 1. StartExecutor sends the same question to two AI agents concurrently (fan-out)
+/// 2. Physicist Agent and Chemist Agent answer independently and in parallel
+/// 3. AggregationExecutor collects both responses and combines them (fan-in)
+///
+/// This pattern is useful when you want multiple perspectives on the same input,
+/// or when you can break work into independent parallel tasks for better performance.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - An Azure OpenAI chat completion deployment must be configured.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Set up the Azure AI Project 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";
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        var chatClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+                            .ProjectOpenAIClient.GetChatClient(deploymentName).AsIChatClient();
+
+        // Create the executors
+        var physicist = new ChatClientAgent(
+            chatClient,
+            name: "Physicist",
+            instructions: "You are an expert in physics. You answer questions from a physics perspective."
+        ).BindAsExecutor(new AIAgentHostOptions { ForwardIncomingMessages = false });
+
+        var chemist = new ChatClientAgent(
+            chatClient,
+            name: "Chemist",
+            instructions: "You are an expert in chemistry. You answer questions from a chemistry perspective."
+        ).BindAsExecutor(new AIAgentHostOptions { ForwardIncomingMessages = false });
+
+        var startExecutor = new ConcurrentStartExecutor();
+        var aggregationExecutor = new ConcurrentAggregationExecutor();
+
+        // Build the workflow by adding executors and connecting them
+        var workflow = new WorkflowBuilder(startExecutor)
+            .AddFanOutEdge(startExecutor, [physicist, chemist])
+            .AddFanInBarrierEdge([physicist, chemist], aggregationExecutor)
+            .WithOutputFrom(aggregationExecutor)
+            .Build();
+
+        // Execute the workflow in streaming mode
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input: "What is temperature?");
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case WorkflowOutputEvent workflowOutput:
+                    Console.WriteLine($"Workflow completed with results:\n{workflowOutput.Data}");
+                    break;
+
+                case WorkflowErrorEvent workflowError:
+                    WriteError(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred");
+                    break;
+
+                case ExecutorFailedEvent executorFailed:
+                    WriteError($"Executor '{executorFailed.ExecutorId}' failed with {(
+                        executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}"
+                        )}.");
+                    break;
+            }
+        }
+
+        void WriteError(string error)
+        {
+            Console.ForegroundColor = ConsoleColor.Red;
+            Console.Write(error);
+            Console.ResetColor();
+        }
+    }
+}
+
+/// <summary>
+/// Executor that starts the concurrent processing by sending messages to the agents.
+/// </summary>
+[SendsMessage(typeof(ChatMessage))]
+[SendsMessage(typeof(TurnToken))]
+internal sealed partial class ConcurrentStartExecutor() :
+    Executor("ConcurrentStartExecutor")
+{
+    /// <summary>
+    /// Starts the concurrent processing by sending messages to the agents.
+    /// </summary>
+    /// <param name="message">The user message to process</param>
+    /// <param name="context">Workflow context for accessing workflow services and adding events</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
+    /// The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task representing the asynchronous operation</returns>
+    [MessageHandler]
+    public async ValueTask HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Broadcast the message to all connected agents. Receiving agents will queue
+        // the message but will not start processing until they receive a turn token.
+        await context.SendMessageAsync(new ChatMessage(ChatRole.User, message), cancellationToken: cancellationToken);
+        // Broadcast the turn token to kick off the agents.
+        await context.SendMessageAsync(new TurnToken(emitEvents: false), cancellationToken: cancellationToken);
+    }
+}
+
+/// <summary>
+/// Executor that aggregates the results from the concurrent agents.
+/// </summary>
+[YieldsOutput(typeof(string))]
+internal sealed partial class ConcurrentAggregationExecutor() :
+    Executor<List<ChatMessage>>("ConcurrentAggregationExecutor")
+{
+    private readonly List<ChatMessage> _messages = [];
+
+    /// <summary>
+    /// Handles incoming messages from the agents and aggregates their responses.
+    /// </summary>
+    /// <param name="message">The messages from the agent</param>
+    /// <param name="context">Workflow context for accessing workflow services and adding events</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
+    /// The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task representing the asynchronous operation</returns>
+    public override async ValueTask HandleAsync(List<ChatMessage> message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._messages.AddRange(message);
+    }
+
+    protected override ValueTask OnMessageDeliveryFinishedAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        StringBuilder resultBuilder = new();
+        foreach (ChatMessage m in this._messages)
+        {
+            resultBuilder.AppendLine($"{m.AuthorName}: {m.Text}");
+            resultBuilder.AppendLine();
+        }
+
+        this._messages.Clear();
+
+        return context.YieldOutputAsync(resultBuilder.ToString(), cancellationToken);
+    }
+}

dotnet/samples/03-workflows/Concurrent/MapReduce/MapReduce.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Concurrent/MapReduce/Program.cs

@@ -0,0 +1,435 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowMapReduceSample;
+
+/// <summary>
+/// Sample: Map-Reduce Word Count with Fan-Out and Fan-In over File-Backed Intermediate Results
+///
+/// The workflow splits a large text into chunks, maps words to counts in parallel,
+/// shuffles intermediate pairs to reducers, then reduces to per-word totals.
+/// It also demonstrates workflow visualization for graph visualization.
+///
+/// Purpose:
+/// Show how to:
+/// - Partition input once and coordinate parallel mappers with shared state.
+/// - Implement map, shuffle, and reduce executors that pass file paths instead of large payloads.
+/// - Use fan-out and fan-in edges to express parallelism and joins.
+/// - Persist intermediate results to disk to bound memory usage for large inputs.
+/// - Visualize the workflow graph using ToDotString and ToMermaidString and export to SVG.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Write access to a temp directory.
+/// - A source text file to process.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        Workflow workflow = BuildWorkflow();
+        await RunWorkflowAsync(workflow);
+    }
+
+    /// <summary>
+    /// Builds a map-reduce workflow using a fan-out/fan-in pattern with mappers, reducers, and other executors.
+    /// </summary>
+    /// <remarks>This method constructs a workflow consisting of multiple stages, including splitting,
+    /// mapping, shuffling, reducing, and completion. The workflow is designed to process data in parallel using a
+    /// fan-out/fan-in architecture. The resulting workflow is ready for execution and includes all necessary
+    /// dependencies between the executors.</remarks>
+    /// <returns>A <see cref="Workflow"/> instance representing the constructed workflow.</returns>
+    public static Workflow BuildWorkflow()
+    {
+        // Step 1: Create the mappers and the input splitter
+        var mappers = Enumerable.Range(0, 3).Select(i => new Mapper($"map_executor_{i}")).ToArray();
+        var splitter = new Split(mappers.Select(m => m.Id).ToArray(), "split_data_executor");
+
+        // Step 2: Create the reducers and the intermidiace shuffler
+        var reducers = Enumerable.Range(0, 4).Select(i => new Reducer($"reduce_executor_{i}")).ToArray();
+        var shuffler = new Shuffler(reducers.Select(r => r.Id).ToArray(), mappers.Select(m => m.Id).ToArray(), "shuffle_executor");
+
+        // Step 3: Create the output manager
+        var completion = new CompletionExecutor("completion_executor");
+
+        // Step 4: Build the concurrent workflow with fan-out/fan-in pattern
+        return new WorkflowBuilder(splitter)
+            .AddFanOutEdge(splitter, [.. mappers])         // Split -> many mappers
+            .AddFanInBarrierEdge([.. mappers], shuffler)          // All mappers -> shuffle
+            .AddFanOutEdge(shuffler, [.. reducers])        // Shuffle -> many reducers
+            .AddFanInBarrierEdge([.. reducers], completion)       // All reducers -> completion
+            .WithOutputFrom(completion)
+            .Build();
+    }
+
+    /// <summary>
+    /// Executes the specified workflow asynchronously using a predefined input text and processes its output events.
+    /// </summary>
+    /// <remarks>This method reads input text from a file located in the "resources" directory. If the file is
+    /// not found,  a default sample text is used. The workflow is executed with the input text, and its events are
+    /// streamed  and processed in real-time. If the workflow produces output files, their paths and contents are
+    /// displayed.</remarks>
+    /// <param name="workflow">The workflow to execute. This defines the sequence of operations to be performed.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    private static async Task RunWorkflowAsync(Workflow workflow)
+    {
+        // Step 1: Read the input text
+        var resourcesPath = Path.Combine(Directory.GetCurrentDirectory(), "..", "..", "..", "..", "resources");
+        var textFilePath = Path.Combine(resourcesPath, "long_text.txt");
+
+        string rawText;
+        if (File.Exists(textFilePath))
+        {
+            rawText = await File.ReadAllTextAsync(textFilePath);
+        }
+        else
+        {
+            // Use sample text if file doesn't exist
+            Console.WriteLine($"Note: {textFilePath} not found, using sample text");
+            rawText = "The quick brown fox jumps over the lazy dog. The dog was very lazy. The fox was very quick.";
+        }
+
+        // Step 2: Run the workflow
+        Console.WriteLine("\n=== RUNNING WORKFLOW ===\n");
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input: rawText);
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            Console.WriteLine($"Event: {evt}");
+            if (evt is WorkflowOutputEvent outputEvent)
+            {
+                Console.WriteLine("\nFinal Output Files:");
+                if (outputEvent.Data is List<string> filePaths)
+                {
+                    foreach (var filePath in filePaths)
+                    {
+                        Console.WriteLine($"  - {filePath}");
+                        if (File.Exists(filePath))
+                        {
+                            var content = await File.ReadAllTextAsync(filePath);
+                            Console.WriteLine($"    Contents:\n{content}");
+                        }
+                    }
+                }
+            }
+            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();
+            }
+        }
+    }
+}
+
+#region Executors
+
+/// <summary>
+/// Splits data into roughly equal chunks based on the number of mapper nodes.
+/// </summary>
+[SendsMessage(typeof(SplitComplete))]
+internal sealed class Split(string[] mapperIds, string id) :
+    Executor<string>(id)
+{
+    private readonly string[] _mapperIds = mapperIds;
+    private static readonly string[] s_lineSeparators = ["\r\n", "\r", "\n"];
+
+    /// <summary>
+    /// Tokenize input and assign contiguous index ranges to each mapper via shared state.
+    /// </summary>
+    public override async ValueTask HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Ensure temp directory exists
+        Directory.CreateDirectory(MapReduceConstants.TempDir);
+
+        // Process the data into a list of words and remove any empty lines
+        var wordList = Preprocess(message);
+
+        // Store the tokenized words once so that all mappers can read by index
+        await context.QueueStateUpdateAsync(MapReduceConstants.DataToProcessKey, wordList, scopeName: MapReduceConstants.StateScope, cancellationToken);
+
+        // Divide indices into contiguous slices for each mapper
+        var mapperCount = this._mapperIds.Length;
+        var chunkSize = wordList.Length / mapperCount;
+
+        async Task ProcessChunkAsync(int i)
+        {
+            // Determine the start and end indices for this mapper's chunk
+            var startIndex = i * chunkSize;
+            var endIndex = i < mapperCount - 1 ? startIndex + chunkSize : wordList.Length;
+
+            // Save the indices under the mapper's Id
+            await context.QueueStateUpdateAsync(this._mapperIds[i], (startIndex, endIndex), scopeName: MapReduceConstants.StateScope, cancellationToken);
+
+            // Notify the mapper that data is ready
+            await context.SendMessageAsync(new SplitComplete(), targetId: this._mapperIds[i], cancellationToken);
+        }
+
+        // Process all the chunks
+        var tasks = Enumerable.Range(0, mapperCount).Select(ProcessChunkAsync);
+        await Task.WhenAll(tasks);
+    }
+
+    private static string[] Preprocess(string data)
+    {
+        var lines = data.Split(s_lineSeparators, StringSplitOptions.RemoveEmptyEntries)
+            .Select(line => line.Trim())
+            .Where(line => !string.IsNullOrWhiteSpace(line));
+
+        return lines
+            .SelectMany(line => line.Split(' ', StringSplitOptions.RemoveEmptyEntries))
+            .Where(word => !string.IsNullOrWhiteSpace(word))
+            .ToArray();
+    }
+}
+
+/// <summary>
+/// Maps each token to a count of 1 and writes pairs to a per-mapper file.
+/// </summary>
+[SendsMessage(typeof(MapComplete))]
+internal sealed class Mapper(string id) : Executor<SplitComplete>(id)
+{
+    /// <summary>
+    /// Read the assigned slice, emit (word, 1) pairs, and persist to disk.
+    /// </summary>
+    public override async ValueTask HandleAsync(SplitComplete message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        var dataToProcess = await context.ReadStateAsync<string[]>(MapReduceConstants.DataToProcessKey, scopeName: MapReduceConstants.StateScope, cancellationToken);
+        var chunk = await context.ReadStateAsync<(int start, int end)>(this.Id, scopeName: MapReduceConstants.StateScope, cancellationToken);
+
+        var results = dataToProcess![chunk.start..chunk.end]
+            .Select(word => (word, 1))
+            .ToArray();
+
+        // Write this mapper's results as simple text lines for easy debugging
+        var filePath = Path.Combine(MapReduceConstants.TempDir, $"map_results_{this.Id}.txt");
+        var lines = results.Select(r => $"{r.word}: {r.Item2}");
+        await File.WriteAllLinesAsync(filePath, lines, cancellationToken);
+
+        await context.SendMessageAsync(new MapComplete(filePath), cancellationToken: cancellationToken);
+    }
+}
+
+/// <summary>
+/// Groups intermediate pairs by key and partitions them across reducers.
+/// </summary>
+[SendsMessage(typeof(ShuffleComplete))]
+internal sealed class Shuffler(string[] reducerIds, string[] mapperIds, string id) :
+    Executor<MapComplete>(id)
+{
+    private readonly string[] _reducerIds = reducerIds;
+    private readonly string[] _mapperIds = mapperIds;
+    private readonly List<MapComplete> _mapResults = [];
+
+    /// <summary>
+    /// Aggregate mapper outputs and write one partition file per reducer.
+    /// </summary>
+    public override async ValueTask HandleAsync(MapComplete message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._mapResults.Add(message);
+
+        // Wait for all mappers to complete
+        if (this._mapResults.Count < this._mapperIds.Length)
+        {
+            return;
+        }
+
+        var chunks = await this.PreprocessAsync(this._mapResults);
+
+        async Task ProcessChunkAsync(List<(string key, List<int> values)> chunk, int index)
+        {
+            // Write one grouped partition for reducer index and notify that reducer
+            var filePath = Path.Combine(MapReduceConstants.TempDir, $"shuffle_results_{index}.txt");
+            var lines = chunk.Select(kvp => $"{kvp.key}: {JsonSerializer.Serialize(kvp.values)}");
+            await File.WriteAllLinesAsync(filePath, lines, cancellationToken);
+
+            await context.SendMessageAsync(new ShuffleComplete(filePath, this._reducerIds[index]), cancellationToken: cancellationToken);
+        }
+
+        var tasks = chunks.Select((chunk, i) => ProcessChunkAsync(chunk, i));
+        await Task.WhenAll(tasks);
+    }
+
+    /// <summary>
+    /// Load all mapper files, group by key, sort keys, and partition for reducers.
+    /// </summary>
+    private async Task<List<List<(string key, List<int> values)>>> PreprocessAsync(List<MapComplete> data)
+    {
+        // Load all intermediate pairs
+        var mapResults = new List<(string key, int value)>();
+        foreach (var result in data)
+        {
+            var lines = await File.ReadAllLinesAsync(result.FilePath);
+            foreach (var line in lines)
+            {
+                var parts = line.Split(": ");
+                if (parts.Length == 2)
+                {
+                    mapResults.Add((parts[0], int.Parse(parts[1])));
+                }
+            }
+        }
+
+        // Group values by token
+        var intermediateResults = mapResults
+            .GroupBy(r => r.key)
+            .ToDictionary(g => g.Key, g => g.Select(r => r.value).ToList());
+
+        // Deterministic ordering helps with debugging and test stability
+        var aggregatedResults = intermediateResults
+            .Select(kvp => (key: kvp.Key, values: kvp.Value))
+            .OrderBy(x => x.key)
+            .ToList();
+
+        // Partition keys across reducers as evenly as possible
+        var reduceExecutorCount = this._reducerIds.Length; // Use actual number of reducers
+        if (reduceExecutorCount == 0)
+        {
+            reduceExecutorCount = 1;
+        }
+
+        var chunkSize = aggregatedResults.Count / reduceExecutorCount;
+        var remaining = aggregatedResults.Count % reduceExecutorCount;
+
+        var chunks = new List<List<(string key, List<int> values)>>();
+        for (int i = 0; i < aggregatedResults.Count - remaining; i += chunkSize)
+        {
+            chunks.Add(aggregatedResults.GetRange(i, chunkSize));
+        }
+
+        if (remaining > 0 && chunks.Count > 0)
+        {
+            chunks[^1].AddRange(aggregatedResults.TakeLast(remaining));
+        }
+        else if (chunks.Count == 0)
+        {
+            chunks.Add(aggregatedResults);
+        }
+
+        return chunks;
+    }
+}
+
+/// <summary>
+/// Sums grouped counts per key for its assigned partition.
+/// </summary>
+[SendsMessage(typeof(ReduceComplete))]
+internal sealed class Reducer(string id) : Executor<ShuffleComplete>(id)
+{
+    /// <summary>
+    /// Read one shuffle partition and reduce it to totals.
+    /// </summary>
+    public override async ValueTask HandleAsync(ShuffleComplete message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        if (message.ReducerId != this.Id)
+        {
+            // This partition belongs to a different reducer. Skip.
+            return;
+        }
+
+        // Read grouped values from the shuffle output
+        var lines = await File.ReadAllLinesAsync(message.FilePath, cancellationToken);
+
+        // Sum values per key. Values are serialized JSON arrays like [1, 1, ...]
+        var reducedResults = new Dictionary<string, int>();
+        foreach (var line in lines)
+        {
+            var parts = line.Split(": ", 2);
+            if (parts.Length == 2)
+            {
+                var key = parts[0];
+                var values = JsonSerializer.Deserialize<List<int>>(parts[1]);
+                reducedResults[key] = values?.Sum() ?? 0;
+            }
+        }
+
+        // Persist our partition totals
+        var filePath = Path.Combine(MapReduceConstants.TempDir, $"reduced_results_{this.Id}.txt");
+        var outputLines = reducedResults.Select(kvp => $"{kvp.Key}: {kvp.Value}");
+        await File.WriteAllLinesAsync(filePath, outputLines, cancellationToken);
+
+        await context.SendMessageAsync(new ReduceComplete(filePath), cancellationToken: cancellationToken);
+    }
+}
+
+/// <summary>
+/// Joins all reducer outputs and yields the final output.
+/// </summary>
+[YieldsOutput(typeof(List<string>))]
+internal sealed class CompletionExecutor(string id) :
+    Executor<List<ReduceComplete>>(id)
+{
+    /// <summary>
+    /// Collect reducer output file paths and yield final output.
+    /// </summary>
+    public override async ValueTask HandleAsync(List<ReduceComplete> message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        var filePaths = message.ConvertAll(r => r.FilePath);
+        await context.YieldOutputAsync(filePaths, cancellationToken);
+    }
+}
+
+#endregion
+
+#region Events
+
+/// <summary>
+/// Marker event published when splitting finishes. Triggers map executors.
+/// </summary>
+internal sealed class SplitComplete : WorkflowEvent;
+
+/// <summary>
+/// Signal that a mapper wrote its intermediate pairs to file.
+/// </summary>
+internal sealed class MapComplete(string FilePath) : WorkflowEvent
+{
+    public string FilePath { get; } = FilePath;
+}
+
+/// <summary>
+/// Signal that a shuffle partition file is ready for a specific reducer.
+/// </summary>
+internal sealed class ShuffleComplete(string FilePath, string ReducerId) : WorkflowEvent
+{
+    public string FilePath { get; } = FilePath;
+    public string ReducerId { get; } = ReducerId;
+}
+
+/// <summary>
+/// Signal that a reducer wrote final counts for its partition.
+/// </summary>
+internal sealed class ReduceComplete(string FilePath) : WorkflowEvent
+{
+    public string FilePath { get; } = FilePath;
+}
+
+#endregion
+
+#region Helpers
+
+/// <summary>
+/// Provides constant values used in the MapReduce workflow.
+/// </summary>
+/// <remarks>This class contains keys and paths that are utilized throughout the MapReduce process, including
+/// identifiers for data processing and temporary storage locations.</remarks>
+internal static class MapReduceConstants
+{
+    public static string DataToProcessKey = "data_to_be_processed";
+    public static string TempDir = Path.Combine(Path.GetTempPath(), "workflow_viz_sample");
+    public static string StateScope = "MapReduceState";
+}
+
+#endregion

dotnet/samples/03-workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj

@@ -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>

dotnet/samples/03-workflows/ConditionalEdges/01_EdgeCondition/Program.cs

@@ -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.");
+        }
+    }
+}

dotnet/samples/03-workflows/ConditionalEdges/01_EdgeCondition/Resources.cs

@@ -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));
+}

dotnet/samples/03-workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj

@@ -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>

dotnet/samples/03-workflows/ConditionalEdges/02_SwitchCase/Program.cs

@@ -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.");
+        }
+    }
+}

dotnet/samples/03-workflows/ConditionalEdges/02_SwitchCase/Resources.cs

@@ -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));
+}

dotnet/samples/03-workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj

@@ -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>

dotnet/samples/03-workflows/ConditionalEdges/03_MultiSelection/Program.cs

@@ -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);
+    }
+}

dotnet/samples/03-workflows/ConditionalEdges/03_MultiSelection/Resources.cs

@@ -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));
+}

dotnet/samples/03-workflows/Declarative/AotCheckpointing/AotCheckpointing.csproj

@@ -0,0 +1,48 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <!--
+    Simulate an AOT / trim-aggressive deployment by disabling System.Text.Json's
+    implicit reflection fallback. When this flag is false, any JSON operation in
+    the process must resolve type info via a source-generated JsonSerializerContext
+    or fail at runtime (the checkpoint pipeline surfaces this as
+    InvalidOperationException: "No JSON type info is available for type 'X'").
+    This is the same constraint that 'dotnet publish -p:PublishAot=true' imposes,
+    observed without requiring a full AOT publish.
+  -->
+  <PropertyGroup>
+    <JsonSerializerIsReflectionEnabledByDefault>false</JsonSerializerIsReflectionEnabledByDefault>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="AotCheckpointing.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/AotCheckpointing/AotCheckpointing.yaml

@@ -0,0 +1,38 @@
+#
+# This workflow has three discrete actions so each runs in a distinct
+# superstep, making the checkpoint progression easy to follow.
+#
+# 1. SetVariable: capture the user input
+# 2. InvokeAzureAgent: greet the user via an Azure agent (autoSend on)
+# 3. SendActivity: emit a closing message
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_aot_demo
+  actions:
+
+    # Capture the user's input
+    - kind: SetVariable
+      id: set_input
+      variable: Local.UserInput
+      value: =System.LastMessage.Text
+
+    # Invoke the greeting agent and stream the response to the user
+    - kind: InvokeAzureAgent
+      id: invoke_greeter
+      conversationId: =System.ConversationId
+      agent:
+        name: GreeterAgent
+      input:
+        messages: =Local.UserInput
+      output:
+        messages: Local.GreeterResponse
+        autoSend: true
+
+    # Emit a closing activity so there is a clear final superstep
+    - kind: SendActivity
+      id: send_summary
+      activity: |-
+        [Sample] Workflow completed. Checkpoints persisted to disk.

dotnet/samples/03-workflows/Declarative/AotCheckpointing/Program.cs

@@ -0,0 +1,174 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Agents.AI.Workflows.Checkpointing;
+using Microsoft.Agents.AI.Workflows.Declarative;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.AotCheckpointing;
+
+/// <summary>
+/// Demonstrates JSON checkpointing of a declarative workflow under reflection-disabled
+/// <see cref="System.Text.Json.JsonSerializer"/> (the AOT / trim-aggressive constraint set
+/// via <c>JsonSerializerIsReflectionEnabledByDefault=false</c> in the csproj).
+/// </summary>
+/// <remarks>
+/// The key call is <see cref="CheckpointManager.CreateJson(ICheckpointStore{System.Text.Json.JsonElement}, System.Text.Json.JsonSerializerOptions?)"/>
+/// with <see cref="DeclarativeWorkflowJsonOptions.Default"/>. Drop the options argument to observe the AOT failure. See README.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        await CreateGreeterAgentAsync(foundryEndpoint, configuration);
+
+        string workflowInput = Application.GetInput(args);
+
+        Workflow CreateWorkflow()
+        {
+            AzureAgentProvider agentProvider = new(foundryEndpoint, new AzureCliCredential());
+            DeclarativeWorkflowOptions options = new(agentProvider) { Configuration = configuration };
+            string workflowPath = Path.Combine(AppContext.BaseDirectory, "AotCheckpointing.yaml");
+            return DeclarativeWorkflowBuilder.Build<string>(workflowPath, options);
+        }
+
+        DirectoryInfo checkpointFolder = Directory.CreateDirectory(Path.Combine(".", $"chk-{DateTime.Now:yyMMdd-HHmmss-ff}"));
+        try
+        {
+            using FileSystemJsonCheckpointStore store = new(checkpointFolder);
+
+            // KEY LINE: AOT-safe checkpoint manager. Drop the options argument to see the failure.
+            CheckpointManager checkpointManager = CheckpointManager.CreateJson(store, DeclarativeWorkflowJsonOptions.Default);
+
+            Console.WriteLine($"\nCheckpoint folder: {checkpointFolder.FullName}");
+
+            // Phase 1: run + drain. Every [checkpoint x<n>] line is a successful JSON WRITE.
+            List<CheckpointInfo> checkpoints = await RunAndStreamAsync(CreateWorkflow(), workflowInput, checkpointManager).ConfigureAwait(false);
+
+            // Phase 2: prove the JSON READ path. ResumeStreamingAsync deserializes the checkpoint
+            // inside the call; a clean return is the proof. We do not drain the resumed run because
+            // it parks in WaitForInputAsync without a pending external request.
+            if (checkpoints.Count > 0)
+            {
+                CheckpointInfo resumeFromCheckpoint = checkpoints[0];
+                Console.WriteLine($"\nWORKFLOW: Verifying read path by resuming from checkpoint {resumeFromCheckpoint.CheckpointId}");
+                StreamingRun resumed = await InProcessExecution.ResumeStreamingAsync(CreateWorkflow(), resumeFromCheckpoint, checkpointManager).ConfigureAwait(false);
+                await resumed.DisposeAsync().ConfigureAwait(false);
+                Console.WriteLine("WORKFLOW: Checkpoint deserialized successfully");
+            }
+
+            Console.WriteLine("\nWORKFLOW: Done!\n");
+        }
+        finally
+        {
+            TryDelete(checkpointFolder);
+        }
+    }
+
+    private static async Task<List<CheckpointInfo>> RunAndStreamAsync(Workflow workflow, string input, CheckpointManager checkpointManager)
+    {
+        StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input, checkpointManager).ConfigureAwait(false);
+        return await DrainAsync(run).ConfigureAwait(false);
+    }
+
+    private static async Task<List<CheckpointInfo>> DrainAsync(StreamingRun run)
+    {
+#pragma warning disable CA2007 // Consider calling ConfigureAwait on the awaited task
+        await using IAsyncDisposable disposeRun = run;
+#pragma warning restore CA2007
+
+        List<CheckpointInfo> checkpoints = [];
+        string? streamingMessageId = null;
+
+        await foreach (WorkflowEvent workflowEvent in run.WatchStreamAsync().ConfigureAwait(false))
+        {
+            switch (workflowEvent)
+            {
+                case WorkflowErrorEvent workflowError:
+                    throw workflowError.Data as Exception ?? new InvalidOperationException("Unexpected workflow failure.");
+
+                case SuperStepCompletedEvent superStepCompleted:
+                    CheckpointInfo? checkpoint = superStepCompleted.CompletionInfo?.Checkpoint;
+                    if (checkpoint is not null)
+                    {
+                        checkpoints.Add(checkpoint);
+                    }
+                    Console.ForegroundColor = ConsoleColor.DarkGray;
+                    Console.WriteLine($"\n[checkpoint x{superStepCompleted.StepNumber}: {checkpoint?.CheckpointId ?? "(none)"}]");
+                    Console.ResetColor();
+                    break;
+
+                case MessageActivityEvent activityEvent:
+                    Console.ForegroundColor = ConsoleColor.Yellow;
+                    Console.WriteLine($"\nACTIVITY: {activityEvent.Message.Trim()}");
+                    Console.ResetColor();
+                    break;
+
+                case AgentResponseUpdateEvent streamEvent:
+                    if (!string.Equals(streamingMessageId, streamEvent.Update.MessageId, StringComparison.Ordinal))
+                    {
+                        streamingMessageId = streamEvent.Update.MessageId;
+                        string agentName = streamEvent.Update.AuthorName ?? streamEvent.Update.AgentId ?? nameof(ChatRole.Assistant);
+                        Console.ForegroundColor = ConsoleColor.Cyan;
+                        Console.Write($"\n{agentName.ToUpperInvariant()}: ");
+                        Console.ResetColor();
+                    }
+                    Console.Write(streamEvent.Update.Text);
+                    break;
+            }
+        }
+
+        return checkpoints;
+    }
+
+    private static async Task CreateGreeterAgentAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        DeclarativeAgentDefinition definition =
+            new(configuration.GetValue(Application.Settings.FoundryModel))
+            {
+                Instructions =
+                    """
+                    You are a warm and concise greeter. Reply to the user's message in
+                    one or two short sentences. Always include the user's name if they
+                    provided one, and end with a friendly question.
+                    """
+            };
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "GreeterAgent",
+            agentDefinition: definition,
+            agentDescription: "Greeter agent for the AotCheckpointing sample.");
+    }
+
+    private static void TryDelete(DirectoryInfo directory)
+    {
+        try
+        {
+            directory.Refresh();
+            if (directory.Exists)
+            {
+                directory.Delete(recursive: true);
+            }
+        }
+        catch (Exception ex)
+        {
+            Console.ForegroundColor = ConsoleColor.DarkYellow;
+            Console.WriteLine($"\n(could not clean up '{directory.FullName}': {ex.Message})");
+            Console.ResetColor();
+        }
+    }
+}

dotnet/samples/03-workflows/Declarative/AotCheckpointing/README.md

@@ -0,0 +1,107 @@
+# AotCheckpointing sample
+
+Demonstrates JSON checkpointing of a declarative workflow under
+reflection-disabled `System.Text.Json` -- the same constraint imposed by
+**AOT / trim-aggressive deployments**.
+
+## What it shows
+
+- A 3-action declarative workflow
+  (`SetVariable` -> `InvokeAzureAgent` -> `SendActivity`) checkpointed
+  after every superstep.
+- The csproj sets
+  `<JsonSerializerIsReflectionEnabledByDefault>false</JsonSerializerIsReflectionEnabledByDefault>`.
+  Every JSON operation must resolve type info via a source-gen
+  `JsonSerializerContext` or fail with
+  `InvalidOperationException: No JSON type info is available for type 'X'`.
+- The experimental
+  [`DeclarativeWorkflowJsonOptions.Default`](../../../../src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowJsonOptions.cs)
+  `JsonSerializerOptions` instance covers every declarative-package
+  type that flows through the checkpoint pipeline. Pass it to
+  `CheckpointManager.CreateJson`.
+- JSON round-trip is verified in two phases:
+  1. Run + drain -- every `[checkpoint x<n>]` line is a successful JSON **write**.
+  2. `ResumeStreamingAsync` on a fresh workflow instance -- a clean
+     return is the proof JSON **reads** round-trip too. The resumed run
+     is disposed immediately; without a pending external request it
+     would park in `WaitForInputAsync` indefinitely.
+
+`DeclarativeWorkflowJsonOptions` is marked
+`[Experimental("MAAI001")]`. Suppress that diagnostic in your csproj to
+use it.
+
+### Registering user-defined types
+
+For workflows whose inputs or custom `ActionExecutorResult.Result`
+payloads are user-defined, clone `Default` and append your own resolver:
+
+```csharp
+JsonSerializerOptions options = new(DeclarativeWorkflowJsonOptions.Default);
+options.TypeInfoResolverChain.Add(MyAppJsonContext.Default);
+options.MakeReadOnly();
+CheckpointManager manager = CheckpointManager.CreateJson(store, options);
+```
+
+## Run
+
+Prerequisites:
+
+- Azure Foundry project with a deployed model.
+- `az login`.
+- Configuration (user secrets or env):
+
+  | Setting | Description |
+  | --- | --- |
+  | `AZURE_AI_PROJECT_ENDPOINT` | Foundry project endpoint URL. |
+  | `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Model deployment name. |
+
+  See the [parent README](../README.md) for the full walkthrough.
+
+```sh
+cd dotnet/samples/03-workflows/Declarative/AotCheckpointing
+dotnet run "Hello, my name is Ada."
+```
+
+Expected output:
+
+1. `[checkpoint x<n>]` lines after each superstep.
+2. The agent's streamed response.
+3. `ACTIVITY: [Sample] Workflow completed. ...`
+4. `WORKFLOW: Verifying read path by resuming from checkpoint <id>`
+5. `WORKFLOW: Checkpoint deserialized successfully`
+6. `WORKFLOW: Done!`
+
+The `chk-*/` checkpoint folder is deleted at the end.
+
+## Observe the failure mode
+
+Drop the options argument:
+
+```csharp
+CheckpointManager checkpointManager = CheckpointManager.CreateJson(store, DeclarativeWorkflowJsonOptions.Default);
+```
+
+becomes
+
+```csharp
+CheckpointManager checkpointManager = CheckpointManager.CreateJson(store);
+```
+
+Clean rebuild, then re-run. Expected on the first checkpoint commit:
+
+```
+System.InvalidOperationException: No JSON type info is available for type
+'Microsoft.Agents.AI.Workflows.Declarative.Kit.ActionExecutorResult'.
+```
+
+This is what `dotnet publish -p:PublishAot=true` would surface at runtime.
+
+## Notes
+
+- `PublishAot=true` is **not** set. The
+  `JsonSerializerIsReflectionEnabledByDefault=false` flag is the
+  minimum constraint that reproduces the AOT failure for JSON
+  checkpointing.
+- JSON code paths inside transitive dependencies (e.g. Foundry SDK)
+  that rely on reflection would also fail under this flag; those are
+  outside the workflow framework's responsibility.

dotnet/samples/03-workflows/Declarative/ConfirmInput/ConfirmInput.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+  
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="ConfirmInput.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+  
+</Project>

dotnet/samples/03-workflows/Declarative/ConfirmInput/ConfirmInput.yaml

@@ -0,0 +1,61 @@
+#
+# This workflow demonstrates how to use the Question action
+# to request user input and confirm it matches the original input.
+#
+# Note: This workflow doesn't make use of any agents.
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_demo
+  actions:
+  
+    # Capture original input
+    - kind: SetVariable
+      id: set_project
+      variable: Local.OriginalInput
+      value: =System.LastMessage.Text
+
+    # Request input from user
+    - kind: Question
+      id: question_confirm
+      alwaysPrompt: false
+      autoSend: false
+      property: Local.ConfirmedInput
+      prompt:
+        kind: Message
+        text:
+            - "CONFIRM:"
+      entity:
+        kind: StringPrebuiltEntity
+
+    # Confirm input
+    - kind: ConditionGroup
+      id: check_completion
+      conditions:
+
+        # Didn't match
+        - condition: =Local.OriginalInput <> Local.ConfirmedInput
+          id: check_confirm
+          actions:
+
+            - kind: SendActivity
+              id: sendActivity_mismatch
+              activity: |-
+                "{Local.ConfirmedInput}" does not match the original input of "{Local.OriginalInput}". Please try again.
+
+            - kind: GotoAction
+              id: goto_again
+              actionId: question_confirm
+
+      # Confirmed
+      elseActions:
+        - kind: SendActivity
+          id: sendActivity_confirmed
+          activity: |-
+            You entered:
+            {Local.OriginalInput}
+
+            Confirmed input:
+            {Local.ConfirmedInput}

dotnet/samples/03-workflows/Declarative/ConfirmInput/Program.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.Configuration;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.ConfirmInput;
+
+/// <summary>
+/// Demonstrate how to use the question action to request user input
+/// and confirm it matches the original input.
+/// </summary>
+/// <remarks>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.  This class demonstrates how to initialize a
+        // declarative workflow from a YAML file. Once the workflow is created, it
+        // can be executed just like any regular workflow.
+        WorkflowFactory workflowFactory = new("ConfirmInput.yaml", foundryEndpoint);
+
+        // Execute the workflow:  The WorkflowRunner demonstrates how to execute
+        // a workflow, handle the workflow events, and providing external input.
+        // This also includes the ability to checkpoint workflow state and how to
+        // resume execution.
+        WorkflowRunner runner = new();
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+}

dotnet/samples/03-workflows/Declarative/CustomerSupport/CustomerSupport.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="$(MSBuildThisFileDirectory)..\..\..\..\..\declarative-agents\workflow-samples\CustomerSupport.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/CustomerSupport/Program.cs

@@ -0,0 +1,444 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Responses;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.CustomerSupport;
+
+/// <summary>
+/// This workflow demonstrates using multiple agents to provide automated
+/// troubleshooting steps to resolve common issues with escalation options.
+/// </summary>
+/// <remarks>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Create the ticketing plugin (mock functionality)
+        TicketingPlugin plugin = new();
+
+        // Ensure sample agents exist in Foundry.
+        await CreateAgentsAsync(foundryEndpoint, configuration, plugin);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.  This class demonstrates how to initialize a
+        // declarative workflow from a YAML file. Once the workflow is created, it
+        // can be executed just like any regular workflow.
+        WorkflowFactory workflowFactory =
+            new("CustomerSupport.yaml", foundryEndpoint)
+            {
+                Functions =
+                [
+                    AIFunctionFactory.Create(plugin.CreateTicket),
+                    AIFunctionFactory.Create(plugin.GetTicket),
+                    AIFunctionFactory.Create(plugin.ResolveTicket),
+                    AIFunctionFactory.Create(plugin.SendNotification),
+                ]
+            };
+
+        // Execute the workflow:  The WorkflowRunner demonstrates how to execute
+        // a workflow, handle the workflow events, and providing external input.
+        // This also includes the ability to checkpoint workflow state and how to
+        // resume execution.
+        WorkflowRunner runner = new();
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentsAsync(Uri foundryEndpoint, IConfiguration configuration, TicketingPlugin plugin)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "SelfServiceAgent",
+            agentDefinition: DefineSelfServiceAgent(configuration),
+            agentDescription: "Service agent for CustomerSupport workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "TicketingAgent",
+            agentDefinition: DefineTicketingAgent(configuration, plugin),
+            agentDescription: "Ticketing agent for CustomerSupport workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "TicketRoutingAgent",
+            agentDefinition: DefineTicketRoutingAgent(configuration, plugin),
+            agentDescription: "Routing agent for CustomerSupport workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "WindowsSupportAgent",
+            agentDefinition: DefineWindowsSupportAgent(configuration, plugin),
+            agentDescription: "Windows support agent for CustomerSupport workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "TicketResolutionAgent",
+            agentDefinition: DefineResolutionAgent(configuration, plugin),
+            agentDescription: "Resolution agent for CustomerSupport workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "TicketEscalationAgent",
+            agentDefinition: TicketEscalationAgent(configuration, plugin),
+            agentDescription: "Escalate agent for human support");
+    }
+
+    private static DeclarativeAgentDefinition DefineSelfServiceAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Use your knowledge to work with the user to provide the best possible troubleshooting steps.
+
+                - If the user confirms that the issue is resolved, then the issue is resolved. 
+                - If the user reports that the issue persists, then escalate.
+                """,
+            TextOptions =
+                new ResponseTextOptions
+                {
+                    TextFormat =
+                        ResponseTextFormat.CreateJsonSchemaFormat(
+                            "TaskEvaluation",
+                            BinaryData.FromString(
+                                """
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "IsResolved": {
+                                      "type": "boolean",
+                                      "description": "True if the user issue/ask has been resolved."
+                                    },
+                                    "NeedsTicket": {
+                                      "type": "boolean",
+                                      "description": "True if the user issue/ask requires that a ticket be filed."
+                                    },
+                                    "IssueDescription": {
+                                      "type": "string",
+                                      "description": "A concise description of the issue."
+                                    },
+                                    "AttemptedResolutionSteps": {
+                                      "type": "string",
+                                      "description": "An outline of the steps taken to attempt resolution."
+                                    }                              
+                                  },
+                                  "required": ["IsResolved", "NeedsTicket", "IssueDescription", "AttemptedResolutionSteps"],
+                                  "additionalProperties": false
+                                }
+                                """),
+                            jsonSchemaFormatDescription: null,
+                            jsonSchemaIsStrict: true),
+                }
+        };
+
+    private static DeclarativeAgentDefinition DefineTicketingAgent(IConfiguration configuration, TicketingPlugin plugin) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Always create a ticket in Azure DevOps using the available tools.
+
+                Include the following information in the TicketSummary.
+
+                - Issue description: {{IssueDescription}}
+                - Attempted resolution steps: {{AttemptedResolutionSteps}}
+
+                After creating the ticket, provide the user with the ticket ID.
+                """,
+            Tools =
+            {
+                AIFunctionFactory.Create(plugin.CreateTicket).AsOpenAIResponseTool()
+            },
+            StructuredInputs =
+            {
+                ["IssueDescription"] =
+                    new StructuredInputDefinition
+                    {
+                        IsRequired = false,
+                        DefaultValue = BinaryData.FromString(@"""unknown"""),
+                        Description = "A concise description of the issue.",
+                    },
+                ["AttemptedResolutionSteps"] =
+                    new StructuredInputDefinition
+                    {
+                        IsRequired = false,
+                        DefaultValue = BinaryData.FromString(@"""unknown"""),
+                        Description = "An outline of the steps taken to attempt resolution.",
+                    }
+            },
+            TextOptions =
+                new ResponseTextOptions
+                {
+                    TextFormat =
+                        ResponseTextFormat.CreateJsonSchemaFormat(
+                            "TaskEvaluation",
+                            BinaryData.FromString(
+                                """
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "TicketId": {
+                                      "type": "string",
+                                      "description": "The identifier of the ticket created in response to the user issue."
+                                    },
+                                    "TicketSummary": {
+                                      "type": "string",
+                                      "description": "The summary of the ticket created in response to the user issue."
+                                    }
+                                  },
+                                  "required": ["TicketId", "TicketSummary"],
+                                  "additionalProperties": false
+                                }
+                                """),
+                            jsonSchemaFormatDescription: null,
+                            jsonSchemaIsStrict: true),
+                }
+        };
+
+    private static DeclarativeAgentDefinition DefineTicketRoutingAgent(IConfiguration configuration, TicketingPlugin plugin) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Determine how to route the given issue to the appropriate support team. 
+
+                Choose from the available teams and their functions:
+                - Windows Activation Support: Windows license activation issues
+                - Windows Support: Windows related issues
+                - Azure Support: Azure related issues
+                - Network Support: Network related issues
+                - Hardware Support: Hardware related issues
+                - Microsoft Office Support: Microsoft Office related issues
+                - General Support: General issues not related to the above categories
+                """,
+            Tools =
+            {
+                AIFunctionFactory.Create(plugin.GetTicket).AsOpenAIResponseTool(),
+            },
+            TextOptions =
+                new ResponseTextOptions
+                {
+                    TextFormat =
+                        ResponseTextFormat.CreateJsonSchemaFormat(
+                            "TaskEvaluation",
+                            BinaryData.FromString(
+                                """
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "TeamName": {
+                                      "type": "string",
+                                      "description": "The name of the team to route the issue"
+                                    }
+                                  },
+                                  "required": ["TeamName"],
+                                  "additionalProperties": false
+                                }
+                                """),
+                            jsonSchemaFormatDescription: null,
+                            jsonSchemaIsStrict: true),
+                }
+        };
+
+    private static DeclarativeAgentDefinition DefineWindowsSupportAgent(IConfiguration configuration, TicketingPlugin plugin) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Use your knowledge to work with the user to provide the best possible troubleshooting steps
+                for issues related to Windows operating system.
+
+                - Utilize the "Attempted Resolutions Steps" as a starting point for your troubleshooting.
+                - Never escalate without troubleshooting with the user.                
+                - If the user confirms that the issue is resolved, then the issue is resolved. 
+                - If the user reports that the issue persists, then escalate.
+
+                Issue: {{IssueDescription}}
+                Attempted Resolution Steps: {{AttemptedResolutionSteps}}
+                """,
+            StructuredInputs =
+            {
+                ["IssueDescription"] =
+                    new StructuredInputDefinition
+                    {
+                        IsRequired = false,
+                        DefaultValue = BinaryData.FromString(@"""unknown"""),
+                        Description = "A concise description of the issue.",
+                    },
+                ["AttemptedResolutionSteps"] =
+                    new StructuredInputDefinition
+                    {
+                        IsRequired = false,
+                        DefaultValue = BinaryData.FromString(@"""unknown"""),
+                        Description = "An outline of the steps taken to attempt resolution.",
+                    }
+            },
+            Tools =
+            {
+                AIFunctionFactory.Create(plugin.GetTicket).AsOpenAIResponseTool(),
+            },
+            TextOptions =
+                new ResponseTextOptions
+                {
+                    TextFormat =
+                        ResponseTextFormat.CreateJsonSchemaFormat(
+                            "TaskEvaluation",
+                            BinaryData.FromString(
+                                """
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "IsResolved": {
+                                      "type": "boolean",
+                                      "description": "True if the user issue/ask has been resolved."
+                                    },
+                                    "NeedsEscalation": {
+                                      "type": "boolean",
+                                      "description": "True resolution could not be achieved and the issue/ask requires escalation."
+                                    },
+                                    "ResolutionSummary": {
+                                      "type": "string",
+                                      "description": "The summary of the steps that led to resolution."
+                                    }
+                                  },
+                                  "required": ["IsResolved", "NeedsEscalation", "ResolutionSummary"],
+                                  "additionalProperties": false
+                                }
+                                """),
+                            jsonSchemaFormatDescription: null,
+                            jsonSchemaIsStrict: true),
+                }
+        };
+
+    private static DeclarativeAgentDefinition DefineResolutionAgent(IConfiguration configuration, TicketingPlugin plugin) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Resolve the following ticket in Azure DevOps.
+                Always include the resolution details.
+
+                - Ticket ID: #{{TicketId}}
+                - Resolution Summary: {{ResolutionSummary}}
+                """,
+            Tools =
+            {
+                AIFunctionFactory.Create(plugin.ResolveTicket).AsOpenAIResponseTool(),
+            },
+            StructuredInputs =
+            {
+                    ["TicketId"] =
+                        new StructuredInputDefinition
+                        {
+                            IsRequired = false,
+                            DefaultValue = BinaryData.FromString(@"""unknown"""),
+                            Description = "The identifier of the ticket being resolved.",
+                        },
+                    ["ResolutionSummary"] =
+                        new StructuredInputDefinition
+                        {
+                            IsRequired = false,
+                            DefaultValue = BinaryData.FromString(@"""unknown"""),
+                            Description = "The steps taken to resolve the issue.",
+                        }
+            }
+        };
+
+    private static DeclarativeAgentDefinition TicketEscalationAgent(IConfiguration configuration, TicketingPlugin plugin) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                You escalate the provided issue to human support team by sending an email if the issue is not resolved.
+
+                Here are some additional details that might help:
+                - TicketId : {{TicketId}}
+                - IssueDescription : {{IssueDescription}}
+                - AttemptedResolutionSteps : {{AttemptedResolutionSteps}}
+
+                Before escalating, gather the user's email address for follow-up.
+                If not known, ask the user for their email address so that the support team can reach them when needed.
+
+                When sending the email, include the following details:
+                - To: support@contoso.com
+                - Cc: user's email address
+                - Subject of the email: "Support Ticket - {TicketId} - [Compact Issue Description]"
+                - Body: 
+                  - Issue description
+                  - Attempted resolution steps
+                  - User's email address
+                  - Any other relevant information from the conversation history
+
+                Assure the user that their issue will be resolved and provide them with a ticket ID for reference.
+                """,
+            Tools =
+            {
+                AIFunctionFactory.Create(plugin.GetTicket).AsOpenAIResponseTool(),
+                AIFunctionFactory.Create(plugin.SendNotification).AsOpenAIResponseTool(),
+            },
+            StructuredInputs =
+            {
+                ["TicketId"] =
+                    new StructuredInputDefinition
+                    {
+                        IsRequired = false,
+                        DefaultValue = BinaryData.FromString(@"""unknown"""),
+                        Description = "The identifier of the ticket being escalated.",
+                    },
+                ["IssueDescription"] =
+                    new StructuredInputDefinition
+                    {
+                        IsRequired = false,
+                        DefaultValue = BinaryData.FromString(@"""unknown"""),
+                        Description = "A concise description of the issue.",
+                    },
+                ["ResolutionSummary"] =
+                    new StructuredInputDefinition
+                    {
+                        IsRequired = false,
+                        DefaultValue = BinaryData.FromString(@"""unknown"""),
+                        Description = "An outline of the steps taken to attempt resolution.",
+                    }
+            },
+            TextOptions =
+                new ResponseTextOptions
+                {
+                    TextFormat =
+                        ResponseTextFormat.CreateJsonSchemaFormat(
+                            "TaskEvaluation",
+                            BinaryData.FromString(
+                                """
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "IsComplete": {
+                                      "type": "boolean",
+                                      "description": "Has the email been sent and no more user input is required."
+                                    },
+                                    "UserMessage": {
+                                      "type": "string",
+                                      "description": "A natural language message to the user."
+                                    }
+                                  },
+                                  "required": ["IsComplete", "UserMessage"],
+                                  "additionalProperties": false
+                                }
+                                """),
+                            jsonSchemaFormatDescription: null,
+                            jsonSchemaIsStrict: true),
+                }
+        };
+}

dotnet/samples/03-workflows/Declarative/CustomerSupport/Properties/launchSettings.json

@@ -0,0 +1,19 @@
+{
+  "profiles": {
+    "Default": {
+      "commandName": "Project"
+    },
+    "Reboot": {
+      "commandName": "Project",
+      "commandLineArgs": "\"My PC keeps rebooting and I can't use it.\""
+    },
+    "License": {
+      "commandName": "Project",
+      "commandLineArgs": "\"My M365 Office license key isn't activating.\""
+    },
+    "Windows": {
+      "commandName": "Project",
+      "commandLineArgs": "\"How do I change my mouse speed settings?\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/CustomerSupport/TicketingPlugin.cs

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+
+namespace Demo.Workflows.Declarative.CustomerSupport;
+
+internal sealed class TicketingPlugin
+{
+    private readonly Dictionary<string, TicketItem> _ticketStore = [];
+
+    [Description("Retrieve a ticket by identifier from Azure DevOps.")]
+    public TicketItem? GetTicket(string id)
+    {
+        Trace(nameof(GetTicket));
+
+        this._ticketStore.TryGetValue(id, out TicketItem? ticket);
+
+        return ticket;
+    }
+
+    [Description("Create a ticket in Azure DevOps and return its identifier.")]
+    public string CreateTicket(string subject, string description, string notes)
+    {
+        Trace(nameof(CreateTicket));
+
+        TicketItem ticket = new()
+        {
+            Subject = subject,
+            Description = description,
+            Notes = notes,
+            Id = Guid.NewGuid().ToString("N"),
+        };
+
+        this._ticketStore[ticket.Id] = ticket;
+
+        return ticket.Id;
+    }
+
+    [Description("Resolve an existing ticket in Azure DevOps given its identifier.")]
+    public void ResolveTicket(string id, string resolutionSummary)
+    {
+        Trace(nameof(ResolveTicket));
+
+        if (this._ticketStore.TryGetValue(id, out TicketItem? ticket))
+        {
+            ticket.Status = TicketStatus.Resolved;
+        }
+    }
+
+    [Description("Send an email notification to escalate ticket engagement.")]
+    public void SendNotification(string id, string email, string cc, string body)
+    {
+        Trace(nameof(SendNotification));
+    }
+
+    private static void Trace(string functionName)
+    {
+        Console.ForegroundColor = ConsoleColor.DarkMagenta;
+        try
+        {
+            Console.WriteLine($"\nFUNCTION: {functionName}");
+        }
+        finally
+        {
+            Console.ResetColor();
+        }
+    }
+
+    public enum TicketStatus
+    {
+        Open,
+        InProgress,
+        Resolved,
+        Closed,
+    }
+
+    public sealed class TicketItem
+    {
+        public TicketStatus Status { get; set; } = TicketStatus.Open;
+        public string Subject { get; init; } = string.Empty;
+        public string Id { get; init; } = string.Empty;
+        public string Description { get; init; } = string.Empty;
+        public string Notes { get; init; } = string.Empty;
+    }
+}

dotnet/samples/03-workflows/Declarative/DeepResearch/DeepResearch.csproj

@@ -0,0 +1,41 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+  
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="$(MSBuildThisFileDirectory)..\..\..\..\..\declarative-agents\workflow-samples\DeepResearch.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+    <None Include="wttr.json">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/DeepResearch/Program.cs

@@ -0,0 +1,284 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Responses;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.DeepResearch;
+
+/// <summary>
+/// Demonstrate a declarative workflow that accomplishes a task
+/// using the Magentic orchestration pattern developed by AutoGen.
+/// </summary>
+/// <remarks>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agents exist in Foundry.
+        await CreateAgentsAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.  This class demonstrates how to initialize a
+        // declarative workflow from a YAML file. Once the workflow is created, it
+        // can be executed just like any regular workflow.
+        WorkflowFactory workflowFactory = new("DeepResearch.yaml", foundryEndpoint);
+
+        // Execute the workflow:  The WorkflowRunner demonstrates how to execute
+        // a workflow, handle the workflow events, and providing external input.
+        // This also includes the ability to checkpoint workflow state and how to
+        // resume execution.
+        WorkflowRunner runner = new();
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentsAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "ResearchAgent",
+            agentDefinition: DefineResearchAgent(configuration),
+            agentDescription: "Planner agent for DeepResearch workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "PlannerAgent",
+            agentDefinition: DefinePlannerAgent(configuration),
+            agentDescription: "Planner agent for DeepResearch workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "ManagerAgent",
+            agentDefinition: DefineManagerAgent(configuration),
+            agentDescription: "Manager agent for DeepResearch workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "SummaryAgent",
+            agentDefinition: DefineSummaryAgent(configuration),
+            agentDescription: "Summary agent for DeepResearch workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "KnowledgeAgent",
+            agentDefinition: DefineKnowledgeAgent(configuration),
+            agentDescription: "Research agent for DeepResearch workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "CoderAgent",
+            agentDefinition: DefineCoderAgent(configuration),
+            agentDescription: "Coder agent for DeepResearch workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "WeatherAgent",
+            agentDefinition: DefineWeatherAgent(configuration),
+            agentDescription: "Weather agent for DeepResearch workflow");
+    }
+
+    private static DeclarativeAgentDefinition DefineResearchAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                In order to help begin addressing the user request, please answer the following pre-survey to the best of your ability. 
+                Keep in mind that you are Ken Jennings-level with trivia, and Mensa-level with puzzles, so there should be a deep well to draw from.
+
+                Here is the pre-survey:
+
+                    1. Please list any specific facts or figures that are GIVEN in the request itself. It is possible that there are none.
+                    2. Please list any facts that may need to be looked up, and WHERE SPECIFICALLY they might be found. In some cases, authoritative sources are mentioned in the request itself.
+                    3. Please list any facts that may need to be derived (e.g., via logical deduction, simulation, or computation)
+                    4. Please list any facts that are recalled from memory, hunches, well-reasoned guesses, etc.
+
+                When answering this survey, keep in mind that 'facts' will typically be specific names, dates, statistics, etc. Your answer must only use the headings:
+
+                    1. GIVEN OR VERIFIED FACTS
+                    2. FACTS TO LOOK UP
+                    3. FACTS TO DERIVE
+                    4. EDUCATED GUESSES
+
+                DO NOT include any other headings or sections in your response. DO NOT list next steps or plans until asked to do so.
+                """,
+            Tools =
+            {
+                //ProjectsAgentTool.CreateBingGroundingTool( // TODO: Use Bing Grounding when available
+                //    new BingGroundingSearchToolParameters(
+                //        [new BingGroundingSearchConfiguration(this.GetSetting(Settings.FoundryGroundingTool))]))
+            }
+        };
+
+    private static DeclarativeAgentDefinition DefinePlannerAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions = // TODO: Use Structured Inputs / Prompt Template
+                """
+                Your only job is to devise an efficient plan that identifies (by name) how a team member may contribute to addressing the user request.
+
+                Only select the following team which is listed as "- [Name]: [Description]"
+
+                - WeatherAgent: Able to retrieve weather information
+                - CoderAgent: Able to write and execute Python code
+                - KnowledgeAgent: Able to perform generic websearches
+
+                The plan must be a bullet point list must be in the form "- [AgentName]: [Specific action or task for that agent to perform]"
+  
+                Remember, there is no requirement to involve the entire team -- only select team member's whose particular expertise is required for this task.
+                """
+        };
+
+    private static DeclarativeAgentDefinition DefineManagerAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions = // TODO: Use Structured Inputs / Prompt Template
+                """
+                Recall we have assembled the following team:
+
+                - KnowledgeAgent: Able to perform generic websearches
+                - CoderAgent: Able to write and execute Python code
+                - WeatherAgent: Able to retrieve weather information
+                                
+                To make progress on the request, please answer the following questions, including necessary reasoning:
+                - Is the request fully satisfied? (True if complete, or False if the original request has yet to be SUCCESSFULLY and FULLY addressed)
+                - Are we in a loop where we are repeating the same requests and / or getting the same responses from an agent multiple times? Loops can span multiple turns, and can include repeated actions like scrolling up or down more than a handful of times.
+                - Are we making forward progress? (True if just starting, or recent messages are adding value. False if recent messages show evidence of being stuck in a loop or if there is evidence of significant barriers to success such as the inability to read from a required file)
+                - Who should speak next? (select from: KnowledgeAgent, CoderAgent, WeatherAgent) 
+                - What instruction or question would you give this team member? (Phrase as if speaking directly to them, and include any specific information they may need)
+                """,
+            TextOptions =
+                new ResponseTextOptions
+                {
+                    TextFormat =
+                        ResponseTextFormat.CreateJsonSchemaFormat(
+                            "TaskEvaluation",
+                            BinaryData.FromString(
+                                """
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "is_request_satisfied": {
+                                      "type": "object",
+                                      "properties": {
+                                        "reason": { "type": "string" },
+                                        "answer": { "type": "boolean" }
+                                      },
+                                      "required": ["reason", "answer"],
+                                      "additionalProperties": false
+                                    },
+                                    "is_in_loop": {
+                                      "type": "object",
+                                      "properties": {
+                                        "reason": { "type": "string" },
+                                        "answer": { "type": "boolean" }
+                                      },
+                                      "required": ["reason", "answer"],
+                                      "additionalProperties": false
+                                    },
+                                    "is_progress_being_made": {
+                                      "type": "object",
+                                      "properties": {
+                                        "reason": { "type": "string" },
+                                        "answer": { "type": "boolean" }
+                                      },
+                                      "required": ["reason", "answer"],
+                                      "additionalProperties": false
+                                    },
+                                    "next_speaker": {
+                                      "type": "object",
+                                      "properties": {
+                                        "reason": { "type": "string" },
+                                        "answer": {
+                                          "type": "string"
+                                        }
+                                      },
+                                      "required": ["reason", "answer"],
+                                      "additionalProperties": false
+                                    },
+                                    "instruction_or_question": {
+                                      "type": "object",
+                                      "properties": {
+                                        "reason": { "type": "string" },
+                                        "answer": { "type": "string" }
+                                      },
+                                      "required": ["reason", "answer"],
+                                      "additionalProperties": false
+                                    }
+                                  },
+                                  "required": ["is_request_satisfied", "is_in_loop", "is_progress_being_made", "next_speaker", "instruction_or_question"],
+                                  "additionalProperties": false
+                                }
+                                """),
+                            jsonSchemaFormatDescription: null,
+                            jsonSchemaIsStrict: true),
+                }
+        };
+
+    private static DeclarativeAgentDefinition DefineSummaryAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                We have completed the task.
+
+                Based only on the conversation and without adding any new information,
+                synthesize the result of the conversation as a complete response to the user task.
+
+                The user will only ever see this last response and not the entire conversation,
+                so please ensure it is complete and self-contained.
+                """
+        };
+
+    private static DeclarativeAgentDefinition DefineKnowledgeAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Tools =
+            {
+                //ProjectsAgentTool.CreateBingGroundingTool( // TODO: Use Bing Grounding when available
+                //    new BingGroundingSearchToolParameters(
+                //        [new BingGroundingSearchConfiguration(this.GetSetting(Settings.FoundryGroundingTool))]))
+            }
+        };
+
+    private static DeclarativeAgentDefinition DefineCoderAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                You solve problem by writing and executing code.
+                """,
+            Tools =
+            {
+                ResponseTool.CreateCodeInterpreterTool(
+                    new(CodeInterpreterToolContainerConfiguration.CreateAutomaticContainerConfiguration()))
+            }
+        };
+
+    private static DeclarativeAgentDefinition DefineWeatherAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                You are a weather expert.
+                """,
+            Tools =
+            {
+                ProjectsAgentTool.CreateOpenApiTool(
+                    new OpenApiFunctionDefinition(
+                        "weather-forecast",
+                        BinaryData.FromString(File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "wttr.json"))),
+                        new OpenAPIAnonymousAuthenticationDetails()))
+            }
+        };
+}

dotnet/samples/03-workflows/Declarative/DeepResearch/Properties/launchSettings.json

@@ -0,0 +1,11 @@
+{
+  "profiles": {
+    "Default": {
+      "commandName": "Project"
+    },
+    "Bus Stop": {
+      "commandName": "Project",
+      "commandLineArgs": "\"What is the closest bus-stop that is next to ISHONI YAKINIKU in Seattle?\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/DeepResearch/wttr.json

@@ -0,0 +1,51 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Get weather data",
+    "description": "Retrieves current weather data for a location based on wttr.in.",
+    "version": "v1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://wttr.in"
+    }
+  ],
+  "paths": {
+    "/{location}": {
+      "get": {
+        "description": "Get weather information for a specific location",
+        "operationId": "GetCurrentWeather",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "path",
+            "description": "City or location to retrieve the weather for",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Location not found"
+          }
+        },
+        "deprecated": false
+      }
+    }
+  },
+  "components": {
+    "schemas": {}
+  }
+}

dotnet/samples/03-workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);CA1812</NoWarn>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/ExecuteWorkflow/Program.cs

@@ -0,0 +1,237 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Uncomment this to enable JSON checkpointing to the local file system.
+//#define CHECKPOINT_JSON
+
+using System.Diagnostics;
+using System.Reflection;
+using Azure.Identity;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Agents.AI.Workflows.Declarative;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using Shared.Workflows;
+
+namespace Demo.DeclarativeWorkflow;
+
+/// <summary>
+/// HOW TO: Create a workflow from a declarative (yaml based) definition.
+/// </summary>
+/// <remarks>
+/// <b>Configuration</b>
+/// Define FOUNDRY_PROJECT_ENDPOINT as a user-secret or environment variable that
+/// points to your Foundry project endpoint.
+/// <b>Usage</b>
+/// Provide the path to the workflow definition file as the first argument.
+/// All other arguments are intepreted as a queue of inputs.
+/// When no input is queued, interactive input is requested from the console.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        string? workflowFile = ParseWorkflowFile(args);
+        if (workflowFile is null)
+        {
+            Notify("\nUsage: DeclarativeWorkflow <workflow-file> [<input>]\n");
+            return;
+        }
+
+        string? workflowInput = ParseWorkflowInput(args);
+
+        Program program = new(workflowFile, workflowInput);
+        await program.ExecuteAsync();
+    }
+
+    private async Task ExecuteAsync()
+    {
+        // Read and parse the declarative workflow.
+        Notify($"\nWORKFLOW: Parsing {Path.GetFullPath(this.WorkflowFile)}");
+
+        Stopwatch timer = Stopwatch.StartNew();
+
+        Workflow workflow = this.CreateWorkflow();
+
+        Notify($"\nWORKFLOW: Defined {timer.Elapsed}");
+
+        Notify("\nWORKFLOW: Starting...");
+
+        string input = this.GetWorkflowInput();
+
+        // Execute the workflow:  The WorkflowRunner demonstrates how to execute
+        // a workflow, handle the workflow events, and providing external input.
+        // This also includes the ability to checkpoint workflow state and how to
+        // resume execution.
+        await this.Runner.ExecuteAsync(this.CreateWorkflow, input);
+    }
+
+    /// <summary>
+    /// Create the workflow from the declarative YAML.  Includes definition of the
+    /// <see cref="DeclarativeWorkflowOptions" /> and the associated <see cref="ResponseAgentProvider"/>.
+    /// </summary>
+    private Workflow CreateWorkflow()
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        // Create the agent provider that will service agent requests within the workflow.
+        AzureAgentProvider agentProvider = new(new Uri(this.FoundryEndpoint), new DefaultAzureCredential())
+        {
+            // Functions included here will be auto-executed by the framework.
+            Functions = this.Functions
+        };
+
+        // Define the workflow options.
+        DeclarativeWorkflowOptions options =
+            new(agentProvider)
+            {
+                Configuration = this.Configuration,
+                //ConversationId = null, // Assign to continue a conversation
+                //LoggerFactory = null, // Assign to enable logging
+            };
+
+        // Use DeclarativeWorkflowBuilder to build a workflow based on a YAML file.
+        return DeclarativeWorkflowBuilder.Build<string>(this.WorkflowFile, options);
+    }
+
+    private string WorkflowFile { get; }
+    private string? WorkflowInput { get; }
+    private string FoundryEndpoint { get; }
+    private IConfiguration Configuration { get; }
+    private WorkflowRunner Runner { get; }
+    private IList<AIFunction> Functions { get; }
+
+    private Program(string workflowFile, string? workflowInput)
+    {
+        this.WorkflowFile = workflowFile;
+        this.WorkflowInput = workflowInput;
+
+        this.Configuration = InitializeConfig();
+
+        this.FoundryEndpoint = this.Configuration[Application.Settings.FoundryEndpoint] ?? throw new InvalidOperationException($"Undefined configuration setting: {Application.Settings.FoundryEndpoint}");
+
+        this.Functions =
+            [
+                // Manually define any custom functions that may be required by agents within the workflow.
+                // By default, this sample does not include any functions.
+                //AIFunctionFactory.Create(),
+            ];
+
+        this.Runner =
+            new(this.Functions)
+            {
+#if CHECKPOINT_JSON
+                // Use an json file checkpoint store that will persist checkpoints to the local file system.
+                UseJsonCheckpoints = true
+#else
+                // Use an in-memory checkpoint store that will not persist checkpoints beyond the lifetime of the process.
+                UseJsonCheckpoints = false
+#endif
+            };
+    }
+
+    private static string? ParseWorkflowFile(string[] args)
+    {
+        string? workflowFile = args.FirstOrDefault();
+        if (string.IsNullOrWhiteSpace(workflowFile))
+        {
+            return null;
+        }
+
+        if (!File.Exists(workflowFile) && !Path.IsPathFullyQualified(workflowFile))
+        {
+            string? repoFolder = GetRepoFolder();
+            if (repoFolder is not null)
+            {
+                workflowFile = Path.Combine(repoFolder, "declarative-agents", "workflow-samples", workflowFile);
+                workflowFile = Path.ChangeExtension(workflowFile, ".yaml");
+            }
+        }
+
+        if (!File.Exists(workflowFile))
+        {
+            throw new InvalidOperationException($"Unable to locate workflow: {Path.GetFullPath(workflowFile)}.");
+        }
+
+        return workflowFile;
+
+        static string? GetRepoFolder()
+        {
+            DirectoryInfo? current = new(Directory.GetCurrentDirectory());
+
+            while (current is not null)
+            {
+                if (Directory.Exists(Path.Combine(current.FullName, ".git")))
+                {
+                    return current.FullName;
+                }
+
+                current = current.Parent;
+            }
+
+            return null;
+        }
+    }
+
+    private string GetWorkflowInput()
+    {
+        string? input = this.WorkflowInput;
+
+        try
+        {
+            Console.ForegroundColor = ConsoleColor.DarkGreen;
+
+            Console.Write("\nINPUT: ");
+
+            Console.ForegroundColor = ConsoleColor.White;
+
+            if (!string.IsNullOrWhiteSpace(input))
+            {
+                Console.WriteLine(input);
+                return input;
+            }
+            while (string.IsNullOrWhiteSpace(input))
+            {
+                input = Console.ReadLine();
+            }
+
+            return input.Trim();
+        }
+        finally
+        {
+            Console.ResetColor();
+        }
+    }
+
+    private static string? ParseWorkflowInput(string[] args)
+    {
+        if (args.Length == 0)
+        {
+            return null;
+        }
+
+        string[] workflowInput = [.. args.Skip(1)];
+
+        return workflowInput.FirstOrDefault();
+    }
+
+    // Load configuration from user-secrets
+    private static IConfigurationRoot InitializeConfig() =>
+        new ConfigurationBuilder()
+            .AddUserSecrets(Assembly.GetExecutingAssembly())
+            .AddEnvironmentVariables()
+            .Build();
+
+    private static void Notify(string message)
+    {
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        try
+        {
+            Console.WriteLine(message);
+        }
+        finally
+        {
+            Console.ResetColor();
+        }
+    }
+}

dotnet/samples/03-workflows/Declarative/ExecuteWorkflow/Properties/launchSettings.json

@@ -0,0 +1,32 @@
+{
+  "profiles": {
+    "Marketing": {
+      "commandName": "Project",
+      "commandLineArgs": "\"Marketing.yaml\" \"An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours\""
+    },
+    "MathChat": {
+      "commandName": "Project",
+      "commandLineArgs": "\"MathChat.yaml\" \"How would you compute the value of PI?\""
+    },
+    "Question": {
+      "commandName": "Project",
+      "commandLineArgs": "\"Question.yaml\" \"Iko\""
+    },
+    "Research": {
+      "commandName": "Project",
+      "commandLineArgs": "\"DeepResearch.yaml\" \"What is the closest bus-stop that is next to ISHONI YAKINIKU in Seattle?\""
+    },
+    "ResponseObject": {
+      "commandName": "Project",
+      "commandLineArgs": "\"ResponseObject.yaml\" \"Can you help me plan a trip somewhere soon?\""
+    },
+    "UserInput": {
+      "commandName": "Project",
+      "commandLineArgs": "\"UserInput.yaml\" \"Iko\""
+    },
+    "ParseValue": {
+      "commandName": "Project",
+      "commandLineArgs": "\"Pradeep-ParseValue-Number.yaml\" \"Test this case:\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/FunctionTools/FunctionTools.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="FunctionTools.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/FunctionTools/FunctionTools.yaml

@@ -0,0 +1,22 @@
+#
+# This workflow demonstrates an agent that requires tool approval
+# in a loop responding to user input.
+#
+# Example input: 
+# What is the soup of the day?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_demo
+  actions:
+
+    - kind: InvokeAzureAgent
+      id: invoke_search
+      conversationId: =System.ConversationId
+      agent:
+        name: MenuAgent
+      input:
+        externalLoop:
+          when: =Upper(System.LastMessage.Text) <> "EXIT"

dotnet/samples/03-workflows/Declarative/FunctionTools/MenuPlugin.cs

@@ -0,0 +1,81 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+
+namespace Demo.Workflows.Declarative.FunctionTools;
+
+#pragma warning disable CA1822 // Mark members as static
+
+public sealed class MenuPlugin
+{
+    [Description("Provides a list items on the menu.")]
+    public MenuItem[] GetMenu()
+    {
+        return s_menuItems;
+    }
+
+    [Description("Provides a list of specials from the menu.")]
+    public MenuItem[] GetSpecials()
+    {
+        return [.. s_menuItems.Where(i => i.IsSpecial)];
+    }
+
+    [Description("Provides the price of the requested menu item.")]
+    public float? GetItemPrice(
+        [Description("The name of the menu item.")]
+        string name)
+    {
+        return s_menuItems.FirstOrDefault(i => i.Name.Equals(name, StringComparison.OrdinalIgnoreCase))?.Price;
+    }
+
+    private static readonly MenuItem[] s_menuItems =
+        [
+            new()
+            {
+                Category = "Soup",
+                Name = "Clam Chowder",
+                Price = 4.95f,
+                IsSpecial = true,
+            },
+            new()
+            {
+                Category = "Soup",
+                Name = "Tomato Soup",
+                Price = 4.95f,
+                IsSpecial = false,
+            },
+            new()
+            {
+                Category = "Salad",
+                Name = "Cobb Salad",
+                Price = 9.99f,
+            },
+            new()
+            {
+                Category = "Salad",
+                Name = "House Salad",
+                Price = 4.95f,
+            },
+            new()
+            {
+                Category = "Drink",
+                Name = "Chai Tea",
+                Price = 2.95f,
+                IsSpecial = true,
+            },
+            new()
+            {
+                Category = "Drink",
+                Name = "Soda",
+                Price = 1.95f,
+            },
+        ];
+
+    public sealed class MenuItem
+    {
+        public string Category { get; init; } = string.Empty;
+        public string Name { get; init; } = string.Empty;
+        public float Price { get; init; }
+        public bool IsSpecial { get; init; }
+    }
+}

dotnet/samples/03-workflows/Declarative/FunctionTools/Program.cs

@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Responses;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.FunctionTools;
+
+/// <summary>
+/// Demonstrate a workflow that responds to user input using an agent who
+/// with function tools assigned.  Exits the loop when the user enters "exit".
+/// </summary>
+/// <remarks>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agents exist in Foundry.
+        MenuPlugin menuPlugin = new();
+        AIFunction[] functions =
+            [
+                AIFunctionFactory.Create(menuPlugin.GetMenu),
+                AIFunctionFactory.Create(menuPlugin.GetSpecials),
+                AIFunctionFactory.Create(menuPlugin.GetItemPrice),
+            ];
+
+        await CreateAgentAsync(foundryEndpoint, configuration, functions);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.  This class demonstrates how to initialize a
+        // declarative workflow from a YAML file. Once the workflow is created, it
+        // can be executed just like any regular workflow.
+        WorkflowFactory workflowFactory = new("FunctionTools.yaml", foundryEndpoint);
+
+        // Execute the workflow:  The WorkflowRunner demonstrates how to execute
+        // a workflow, handle the workflow events, and providing external input.
+        // This also includes the ability to checkpoint workflow state and how to
+        // resume execution.
+        WorkflowRunner runner = new(functions) { UseJsonCheckpoints = true };
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration, AIFunction[] functions)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "MenuAgent",
+            agentDefinition: DefineMenuAgent(configuration, functions),
+            agentDescription: "Provides information about the restaurant menu");
+    }
+
+    private static DeclarativeAgentDefinition DefineMenuAgent(IConfiguration configuration, AIFunction[] functions)
+    {
+        DeclarativeAgentDefinition agentDefinition =
+            new(configuration.GetValue(Application.Settings.FoundryModel))
+            {
+                Instructions =
+                    """
+                    Answer the users questions on the menu.
+                    For questions or input that do not require searching the documentation, inform the
+                    user that you can only answer questions what's on the menu.
+                    """
+            };
+
+        foreach (AIFunction function in functions)
+        {
+            agentDefinition.Tools.Add(function.AsOpenAIResponseTool());
+        }
+
+        return agentDefinition;
+    }
+}

dotnet/samples/03-workflows/Declarative/FunctionTools/Properties/launchSettings.json

@@ -0,0 +1,11 @@
+{
+  "profiles": {
+    "Default": {
+      "commandName": "Project"
+    },
+    "Soup": {
+      "commandName": "Project",
+      "commandLineArgs": "\"What is the soup of the day?\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj

@@ -0,0 +1,39 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);CA1812</NoWarn>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="$(MSBuildThisFileDirectory)..\..\..\..\..\declarative-agents\workflow-samples\MathChat.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/HostedWorkflow/Program.cs

@@ -0,0 +1,176 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Uncomment this to enable JSON checkpointing to the local file system.
+//#define CHECKPOINT_JSON
+
+using Azure.AI.Extensions.OpenAI;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.DeclarativeWorkflow;
+
+/// <summary>
+/// %%% COMMENT
+/// </summary>
+/// <remarks>
+/// <b>Configuration</b>
+/// Define FOUNDRY_PROJECT_ENDPOINT as a user-secret or environment variable that
+/// points to your Foundry project endpoint.
+/// <b>Usage</b>
+/// Provide the path to the workflow definition file as the first argument.
+/// All other arguments are intepreted as a queue of inputs.
+/// When no input is queued, interactive input is requested from the console.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        // Create the agent service client
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        // Ensure sample agents exist in Foundry.
+        await CreateAgentsAsync(aiProjectClient, configuration);
+
+        // Ensure workflow agent exists in Foundry.
+        ProjectsAgentVersion agentVersion = await CreateWorkflowAsync(aiProjectClient, configuration);
+
+        string workflowInput = GetWorkflowInput(args);
+
+        FoundryAgent agent = aiProjectClient.AsAIAgent(agentVersion);
+
+        AgentSession session = await agent.CreateSessionAsync();
+
+        ProjectConversation conversation =
+            await aiProjectClient
+                .GetProjectOpenAIClient()
+                .GetProjectConversationsClient()
+                .CreateProjectConversationAsync()
+                .ConfigureAwait(false);
+
+        Console.WriteLine($"CONVERSATION: {conversation.Id}");
+
+        ChatOptions chatOptions =
+            new()
+            {
+                ConversationId = conversation.Id
+            };
+        ChatClientAgentRunOptions runOptions = new(chatOptions);
+
+        IAsyncEnumerable<AgentResponseUpdate> agentResponseUpdates = agent.RunStreamingAsync(workflowInput, session, runOptions);
+
+        string? lastMessageId = null;
+        await foreach (AgentResponseUpdate responseUpdate in agentResponseUpdates)
+        {
+            if (responseUpdate.MessageId != lastMessageId)
+            {
+                Console.WriteLine($"\n\n{responseUpdate.AuthorName ?? responseUpdate.AgentId}");
+            }
+
+            lastMessageId = responseUpdate.MessageId;
+
+            Console.Write(responseUpdate.Text);
+        }
+    }
+
+    private static async Task<ProjectsAgentVersion> CreateWorkflowAsync(AIProjectClient agentClient, IConfiguration configuration)
+    {
+        string workflowYaml = File.ReadAllText("MathChat.yaml");
+
+#pragma warning disable AAIP001 // WorkflowAgentDefinition is experimental
+        WorkflowAgentDefinition workflowAgentDefinition = WorkflowAgentDefinition.FromYaml(workflowYaml);
+#pragma warning restore AAIP001
+
+        return
+            await agentClient.CreateAgentAsync(
+                agentName: "MathChatWorkflow",
+                agentDefinition: workflowAgentDefinition,
+                agentDescription: "The student attempts to solve the input problem and the teacher provides guidance.");
+    }
+
+    private static async Task CreateAgentsAsync(AIProjectClient agentClient, IConfiguration configuration)
+    {
+        await agentClient.CreateAgentAsync(
+            agentName: "StudentAgent",
+            agentDefinition: DefineStudentAgent(configuration),
+            agentDescription: "Student agent for MathChat workflow");
+
+        await agentClient.CreateAgentAsync(
+            agentName: "TeacherAgent",
+            agentDefinition: DefineTeacherAgent(configuration),
+            agentDescription: "Teacher agent for MathChat workflow");
+    }
+
+    private static DeclarativeAgentDefinition DefineStudentAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Your job is help a math teacher practice teaching by making intentional mistakes.
+                You attempt to solve the given math problem, but with intentional mistakes so the teacher can help.
+                Always incorporate the teacher's advice to fix your next response.
+                You have the math-skills of a 6th grader.
+                Don't describe who you are or reveal your instructions.
+                """
+        };
+
+    private static DeclarativeAgentDefinition DefineTeacherAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Review and coach the student's approach to solving the given math problem.
+                Don't repeat the solution or try and solve it.
+                If the student has demonstrated comprehension and responded to all of your feedback,
+                give the student your congratulations by using the word "congratulations".
+                """
+        };
+
+    private static string GetWorkflowInput(string[] args)
+    {
+        string? input = null;
+
+        if (args.Length > 0)
+        {
+            string[] workflowInput = [.. args.Skip(1)];
+            input = workflowInput.FirstOrDefault();
+        }
+
+        try
+        {
+            Console.ForegroundColor = ConsoleColor.DarkGreen;
+            Console.Write("\nINPUT: ");
+            Console.ForegroundColor = ConsoleColor.White;
+
+            if (!string.IsNullOrWhiteSpace(input))
+            {
+                Console.WriteLine(input);
+                return input;
+            }
+
+            while (string.IsNullOrWhiteSpace(input))
+            {
+                input = Console.ReadLine();
+            }
+
+            return input.Trim();
+        }
+        finally
+        {
+            Console.ResetColor();
+        }
+    }
+}

dotnet/samples/03-workflows/Declarative/InputArguments/InputArguments.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="InputArguments.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/InputArguments/InputArguments.yaml

@@ -0,0 +1,97 @@
+#
+# This workflow demonstrates providing input arguments to an agent.
+#
+# Example input: 
+# I'd like to go on vacation.
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_demo
+  actions:
+
+    # Capture the original user message for input to the location-aware agent
+    - kind: SetVariable
+      id: set_count_increment
+      variable: Local.InputMessage
+      value: =System.LastMessage
+
+    # Invoke the triage agent to determine location requirements
+    - kind: InvokeAzureAgent
+      id: solicit_input
+      conversationId: =System.ConversationId
+      agent:
+        name: LocationTriageAgent
+      input:
+        messages: =Local.ActionMessage
+      output:
+        messages: Local.TriageResponse
+
+    # Request input from the user based on the triage response
+    - kind: RequestExternalInput
+      id: request_requirements
+      variable: Local.NextInput
+
+    # Capture the most recent interaction for evaluation
+    - kind: SetTextVariable
+      id: set_status_message
+      variable: Local.LocationStatusInput
+      value: |-
+          AGENT - {MessageText(Local.TriageResponse)}
+
+          USER - {MessageText(Local.NextInput)}
+
+    # Evaluate the status of the location triage
+    - kind: InvokeAzureAgent
+      id: evaluate_location
+      agent:
+        name: LocationCaptureAgent
+      input:
+        messages: =UserMessage(Local.LocationStatusInput)
+      output:
+        responseObject: Local.LocationResponse
+
+    # Determine if the location information is complete
+    - kind: ConditionGroup
+      id: check_completion
+      conditions:
+
+        - condition: |-
+            =Local.LocationResponse.is_location_defined = false Or
+             Local.LocationResponse.is_location_confirmed = false
+          id: check_done
+          actions:
+
+            # Capture the action message for input to the triage agent
+            - kind: SetVariable
+              id: set_next_message
+              variable: Local.ActionMessage
+              value: =AgentMessage(Local.LocationResponse.action)
+
+            - kind: GotoAction
+              id: goto_solicit_input
+              actionId: solicit_input
+
+      elseActions:
+
+    # Create a new conversation so the prior context does not interfere
+    - kind: CreateConversation
+      id: conversation_location
+      conversationId: Local.LocationConversationId
+
+    # Invoke the location-aware agent with the location argument
+    # and loop until the user types "EXIT"
+    - kind: InvokeAzureAgent
+      id: location_response
+      conversationId: =Local.LocationConversationId
+      agent:
+        name: LocationAwareAgent
+      input:
+        messages: =Local.InputMessage
+        arguments:
+          location: =Local.LocationResponse.place
+        externalLoop:
+          when: =Upper(System.LastMessage.Text) <> "EXIT"
+      output:
+        autoSend: true

dotnet/samples/03-workflows/Declarative/InputArguments/Program.cs

@@ -0,0 +1,151 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Responses;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.InputArguments;
+
+/// <summary>
+/// Demonstrate a workflow that consumes input arguments to dynamically enhance the agent
+/// instructions.  Exits the loop when the user enters "exit".
+/// </summary>
+/// <remarks>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agents exist in Foundry.
+        await CreateAgentAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.  This class demonstrates how to initialize a
+        // declarative workflow from a YAML file. Once the workflow is created, it
+        // can be executed just like any regular workflow.
+        WorkflowFactory workflowFactory = new("InputArguments.yaml", foundryEndpoint);
+
+        // Execute the workflow:  The WorkflowRunner demonstrates how to execute
+        // a workflow, handle the workflow events, and providing external input.
+        // This also includes the ability to checkpoint workflow state and how to
+        // resume execution.
+        WorkflowRunner runner = new();
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "LocationTriageAgent",
+            agentDefinition: DefineLocationTriageAgent(configuration),
+            agentDescription: "Chats with the user to solicit a location of interest.");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "LocationCaptureAgent",
+            agentDefinition: DefineLocationCaptureAgent(configuration),
+            agentDescription: "Evaluate the status of soliciting the location.");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "LocationAwareAgent",
+            agentDefinition: DefineLocationAwareAgent(configuration),
+            agentDescription: "Chats with the user with location awareness.");
+    }
+
+    private static DeclarativeAgentDefinition DefineLocationTriageAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Your only job is to solicit a location from the user.
+
+                Always repeat back the location when addressing the user, except when it is not known.
+                """
+        };
+
+    private static DeclarativeAgentDefinition DefineLocationCaptureAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Request a location from the user.  This location could be their own location
+                or perhaps a location they are interested in.
+
+                City level precision is sufficient.
+
+                If extrapolating region and country, confirm you have it right.
+                """,
+            TextOptions =
+                new ResponseTextOptions
+                {
+                    TextFormat =
+                        ResponseTextFormat.CreateJsonSchemaFormat(
+                            "TaskEvaluation",
+                            BinaryData.FromString(
+                                """
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "place": {
+                                      "type": "string",
+                                      "description": "Captures only your understanding of the location specified by the user without explanation, or 'unknown' if not yet defined."
+                                    },
+                                    "action": {
+                                      "type": "string",
+                                      "description": "The instruction for the next action to take regarding the need for additional detail or confirmation."
+                                    },
+                                    "is_location_defined": {
+                                      "type": "boolean",
+                                      "description": "True if the user location is understood."
+                                    },
+                                    "is_location_confirmed": {
+                                      "type": "boolean",
+                                      "description": "True if the user location is confirmed.  An unambiguous location may be implicitly confirmed without explicit user confirmation."
+                                    }
+                                  },
+                                  "required": ["place", "action", "is_location_defined", "is_location_confirmed"],
+                                  "additionalProperties": false
+                                }
+                                """),
+                            jsonSchemaFormatDescription: null,
+                            jsonSchemaIsStrict: true),
+                }
+        };
+
+    private static DeclarativeAgentDefinition DefineLocationAwareAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            // Parameterized instructions reference the "location" input argument.
+            Instructions =
+                """
+                Talk to the user about their request.
+                Their request is related to a specific location: {{location}}.
+                """,
+            StructuredInputs =
+            {
+                ["location"] =
+                    new StructuredInputDefinition
+                    {
+                        IsRequired = false,
+                        DefaultValue = BinaryData.FromString(@"""unknown"""),
+                        Description = "The user's location",
+                    }
+            }
+        };
+}

dotnet/samples/03-workflows/Declarative/InputArguments/Properties/launchSettings.json

@@ -0,0 +1,11 @@
+{
+  "profiles": {
+    "Default": {
+      "commandName": "Project"
+    },
+    "Vacation": {
+      "commandName": "Project",
+      "commandLineArgs": "\"I'd like to go on vacation.\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/InvokeFoundryToolboxMcp/InvokeFoundryToolboxMcp.csproj

@@ -0,0 +1,42 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+    <PackageReference Include="OpenAI" />
+    <PackageReference Include="System.ClientModel" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Mcp\Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="InvokeFoundryToolboxMcp.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/InvokeFoundryToolboxMcp/InvokeFoundryToolboxMcp.yaml

@@ -0,0 +1,87 @@
+#
+# This workflow demonstrates invoking MCP tools through a Foundry toolbox MCP proxy.
+#
+# The toolbox is provisioned with TWO different tool types:
+#   1. A Foundry built-in web_search tool
+#   2. A Microsoft Learn MCP server (microsoft_docs)
+# Both are surfaced through the same MCP-compatible toolbox endpoint.
+#
+# The workflow:
+# 1. Accepts a documentation/web search query as input
+# 2. Lists the tools exposed by the Foundry toolbox using reserved toolName: tools/list
+# 3. Invokes the microsoft_docs_search MCP tool
+# 4. Invokes the built-in web_search tool against the same toolbox endpoint
+# 5. Uses an agent to summarize and combine both result sets
+#
+# Example input:
+# How do I use Azure OpenAI with my data?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_invoke_foundry_toolbox_mcp
+  actions:
+
+    # Set the search query from user input.
+    - kind: SetVariable
+      id: set_search_query
+      variable: Local.SearchQuery
+      value: =System.LastMessage.Text
+
+    # List tools exposed by the Foundry toolbox MCP proxy.
+    - kind: InvokeMcpTool
+      id: list_toolbox_tools
+      serverUrl: =Env.FOUNDRY_TOOLBOX_MCP_SERVER_URL
+      serverLabel: foundry_toolbox
+      toolName: tools/list
+      conversationId: =System.ConversationId
+      headers:
+        Foundry-Features: Toolboxes=V1Preview
+      output:
+        autoSend: true
+        result: Local.ToolboxTools
+
+    # Invoke a specific tool exposed through the toolbox and add the result to the conversation.
+    - kind: InvokeMcpTool
+      id: search_docs_with_toolbox
+      serverUrl: =Env.FOUNDRY_TOOLBOX_MCP_SERVER_URL
+      serverLabel: foundry_toolbox
+      toolName: =Env.FOUNDRY_TOOLBOX_DOCS_SERVER_LABEL & "___microsoft_docs_search"
+      conversationId: =System.ConversationId
+      headers:
+        Foundry-Features: Toolboxes=V1Preview
+      arguments:
+        query: =Local.SearchQuery
+      output:
+        autoSend: true
+        result: Local.SearchResult
+
+    # Invoke the web_search built-in tool through the same toolbox proxy. The toolbox surfaces
+    # built-in Foundry tools (like web_search) alongside MCP tools through one MCP-compatible
+    # endpoint. Note that web_search expects argument 'search_query' (not 'query').
+    - kind: InvokeMcpTool
+      id: search_web_with_toolbox
+      serverUrl: =Env.FOUNDRY_TOOLBOX_MCP_SERVER_URL
+      serverLabel: foundry_toolbox
+      toolName: =Env.FOUNDRY_TOOLBOX_WEB_SEARCH_TOOL_NAME
+      conversationId: =System.ConversationId
+      headers:
+        Foundry-Features: Toolboxes=V1Preview
+      arguments:
+        search_query: =Local.SearchQuery
+      output:
+        autoSend: true
+        result: Local.WebSearchResult
+
+    # Use the agent to summarize what happened and answer from the toolbox result.
+    - kind: InvokeAzureAgent
+      id: summarize_toolbox_result
+      agent:
+        name: FoundryToolboxMcpAgent
+      conversationId: =System.ConversationId
+      input:
+        messages: =UserMessage("Combine the Microsoft Learn docs results and the Foundry web search results in the conversation to answer the query " & Local.SearchQuery)
+      output:
+        autoSend: true
+        messages: Local.Summary

dotnet/samples/03-workflows/Declarative/InvokeFoundryToolboxMcp/Program.cs

@@ -0,0 +1,219 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates using InvokeMcpTool to call MCP tools through a Foundry toolbox.
+// It creates a sample toolbox that exposes Microsoft Learn MCP tools, lists the toolbox tools
+// through the reserved tools/list operation, then calls microsoft_docs_search from the workflow.
+
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Collections.Concurrent;
+using System.Net.Http.Headers;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Core;
+using Azure.Identity;
+using Microsoft.Agents.AI.Workflows.Declarative.Mcp;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Responses;
+using Shared.Foundry;
+using Shared.Workflows;
+
+#pragma warning disable OPENAI001 // Experimental API
+#pragma warning disable AAIP001 // AgentToolboxes is experimental
+
+namespace Demo.Workflows.Declarative.InvokeFoundryToolboxMcp;
+
+/// <summary>
+/// Demonstrates a workflow that uses InvokeMcpTool to call MCP tools exposed through a Foundry toolbox.
+/// </summary>
+/// <remarks>
+/// This sample provisions a toolbox with Microsoft Learn MCP tools, uses the reserved
+/// <c>tools/list</c> tool name to list the toolbox tools, calls one specific toolbox tool,
+/// and has a Foundry agent summarize the results.
+/// </remarks>
+internal sealed class Program
+{
+    private const string ToolboxNameSetting = "FOUNDRY_TOOLBOX_NAME";
+    private const string ToolboxApiVersionSetting = "FOUNDRY_AGENT_TOOLSET_API_VERSION";
+    private const string ToolboxMcpServerUrlSetting = "FOUNDRY_TOOLBOX_MCP_SERVER_URL";
+    private const string DocsServerLabelSetting = "FOUNDRY_TOOLBOX_DOCS_SERVER_LABEL";
+    private const string WebSearchToolNameSetting = "FOUNDRY_TOOLBOX_WEB_SEARCH_TOOL_NAME";
+    private const string DefaultToolboxName = "declarative_foundry_toolbox_mcp";
+    private const string DefaultToolboxApiVersion = "v1";
+    private const string DefaultDocsServerLabel = "microsoft_docs";
+    private const string DefaultWebSearchToolName = "web_search";
+
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+        string toolboxName = configuration[ToolboxNameSetting] ?? DefaultToolboxName;
+        string toolboxApiVersion = configuration[ToolboxApiVersionSetting] ?? DefaultToolboxApiVersion;
+        string docsServerLabel = configuration[DocsServerLabelSetting] ?? DefaultDocsServerLabel;
+        string webSearchToolName = configuration[WebSearchToolNameSetting] ?? DefaultWebSearchToolName;
+
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        DefaultAzureCredential credential = new();
+
+        // Ensure sample toolbox and agent exist in Foundry
+        string toolboxEndpoint = await CreateSampleToolboxAsync(toolboxName, docsServerLabel, foundryEndpoint, credential);
+        string toolboxMcpServerUrl = BuildToolboxMcpServerUrl(toolboxEndpoint, toolboxName, toolboxApiVersion);
+        IConfiguration workflowConfiguration = new ConfigurationBuilder()
+            .AddConfiguration(configuration)
+            .AddInMemoryCollection(new Dictionary<string, string?>
+            {
+                [ToolboxMcpServerUrlSetting] = toolboxMcpServerUrl,
+                [DocsServerLabelSetting] = docsServerLabel,
+                [WebSearchToolNameSetting] = webSearchToolName,
+            })
+            .Build();
+
+        await CreateAgentAsync(foundryEndpoint, configuration, credential);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the MCP tool handler for invoking the Foundry toolbox MCP proxy.
+        ConcurrentBag<HttpClient> createdHttpClients = [];
+        DefaultMcpToolHandler mcpToolHandler = new(
+            httpClientProvider: async (serverUrl, _) =>
+            {
+                await Task.CompletedTask.ConfigureAwait(false);
+
+                if (!string.Equals(serverUrl, toolboxMcpServerUrl, StringComparison.OrdinalIgnoreCase))
+                {
+                    return null;
+                }
+
+                FoundryToolboxBearerTokenHandler handler = new(credential)
+                {
+                    InnerHandler = new HttpClientHandler()
+                };
+                HttpClient httpClient = new(handler);
+                createdHttpClients.Add(httpClient);
+                return httpClient;
+            });
+
+        try
+        {
+            // Create the workflow factory with MCP tool provider
+            WorkflowFactory workflowFactory = new("InvokeFoundryToolboxMcp.yaml", foundryEndpoint)
+            {
+                Configuration = workflowConfiguration,
+                McpToolHandler = mcpToolHandler
+            };
+
+            // Execute the workflow
+            WorkflowRunner runner = new() { UseJsonCheckpoints = true };
+            await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+        }
+        finally
+        {
+            // Clean up connections and dispose created HttpClients
+            await mcpToolHandler.DisposeAsync();
+
+            foreach (HttpClient httpClient in createdHttpClients)
+            {
+                httpClient.Dispose();
+            }
+        }
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration, TokenCredential credential)
+    {
+        AIProjectClient aiProjectClient = new(foundryEndpoint, credential);
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "FoundryToolboxMcpAgent",
+            agentDefinition: DefineToolboxAgent(configuration),
+            agentDescription: "Summarizes Foundry toolbox MCP tool results");
+    }
+
+    private static DeclarativeAgentDefinition DefineToolboxAgent(IConfiguration configuration)
+    {
+        return new DeclarativeAgentDefinition(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                You are a helpful assistant that explains results produced by tools exposed through a Foundry toolbox.
+                The conversation history contains output from BOTH a Microsoft Learn documentation search (MCP) and a Foundry web search.
+                Synthesize an answer that draws on both sources, calls out where they agree or differ, and notes which toolbox tool produced each fact when it is relevant.
+                Be concise.
+                """
+        };
+    }
+
+    private static async Task<string> CreateSampleToolboxAsync(string name, string serverLabel, Uri foundryEndpoint, TokenCredential credential)
+    {
+        AgentAdministrationClientOptions options = new();
+        options.AddPolicy(new FoundryFeaturesPolicy("Toolboxes=V1Preview"), PipelinePosition.PerCall);
+        AgentAdministrationClient adminClient = new(foundryEndpoint, credential, options);
+        AgentToolboxes toolboxClient = adminClient.GetAgentToolboxes();
+
+        try
+        {
+            await toolboxClient.DeleteAsync(name);
+            Console.WriteLine($"Deleted existing toolbox '{name}'");
+        }
+        catch (ClientResultException ex) when (ex.Status == 404)
+        {
+            // Toolbox does not exist.
+        }
+
+        WebSearchToolboxTool webTool = new();
+
+        MCPToolboxTool mcpTool = new(serverLabel)
+        {
+            ServerUri = new Uri("https://learn.microsoft.com/api/mcp"),
+            ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
+        };
+
+        ToolboxVersion created = (await toolboxClient.CreateVersionAsync(
+            name: name,
+            tools: [webTool, mcpTool],
+            description: "Sample toolbox combining Foundry web search with the Microsoft Learn MCP tools for the declarative InvokeFoundryToolboxMcp sample.")).Value;
+
+        Console.WriteLine($"Created toolbox '{created.Name}' v{created.Version} ({created.Tools.Count} tool(s))");
+
+        return $"{foundryEndpoint.ToString().TrimEnd('/')}/toolboxes";
+    }
+
+    private static string BuildToolboxMcpServerUrl(string toolboxEndpoint, string toolboxName, string apiVersion) =>
+        $"{toolboxEndpoint.TrimEnd('/')}/{toolboxName}/mcp?api-version={Uri.EscapeDataString(apiVersion)}";
+
+    private sealed class FoundryToolboxBearerTokenHandler(TokenCredential credential) : DelegatingHandler
+    {
+        private static readonly TokenRequestContext s_tokenContext =
+            new(["https://ai.azure.com/.default"]);
+
+        protected override async Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken)
+        {
+            AccessToken token = await credential.GetTokenAsync(s_tokenContext, cancellationToken);
+            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
+
+            return await base.SendAsync(request, cancellationToken);
+        }
+    }
+
+    private sealed class FoundryFeaturesPolicy(string feature) : PipelinePolicy
+    {
+        private const string FeatureHeader = "Foundry-Features";
+
+        public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Add(FeatureHeader, feature);
+            ProcessNext(message, pipeline, currentIndex);
+        }
+
+        public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+        {
+            message.Request.Headers.Add(FeatureHeader, feature);
+            return ProcessNextAsync(message, pipeline, currentIndex);
+        }
+    }
+}

dotnet/samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="InvokeFunctionTool.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.yaml

@@ -0,0 +1,55 @@
+#
+# This workflow demonstrates using InvokeFunctionTool to call functions directly
+# from the workflow without going through an AI agent first.
+#
+# InvokeFunctionTool allows workflows to:
+# - Pre-fetch data before calling an AI agent
+# - Execute operations directly without AI involvement
+# - Store function results in workflow variables for later use
+#
+# Example input: 
+# What are the specials in the menu?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_invoke_function_tool_demo
+  actions:
+
+    # Invoke GetSpecials function to get today's specials directly from the workflow
+    - kind: InvokeFunctionTool
+      id: invoke_get_specials
+      conversationId: =System.ConversationId
+      requireApproval: true
+      functionName: GetSpecials
+      output:
+        autoSend: true
+        result: Local.Specials
+        messages: Local.FunctionMessage
+
+    # Display a message showing we retrieved the specials
+    - kind: SendMessage
+      id: show_specials_intro
+      message: "Today's specials have been retrieved. Here they are: {Local.Specials}"
+
+    # Now use an agent to format and present the specials to the user
+    - kind: InvokeAzureAgent
+      id: invoke_menu_agent
+      conversationId: =System.ConversationId
+      agent:
+        name: FunctionMenuAgent
+      input:
+        messages: =UserMessage("Please describe today's specials in an appealing way.")
+      output:
+        messages: Local.AgentResponse
+
+    # Allow the user to ask follow-up questions in a loop
+    - kind: InvokeAzureAgent
+      id: invoke_followup
+      conversationId: =System.ConversationId
+      agent:
+        name: FunctionMenuAgent
+      input:
+        externalLoop:
+          when: =Upper(System.LastMessage.Text) <> "EXIT"

dotnet/samples/03-workflows/Declarative/InvokeFunctionTool/MenuPlugin.cs

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+
+namespace Demo.Workflows.Declarative.InvokeFunctionTool;
+
+#pragma warning disable CA1822 // Mark members as static
+
+/// <summary>
+/// Plugin providing menu-related functions that can be invoked directly by the workflow
+/// using the InvokeFunctionTool action.
+/// </summary>
+public sealed class MenuPlugin
+{
+    [Description("Provides a list items on the menu.")]
+    public MenuItem[] GetMenu()
+    {
+        return s_menuItems;
+    }
+
+    [Description("Provides a list of specials from the menu.")]
+    public MenuItem[] GetSpecials()
+    {
+        return [.. s_menuItems.Where(i => i.IsSpecial)];
+    }
+
+    [Description("Provides the price of the requested menu item.")]
+    public float? GetItemPrice(
+        [Description("The name of the menu item.")]
+        string name)
+    {
+        return s_menuItems.FirstOrDefault(i => i.Name.Equals(name, StringComparison.OrdinalIgnoreCase))?.Price;
+    }
+
+    private static readonly MenuItem[] s_menuItems =
+        [
+            new()
+            {
+                Category = "Soup",
+                Name = "Clam Chowder",
+                Price = 4.95f,
+                IsSpecial = true,
+            },
+            new()
+            {
+                Category = "Soup",
+                Name = "Tomato Soup",
+                Price = 4.95f,
+                IsSpecial = false,
+            },
+            new()
+            {
+                Category = "Salad",
+                Name = "Cobb Salad",
+                Price = 9.99f,
+            },
+            new()
+            {
+                Category = "Salad",
+                Name = "House Salad",
+                Price = 4.95f,
+            },
+            new()
+            {
+                Category = "Drink",
+                Name = "Chai Tea",
+                Price = 2.95f,
+                IsSpecial = true,
+            },
+            new()
+            {
+                Category = "Drink",
+                Name = "Soda",
+                Price = 1.95f,
+            },
+        ];
+
+    public sealed class MenuItem
+    {
+        public string Category { get; init; } = string.Empty;
+        public string Name { get; init; } = string.Empty;
+        public float Price { get; init; }
+        public bool IsSpecial { get; init; }
+    }
+}

dotnet/samples/03-workflows/Declarative/InvokeFunctionTool/Program.cs

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Responses;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.InvokeFunctionTool;
+
+/// <summary>
+/// Demonstrate a workflow that uses InvokeFunctionTool to call functions directly
+/// from the workflow without going through an AI agent first.
+/// </summary>
+/// <remarks>
+/// The InvokeFunctionTool action allows workflows to invoke function tools directly,
+/// enabling pre-fetching of data or executing operations before calling an AI agent.
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Create the menu plugin with functions that can be invoked directly by the workflow
+        MenuPlugin menuPlugin = new();
+        AIFunction[] functions =
+            [
+                AIFunctionFactory.Create(menuPlugin.GetMenu),
+                AIFunctionFactory.Create(menuPlugin.GetSpecials),
+                AIFunctionFactory.Create(menuPlugin.GetItemPrice),
+            ];
+
+        // Ensure sample agent exists in Foundry
+        await CreateAgentAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.
+        WorkflowFactory workflowFactory = new("InvokeFunctionTool.yaml", foundryEndpoint);
+
+        // Execute the workflow
+        WorkflowRunner runner = new(functions) { UseJsonCheckpoints = true };
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "FunctionMenuAgent",
+            agentDefinition: DefineMenuAgent(configuration, []), // Create Agent with no function tool in the definition.
+            agentDescription: "Provides information about the restaurant menu");
+    }
+
+    private static DeclarativeAgentDefinition DefineMenuAgent(IConfiguration configuration, AIFunction[] functions)
+    {
+        DeclarativeAgentDefinition agentDefinition =
+            new(configuration.GetValue(Application.Settings.FoundryModel))
+            {
+                Instructions =
+                    """
+                    Answer the users questions about the menu.
+                    Use the information provided in the conversation history to answer questions.
+                    If the information is already available in the conversation, use it directly.
+                    For questions or input that do not require searching the documentation, inform the
+                    user that you can only answer questions about what's on the menu.
+                    """
+            };
+
+        foreach (AIFunction function in functions)
+        {
+            agentDefinition.Tools.Add(function.AsOpenAIResponseTool());
+        }
+
+        return agentDefinition;
+    }
+}

dotnet/samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="InvokeHttpRequest.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.yaml

@@ -0,0 +1,76 @@
+#
+# This workflow demonstrates using HttpRequestAction to call a REST API directly
+# from the workflow without going through an AI agent first.
+#
+# HttpRequestAction allows workflows to:
+# - Fetch data from external HTTP endpoints
+# - Store the parsed response in workflow variables for later use
+# - Add the response body to the conversation so a downstream agent can
+#   answer questions based on it
+#
+# This sample fetches public metadata for the dotnet/runtime repository from
+# the GitHub REST API (no authentication required) and uses an agent to
+# answer follow-up questions about it.
+#
+# Example input:
+# How many subscribers does the repository have?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_invoke_http_request_demo
+  actions:
+
+    # Capture the original user message for input to the follow-up agent.
+    - kind: SetVariable
+      id: set_user_message
+      variable: Local.InputMessage
+      value: =System.LastMessage
+
+    # Set the repository org/name used to form the request URL.
+    - kind: SetVariable
+      id: set_repo_name
+      variable: Local.RepoName
+      value: microsoft/agent-framework
+
+    # Invoke the GitHub repo API. The response body is parsed into Local.RepoInfo
+    # and also added to the conversation (via conversationId) so the agent below
+    # can answer questions based on it.
+    - kind: HttpRequestAction
+      id: fetch_repo_info
+      conversationId: =System.ConversationId
+      method: GET
+      url: =Concatenate("https://api.github.com/repos/", Local.RepoName)
+      headers:
+        Accept: application/vnd.github+json
+        User-Agent: agent-framework-sample
+      response: Local.RepoInfo
+
+    # Display a confirmation message showing key fields from the parsed response.
+    - kind: SendMessage
+      id: show_repo_summary
+      message: "Fetched repo: visibility={Local.RepoInfo.visibility}, description={Local.RepoInfo.description}"
+
+    # Use the agent to summarize the repo using the conversation context.
+    - kind: InvokeAzureAgent
+      id: summarize_repo
+      conversationId: =System.ConversationId
+      agent:
+        name: GitHubRepoInfoAgent
+      input:
+        messages: =UserMessage("Please provide a brief summary of this GitHub repository based on the data already in the conversation.")
+      output:
+        autoSend: true
+        messages: Local.AgentResponse
+
+    # Allow the user to ask follow-up questions about the repo in a loop.
+    - kind: InvokeAzureAgent
+      id: invoke_followup
+      conversationId: =System.ConversationId
+      agent:
+        name: GitHubRepoInfoAgent
+      input:
+        messages: =Local.InputMessage
+        externalLoop:
+          when: =Upper(System.LastMessage.Text) <> "EXIT"

dotnet/samples/03-workflows/Declarative/InvokeHttpRequest/Program.cs

@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI.Workflows.Declarative;
+using Microsoft.Extensions.Configuration;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.InvokeHttpRequest;
+
+/// <summary>
+/// Demonstrates a workflow that uses HttpRequestAction to call a REST API
+/// directly from the workflow.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The HttpRequestAction allows workflows to issue HTTP requests and:
+/// </para>
+/// <list type="bullet">
+/// <item>Fetch data from external REST endpoints</item>
+/// <item>Store the parsed response in workflow variables</item>
+/// <item>Add the response body to the conversation so an agent can answer
+///       questions based on it</item>
+/// </list>
+/// <para>
+/// This sample fetches public metadata for the dotnet/runtime repository from
+/// the GitHub REST API (no authentication required) and uses a Foundry agent
+/// to answer follow-up questions about it. Type "EXIT" to end the conversation.
+/// </para>
+/// <para>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </para>
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agent exists in Foundry. The agent has no tools - it answers
+        // questions about the GitHub repository using only the JSON data that the
+        // HttpRequestAction adds to the conversation.
+        await CreateAgentAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // The default HttpRequestHandler is sufficient for this sample because the
+        // GitHub REST endpoint used here does not require authentication. For
+        // authenticated endpoints, supply a custom Func<HttpRequestInfo, ..., HttpClient?>
+        // to DefaultHttpRequestHandler so each request can be routed through a
+        // pre-configured (cached) HttpClient with the appropriate credentials.
+        await using DefaultHttpRequestHandler httpRequestHandler = new();
+
+        // Create the workflow factory with the HTTP request handler
+        WorkflowFactory workflowFactory = new("InvokeHttpRequest.yaml", foundryEndpoint)
+        {
+            HttpRequestHandler = httpRequestHandler
+        };
+
+        // Execute the workflow
+        WorkflowRunner runner = new() { UseJsonCheckpoints = true };
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "GitHubRepoInfoAgent",
+            agentDefinition: DefineAgent(configuration),
+            agentDescription: "Answers questions about a GitHub repository using HTTP response data in the conversation");
+    }
+
+    private static DeclarativeAgentDefinition DefineAgent(IConfiguration configuration)
+    {
+        return new DeclarativeAgentDefinition(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Answer the user's questions about the GitHub repository using only the
+                JSON data already present in the conversation history.
+                If the answer is not contained in the conversation, say so plainly
+                rather than guessing. Be concise and helpful.
+                """
+        };
+    }
+}

dotnet/samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.csproj

@@ -0,0 +1,39 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Mcp\Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="InvokeMcpTool.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.yaml

@@ -0,0 +1,63 @@
+#
+# This workflow demonstrates invoking MCP tools directly from a declarative workflow.
+# Uses the Foundry MCP server to search AI model details.
+#
+# The workflow:
+# 1. Accepts a model search term as input
+# 2. Invokes the Foundry MCP tool
+# 3. Invokes the Microsoft Learn MCP tool
+# 4. Uses an agent to summarize the results
+#
+# Example input: 
+# gpt-5.4-mini
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_invoke_mcp_tool
+  actions:
+
+    # Set the search query from user input or use default
+    - kind: SetVariable
+      id: set_search_query
+      variable: Local.SearchQuery
+      value: =System.LastMessage.Text
+
+    # Invoke MCP search tool on Foundry MCP server
+    - kind: InvokeMcpTool
+      id: invoke_foundry_search
+      serverUrl: https://mcp.ai.azure.com
+      serverLabel: azure_mcp_server
+      toolName: model_details_get
+      conversationId: =System.ConversationId
+      arguments:
+        modelName: =Local.SearchQuery
+      output:
+        autoSend: true
+        result: Local.FoundrySearchResult
+
+    # Invoke MCP search tool on Microsoft Learn server
+    - kind: InvokeMcpTool
+      id: invoke_docs_search
+      serverUrl: https://learn.microsoft.com/api/mcp
+      serverLabel: microsoft_docs
+      toolName: microsoft_docs_search
+      conversationId: =System.ConversationId
+      arguments:
+        query: =Local.SearchQuery
+      output:
+        autoSend: true
+        result: Local.DocsSearchResult
+
+    # Use the search agent to provide a helpful response based on results
+    - kind: InvokeAzureAgent
+      id: summarize_results
+      agent:
+        name: McpSearchAgent
+      conversationId: =System.ConversationId
+      input:
+        messages: =UserMessage("Based on the search results for '" & Local.SearchQuery & "', please provide a helpful summary.")
+      output:
+        autoSend: true
+        result: Local.Summary

dotnet/samples/03-workflows/Declarative/InvokeMcpTool/Program.cs

@@ -0,0 +1,141 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates using the InvokeMcpTool action to call MCP (Model Context Protocol)
+// server tools directly from a declarative workflow. MCP servers expose tools that can be
+// invoked to perform specific tasks, like searching documentation or executing operations.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Core;
+using Azure.Identity;
+using Microsoft.Agents.AI.Workflows.Declarative.Mcp;
+using Microsoft.Extensions.Configuration;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.InvokeMcpTool;
+
+/// <summary>
+/// Demonstrates a workflow that uses InvokeMcpTool to call MCP server tools
+/// directly from the workflow.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The InvokeMcpTool action allows workflows to invoke tools on MCP (Model Context Protocol)
+/// servers. This enables:
+/// </para>
+/// <list type="bullet">
+/// <item>Searching external data sources like documentation</item>
+/// <item>Executing operations on remote servers</item>
+/// <item>Integrating with MCP-compatible services</item>
+/// </list>
+/// <para>
+/// This sample uses the Microsoft Learn MCP server to search Azure documentation and the Microsoft Foundry MCP server to get AI model details.
+/// When you run the sample, provide an AI model (e.g. gpt-5.4-mini) as input,
+/// The workflow will use the MCP tools to find relevant information about the model from Microsoft Learn and foundry, then an agent will summarize the results.
+/// </para>
+/// <para>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </para>
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agent exists in Foundry
+        await CreateAgentAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the MCP tool handler for invoking MCP server tools.
+        // The HttpClient callback allows configuring authentication per MCP server.
+        // Different MCP servers may require different authentication configurations.
+        // For Production scenarios, consider implementing a more robust HttpClient management strategy to reuse HttpClient instances and manage their lifetimes appropriately.
+        List<HttpClient> createdHttpClients = [];
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        DefaultAzureCredential credential = new();
+        DefaultMcpToolHandler mcpToolHandler = new(
+            httpClientProvider: async (serverUrl, cancellationToken) =>
+            {
+                if (serverUrl.StartsWith("https://mcp.ai.azure.com", StringComparison.OrdinalIgnoreCase))
+                {
+                    // Acquire token for the Azure MCP server
+                    AccessToken token = await credential.GetTokenAsync(
+                        new TokenRequestContext(["https://mcp.ai.azure.com/.default"]),
+                        cancellationToken);
+
+                    // Create HttpClient with Authorization header
+                    HttpClient httpClient = new();
+                    httpClient.DefaultRequestHeaders.Authorization =
+                        new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token.Token);
+                    createdHttpClients.Add(httpClient);
+                    return httpClient;
+                }
+
+                if (serverUrl.StartsWith("https://learn.microsoft.com", StringComparison.OrdinalIgnoreCase))
+                {
+                    // Microsoft Learn MCP server does not require authentication
+                    HttpClient httpClient = new();
+                    createdHttpClients.Add(httpClient);
+                    return httpClient;
+                }
+
+                // Return null for unknown servers to use the default HttpClient without auth.
+                return null;
+            });
+
+        try
+        {
+            // Create the workflow factory with MCP tool provider
+            WorkflowFactory workflowFactory = new("InvokeMcpTool.yaml", foundryEndpoint)
+            {
+                McpToolHandler = mcpToolHandler
+            };
+
+            // Execute the workflow
+            WorkflowRunner runner = new() { UseJsonCheckpoints = true };
+            await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+        }
+        finally
+        {
+            // Clean up connections and dispose created HttpClients
+            await mcpToolHandler.DisposeAsync();
+
+            foreach (HttpClient httpClient in createdHttpClients)
+            {
+                httpClient.Dispose();
+            }
+        }
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "McpSearchAgent",
+            agentDefinition: DefineSearchAgent(configuration),
+            agentDescription: "Provides information based on search results");
+    }
+
+    private static DeclarativeAgentDefinition DefineSearchAgent(IConfiguration configuration)
+    {
+        return new DeclarativeAgentDefinition(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                You are a helpful assistant that answers questions based on search results.
+                Use the information provided in the conversation history to answer questions.
+                If the information is already available in the conversation, use it directly.
+                Be concise and helpful in your responses.
+                """
+        };
+    }
+}

dotnet/samples/03-workflows/Declarative/Marketing/Marketing.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="$(MSBuildThisFileDirectory)..\..\..\..\..\declarative-agents\workflow-samples\Marketing.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/Marketing/Program.cs

@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Extensions.Configuration;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.Marketing;
+
+/// <summary>
+/// Demonstrate a declarative workflow with three agents (Analyst, Writer, Editor)
+/// sequentially engaging in a task.
+/// </summary>
+/// <remarks>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agents exist in Foundry.
+        await CreateAgentsAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.  This class demonstrates how to initialize a
+        // declarative workflow from a YAML file. Once the workflow is created, it
+        // can be executed just like any regular workflow.
+        WorkflowFactory workflowFactory = new("Marketing.yaml", foundryEndpoint);
+
+        // Execute the workflow:  The WorkflowRunner demonstrates how to execute
+        // a workflow, handle the workflow events, and providing external input.
+        // This also includes the ability to checkpoint workflow state and how to
+        // resume execution.
+        WorkflowRunner runner = new();
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentsAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "AnalystAgent",
+            agentDefinition: DefineAnalystAgent(configuration),
+            agentDescription: "Analyst agent for Marketing workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "WriterAgent",
+            agentDefinition: DefineWriterAgent(configuration),
+            agentDescription: "Writer agent for Marketing workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "EditorAgent",
+            agentDefinition: DefineEditorAgent(configuration),
+            agentDescription: "Editor agent for Marketing workflow");
+    }
+
+    private static DeclarativeAgentDefinition DefineAnalystAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                You are a marketing analyst. Given a product description, identify:
+                - Key features
+                - Target audience
+                - Unique selling points
+                """,
+            Tools =
+            {
+                //ProjectsAgentTool.CreateBingGroundingTool( // TODO: Use Bing Grounding when available
+                //    new BingGroundingSearchToolParameters(
+                //        [new BingGroundingSearchConfiguration(configuration[Application.Settings.FoundryGroundingTool])]))
+            }
+        };
+
+    private static DeclarativeAgentDefinition DefineWriterAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                You are a marketing copywriter. Given a block of text describing features, audience, and USPs,
+                compose a compelling marketing copy (like a newsletter section) that highlights these points.
+                Output should be short (around 150 words), output just the copy as a single text block.
+                """
+        };
+
+    private static DeclarativeAgentDefinition DefineEditorAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                You are an editor. Given the draft copy, correct grammar, improve clarity, ensure consistent tone,
+                give format and make it polished. Output the final improved copy as a single text block.
+                """
+        };
+}

dotnet/samples/03-workflows/Declarative/Marketing/Properties/launchSettings.json

@@ -0,0 +1,11 @@
+{
+  "profiles": {
+    "Default": {
+      "commandName": "Project"
+    },
+    "Water Bottle": {
+      "commandName": "Project",
+      "commandLineArgs": "\"An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours.\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/OpenAIChatAgent/Properties/launchSettings.json

@@ -0,0 +1,32 @@
+{
+  "profiles": {
+    "Marketing": {
+      "commandName": "Project",
+      "commandLineArgs": "\"Marketing.yaml\" \"An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours\""
+    },
+    "MathChat": {
+      "commandName": "Project",
+      "commandLineArgs": "\"MathChat.yaml\" \"How would you compute the value of PI?\""
+    },
+    "Question": {
+      "commandName": "Project",
+      "commandLineArgs": "\"Question.yaml\" \"Iko\""
+    },
+    "Research": {
+      "commandName": "Project",
+      "commandLineArgs": "\"DeepResearch.yaml\" \"What is the closest bus-stop that is next to ISHONI YAKINIKU in Seattle?\""
+    },
+    "ResponseObject": {
+      "commandName": "Project",
+      "commandLineArgs": "\"ResponseObject.yaml\" \"Can you help me plan a trip somewhere soon?\""
+    },
+    "UserInput": {
+      "commandName": "Project",
+      "commandLineArgs": "\"UserInput.yaml\" \"Iko\""
+    },
+    "ParseValue": {
+      "commandName": "Project",
+      "commandLineArgs": "\"Pradeep-ParseValue-Number.yaml\" \"Test this case:\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/OpenAIResponseAgent/Properties/launchSettings.json

@@ -0,0 +1,32 @@
+{
+  "profiles": {
+    "Marketing": {
+      "commandName": "Project",
+      "commandLineArgs": "\"Marketing.yaml\" \"An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours\""
+    },
+    "MathChat": {
+      "commandName": "Project",
+      "commandLineArgs": "\"MathChat.yaml\" \"How would you compute the value of PI?\""
+    },
+    "Question": {
+      "commandName": "Project",
+      "commandLineArgs": "\"Question.yaml\" \"Iko\""
+    },
+    "Research": {
+      "commandName": "Project",
+      "commandLineArgs": "\"DeepResearch.yaml\" \"What is the closest bus-stop that is next to ISHONI YAKINIKU in Seattle?\""
+    },
+    "ResponseObject": {
+      "commandName": "Project",
+      "commandLineArgs": "\"ResponseObject.yaml\" \"Can you help me plan a trip somewhere soon?\""
+    },
+    "UserInput": {
+      "commandName": "Project",
+      "commandLineArgs": "\"UserInput.yaml\" \"Iko\""
+    },
+    "ParseValue": {
+      "commandName": "Project",
+      "commandLineArgs": "\"Pradeep-ParseValue-Number.yaml\" \"Test this case:\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/README.md

@@ -0,0 +1,99 @@
+# Summary
+
+These samples showcases the ability to parse a declarative Foundry Workflow file (YAML) 
+to build a `Workflow` that may be executed using the same pattern as any code-based workflow.
+
+## Configuration
+
+These samples must be configured to create and use agents your 
+[Microsoft Foundry Project](https://learn.microsoft.com/azure/ai-foundry).
+
+### Settings
+
+We suggest using .NET [Secret Manager](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) 
+to avoid the risk of leaking secrets into the repository, branches and pull requests. 
+You can also use environment variables if you prefer.
+
+The configuraton required by the samples is:
+
+|Setting Name| Description|
+|:--|:--|
+|FOUNDRY_PROJECT_ENDPOINT| The endpoint URL of your Microsoft Foundry Project.|
+|FOUNDRY_MODEL| The name of the model deployment to use
+|AZURE_AI_BING_CONNECTION_ID| The name of the Bing Grounding connection configured in your Microsoft Foundry Project.|
+
+To set your secrets with .NET Secret Manager:
+
+1. From the root of the repository, navigate the console to the project folder:
+
+    ```
+    cd dotnet/samples/03-workflows/Declarative/ExecuteWorkflow
+    ```
+
+2. Examine existing secret definitions:
+
+    ```
+    dotnet user-secrets list
+    ```
+
+3. If needed, perform first time initialization:
+
+    ```
+    dotnet user-secrets init
+    ```
+
+4. Define setting that identifies your Microsoft Foundry Project (endpoint):
+
+    ```
+    dotnet user-secrets set "FOUNDRY_PROJECT_ENDPOINT" "https://..."
+    ```
+
+5. Define setting that identifies your Microsoft Foundry Model Deployment (endpoint):
+
+    ```
+    dotnet user-secrets set "FOUNDRY_MODEL" "gpt-5"
+    ```
+
+6. Define setting that identifies your Bing Grounding connection:
+
+    ```
+    dotnet user-secrets set "AZURE_AI_BING_CONNECTION_ID" "mybinggrounding"
+    ```
+
+You may alternatively set your secrets as an environment variable (PowerShell):
+
+```pwsh
+$env:FOUNDRY_PROJECT_ENDPOINT="https://..."
+$env:FOUNDRY_MODEL="gpt-5"
+$env:AZURE_AI_BING_CONNECTION_ID="mybinggrounding"
+```
+
+### Authorization
+
+Use [_Azure CLI_](https://learn.microsoft.com/cli/azure/authenticate-azure-cli) to authorize access to your Microsoft Foundry Project:
+
+```
+az login
+az account get-access-token
+```
+
+## Execution
+
+The samples may be executed within _Visual Studio_ or _VS Code_.
+
+To run the sampes from the command line:
+
+1. From the root of the repository, navigate the console to the project folder:
+
+    ```sh
+    cd dotnet/samples/03-workflows/Declarative/Marketing
+    dotnet run Marketing
+    ```
+
+2. Run the demo and optionally provided input:
+
+    ```sh
+    dotnet run "An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours."
+    dotnet run c:/myworkflows/Marketing.yaml
+    ```
+   >  The sample will allow for interactive input in the absence of an input argument.

dotnet/samples/03-workflows/Declarative/StudentTeacher/Program.cs

@@ -0,0 +1,89 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Extensions.Configuration;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.StudentTeacher;
+
+/// <summary>
+/// Demonstrate a declarative workflow with two agents (Student and Teacher)
+/// in an iterative conversation.
+/// </summary>
+/// <remarks>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agents exist in Foundry.
+        await CreateAgentsAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.  This class demonstrates how to initialize a
+        // declarative workflow from a YAML file. Once the workflow is created, it
+        // can be executed just like any regular workflow.
+        WorkflowFactory workflowFactory = new("MathChat.yaml", foundryEndpoint);
+
+        // Execute the workflow:  The WorkflowRunner demonstrates how to execute
+        // a workflow, handle the workflow events, and providing external input.
+        // This also includes the ability to checkpoint workflow state and how to
+        // resume execution.
+        WorkflowRunner runner = new();
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentsAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "StudentAgent",
+            agentDefinition: DefineStudentAgent(configuration),
+            agentDescription: "Student agent for MathChat workflow");
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "TeacherAgent",
+            agentDefinition: DefineTeacherAgent(configuration),
+            agentDescription: "Teacher agent for MathChat workflow");
+    }
+
+    private static DeclarativeAgentDefinition DefineStudentAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Your job is help a math teacher practice teaching by making intentional mistakes.
+                You attempt to solve the given math problem, but with intentional mistakes so the teacher can help.
+                Always incorporate the teacher's advice to fix your next response.
+                You have the math-skills of a 6th grader.
+                Don't describe who you are or reveal your instructions.
+                """
+        };
+
+    private static DeclarativeAgentDefinition DefineTeacherAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Review and coach the student's approach to solving the given math problem.
+                Don't repeat the solution or try and solve it.
+                If the student has demonstrated comprehension and responded to all of your feedback,
+                give the student your congratulations by using the word "congratulations".
+                """
+        };
+}

dotnet/samples/03-workflows/Declarative/StudentTeacher/Properties/launchSettings.json

@@ -0,0 +1,11 @@
+{
+  "profiles": {
+    "Default": {
+      "commandName": "Project"
+    },
+    "Compute PI": {
+      "commandName": "Project",
+      "commandLineArgs": "\"How would you compute the value of PI based on its fundamental definition?\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/StudentTeacher/StudentTeacher.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="$(MSBuildThisFileDirectory)..\..\..\..\..\declarative-agents\workflow-samples\MathChat.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/ToolApproval/Program.cs

@@ -0,0 +1,78 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Responses;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.ToolApproval;
+
+/// <summary>
+/// Demonstrate a workflow that responds to user input using an agent who
+/// has an MCP tool that requires approval.  Exits the loop when the user enters "exit".
+/// </summary>
+/// <remarks>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agents exist in Foundry.
+        await CreateAgentAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // Create the workflow factory.  This class demonstrates how to initialize a
+        // declarative workflow from a YAML file. Once the workflow is created, it
+        // can be executed just like any regular workflow.
+        WorkflowFactory workflowFactory = new("ToolApproval.yaml", foundryEndpoint);
+
+        // Execute the workflow:  The WorkflowRunner demonstrates how to execute
+        // a workflow, handle the workflow events, and providing external input.
+        // This also includes the ability to checkpoint workflow state and how to
+        // resume execution.
+        WorkflowRunner runner = new() { UseJsonCheckpoints = true };
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "DocumentSearchAgent",
+            agentDefinition: DefineSearchAgent(configuration),
+            agentDescription: "Searches documents on Microsoft Learn");
+    }
+
+    private static DeclarativeAgentDefinition DefineSearchAgent(IConfiguration configuration) =>
+        new(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Answer the users questions by searching the Microsoft Learn documentation.
+                For questions or input that do not require searching the documentation, inform the
+                user that you can only answer questions related to Microsoft Learn documentation.
+                """,
+            Tools =
+                {
+                    ResponseTool.CreateMcpTool(
+                        serverLabel: "microsoft_docs",
+                        serverUri: new Uri("https://learn.microsoft.com/api/mcp"),
+                        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval))
+                }
+        };
+}

dotnet/samples/03-workflows/Declarative/ToolApproval/Properties/launchSettings.json

@@ -0,0 +1,11 @@
+{
+  "profiles": {
+    "Default": {
+      "commandName": "Project"
+    },
+    "Graph API": {
+      "commandName": "Project",
+      "commandLineArgs": "\"What is Microsoft Graph API used for?\""
+    }
+  }
+}

dotnet/samples/03-workflows/Declarative/ToolApproval/ToolApproval.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="ToolApproval.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/ToolApproval/ToolApproval.yaml

@@ -0,0 +1,38 @@
+#
+# This workflow demonstrates an agent that requires tool approval
+# in a loop responding to user input.
+#
+# Example input: 
+# What is Microsoft Graph API used for?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_demo
+  actions:
+
+    - kind: InvokeAzureAgent
+      id: invoke_search
+      conversationId: =System.ConversationId
+      agent:
+        name: DocumentSearchAgent
+
+    - kind: RequestExternalInput
+      id: request_requirements
+
+    - kind: ConditionGroup
+      id: check_completion
+      conditions:
+
+        - condition: =Upper(System.LastMessage.Text) = "EXIT"
+          id: check_done
+          actions:
+
+            - kind: EndWorkflow
+              id: all_done
+
+      elseActions:
+        - kind: GotoAction
+          id: goto_search
+          actionId: invoke_search

dotnet/samples/03-workflows/Evaluation/Evaluation_WorkflowEval/Evaluation_WorkflowEval.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Evaluation/Evaluation_WorkflowEval/Program.cs

@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates evaluating a multi-agent workflow with per-agent breakdown.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-4o-mini";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+// Create two agents: a planner and an executor.
+AIAgent planner = aiProjectClient.AsAIAgent(
+    model: deploymentName,
+    instructions: "You plan trips. Output a concise bullet-point plan.",
+    name: "planner");
+
+AIAgent executor = aiProjectClient.AsAIAgent(
+    model: deploymentName,
+    instructions: "You execute travel plans. Confirm the bookings listed in the plan.",
+    name: "executor");
+
+// Build a simple planner -> executor workflow.
+Workflow workflow = new WorkflowBuilder(planner)
+    .AddEdge(planner, executor)
+    .Build();
+
+// Run the workflow to completion (RunAsync returns Run which supports EvaluateAsync).
+await using Run run = await InProcessExecution.RunAsync(
+    workflow,
+    new ChatMessage(ChatRole.User, "Plan a weekend trip to Paris"));
+
+// Print the events from the run.
+foreach (WorkflowEvent evt in run.OutgoingEvents)
+{
+    if (evt is AgentResponseEvent response)
+    {
+        Console.WriteLine($"  {response.ExecutorId}: {response.Response.Text[..Math.Min(80, response.Response.Text.Length)]}...");
+    }
+}
+
+// Evaluate with per-agent breakdown.
+EvalCheck isNonempty = FunctionEvaluator.Create("is_nonempty", (string response) => response.Trim().Length > 5);
+EvalCheck hasKeywords = EvalChecks.KeywordCheck("plan", "trip");
+LocalEvaluator local = new(isNonempty, hasKeywords);
+
+AgentEvaluationResults results = await run.EvaluateAsync(local);
+
+Console.WriteLine();
+Console.WriteLine($"Overall: {results.Passed}/{results.Total} passed");
+
+if (results.SubResults is not null)
+{
+    foreach (var (agentName, sub) in results.SubResults)
+    {
+        Console.WriteLine($"  {agentName}: {sub.Passed}/{sub.Total} passed");
+        for (int i = 0; i < sub.Items.Count; i++)
+        {
+            foreach (var metric in sub.Items[i].Metrics)
+            {
+                string status = metric.Value.Interpretation?.Failed == true ? "FAIL" : "PASS";
+                Console.WriteLine($"    [{status}] {metric.Key}");
+            }
+        }
+    }
+}

dotnet/samples/03-workflows/Evaluation/Evaluation_WorkflowEval/README.md

@@ -0,0 +1,30 @@
+# Evaluation - Workflow Eval
+
+This sample demonstrates evaluating a multi-agent workflow with per-agent breakdown.
+
+## What this sample demonstrates
+
+- Building a two-agent workflow (planner → executor)
+- Running the workflow and collecting events
+- Using `run.EvaluateAsync()` to evaluate the completed run
+- Per-agent sub-results via `results.SubResults`
+- Combining `FunctionEvaluator.Create` with `EvalChecks.KeywordCheck`
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Azure authentication available to `DefaultAzureCredential` (for local development, run `az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
+$env:FOUNDRY_MODEL="gpt-4o-mini"
+```
+
+## Run the sample
+
+```powershell
+cd dotnet/samples/03-workflows/Evaluation
+dotnet run --project .\Evaluation_WorkflowEval
+```

dotnet/samples/03-workflows/Evaluation/Evaluation_WorkflowExpectedOutputs/Evaluation_WorkflowExpectedOutputs.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Evaluation/Evaluation_WorkflowExpectedOutputs/Program.cs

@@ -0,0 +1,76 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates evaluating a multi-agent workflow against a
+// golden answer using Foundry's reference-based Similarity evaluator.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+using FoundryEvals = Microsoft.Agents.AI.Foundry.FoundryEvals;
+
+string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-4o-mini";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+// Build a two-agent workflow: a researcher writes a draft answer, then an
+// editor polishes it into the final response that we compare to ground truth.
+// EmitAgentResponseEvents is enabled so the workflow surfaces an AgentResponseEvent
+// for each agent — this is what EvaluateAsync uses to find the overall final answer.
+var hostOptions = new AIAgentHostOptions { EmitAgentResponseEvents = true };
+
+AIAgent researcher = projectClient.AsAIAgent(
+    model: deploymentName,
+    instructions: "You research questions and produce a short factual draft answer.",
+    name: "researcher");
+
+AIAgent editor = projectClient.AsAIAgent(
+    model: deploymentName,
+    instructions: "You take a draft answer and produce the final concise response.",
+    name: "editor");
+
+ExecutorBinding researcherExecutor = researcher.BindAsExecutor(hostOptions);
+ExecutorBinding editorExecutor = editor.BindAsExecutor(hostOptions);
+
+Workflow workflow = new WorkflowBuilder(researcherExecutor)
+    .AddEdge(researcherExecutor, editorExecutor)
+    .Build();
+
+// Run the workflow against the user question.
+const string Query = "What is the capital of France?";
+const string GroundTruth = "Paris";
+
+await using Run run = await InProcessExecution.RunAsync(
+    workflow,
+    new ChatMessage(ChatRole.User, Query));
+
+// Evaluate the overall workflow output against a golden answer using the
+// reference-based Similarity evaluator. The 'expectedOutput' value is stamped
+// onto the overall EvalItem.ExpectedOutput and is surfaced to Foundry as
+// `ground_truth` in the underlying JSONL payload.
+//
+// Per-agent breakdown is disabled here: ground truth applies to the workflow's
+// final answer, not to each sub-agent's intermediate output. Without
+// includePerAgent: false, the evaluator would be invoked for per-agent items
+// (which have no ExpectedOutput) and Similarity would fail validation.
+FoundryEvals similarity = new(projectClient, deploymentName, FoundryEvals.Similarity);
+
+AgentEvaluationResults results = await run.EvaluateAsync(
+    similarity,
+    includePerAgent: false,
+    expectedOutput: GroundTruth);
+
+Console.WriteLine($"Query: {Query}");
+Console.WriteLine($"Expected: {GroundTruth}");
+Console.WriteLine($"Provider: {results.ProviderName}");
+Console.WriteLine($"Passed: {results.Passed}/{results.Total}");
+if (results.ReportUrl is not null)
+{
+    Console.WriteLine($"Report: {results.ReportUrl}");
+}

dotnet/samples/03-workflows/Evaluation/Evaluation_WorkflowExpectedOutputs/README.md

@@ -0,0 +1,37 @@
+# Evaluation - Workflow Expected Outputs
+
+This sample demonstrates evaluating a multi-agent workflow's final answer
+against a golden expected output using Foundry's reference-based **Similarity**
+evaluator.
+
+## What this sample demonstrates
+
+- Building a small researcher → editor workflow
+- Running the workflow and obtaining a `Run`
+- Calling `run.EvaluateAsync(evaluator, expectedOutput: ...)` to attach a
+  ground-truth answer to the overall workflow item
+- Using `FoundryEvals.Similarity`, which requires a `ground_truth` value
+  per item
+
+The `expectedOutput` value is stamped onto the overall `EvalItem.ExpectedOutput`
+and is surfaced to Foundry as `ground_truth` in the JSONL payload sent to the
+Evals API.
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Azure authentication available to `DefaultAzureCredential` (for local development, run `az login`)
+
+Set the following environment variables:
+
+```powershell
+$env:FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
+$env:FOUNDRY_MODEL="gpt-4o-mini"
+```
+
+## Run the sample
+
+```powershell
+cd dotnet/samples/03-workflows/Evaluation
+dotnet run --project .\Evaluation_WorkflowExpectedOutputs
+```

dotnet/samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic/Program.cs

@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowHumanInTheLoopBasicSample;
+
+/// <summary>
+/// This sample introduces the concept of RequestPort and ExternalRequest to enable
+/// human-in-the-loop interaction scenarios.
+/// A request port can be used as if it were an executor in the workflow graph. Upon receiving
+/// a message, the request port generates an RequestInfoEvent that gets emitted to the external world.
+/// The external world can then respond to the request by sending an ExternalResponse back to
+/// the workflow.
+/// The sample implements a simple number guessing game where the external user tries to guess
+/// a pre-defined target number. The workflow consists of a single JudgeExecutor that judges
+/// the user's guesses and provides feedback.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Create the workflow
+        var workflow = WorkflowFactory.BuildWorkflow();
+
+        // Execute the workflow
+        await using StreamingRun handle = await InProcessExecution.RunStreamingAsync(workflow, NumberSignal.Init);
+        await foreach (WorkflowEvent evt in handle.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case RequestInfoEvent requestInputEvt:
+                    // Handle `RequestInfoEvent` from the workflow
+                    ExternalResponse response = HandleExternalRequest(requestInputEvt.Request);
+                    await handle.SendResponseAsync(response);
+                    break;
+
+                case WorkflowOutputEvent outputEvt:
+                    // The workflow has yielded output
+                    Console.WriteLine($"Workflow completed with result: {outputEvt.Data}");
+                    return;
+
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    return;
+
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    return;
+            }
+        }
+    }
+
+    private static ExternalResponse HandleExternalRequest(ExternalRequest request)
+    {
+        if (request.TryGetDataAs<NumberSignal>(out var signal))
+        {
+            switch (signal)
+            {
+                case NumberSignal.Init:
+                    int initialGuess = ReadIntegerFromConsole("Please provide your initial guess: ");
+                    return request.CreateResponse(initialGuess);
+                case NumberSignal.Above:
+                    int lowerGuess = ReadIntegerFromConsole("You previously guessed too large. Please provide a new guess: ");
+                    return request.CreateResponse(lowerGuess);
+                case NumberSignal.Below:
+                    int higherGuess = ReadIntegerFromConsole("You previously guessed too small. Please provide a new guess: ");
+                    return request.CreateResponse(higherGuess);
+            }
+        }
+
+        throw new NotSupportedException($"Request {request.PortInfo.RequestType} is not supported");
+    }
+
+    private static int ReadIntegerFromConsole(string prompt)
+    {
+        while (true)
+        {
+            Console.Write(prompt);
+            string? input = Console.ReadLine();
+            if (int.TryParse(input, out int value))
+            {
+                return value;
+            }
+            Console.WriteLine("Invalid input. Please enter a valid integer.");
+        }
+    }
+}

dotnet/samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic/WorkflowFactory.cs

@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowHumanInTheLoopBasicSample;
+
+internal static class WorkflowFactory
+{
+    /// <summary>
+    /// Get a workflow that plays a number guessing game with human-in-the-loop interaction.
+    /// An input port allows the external world to provide inputs to the workflow upon requests.
+    /// </summary>
+    internal static Workflow BuildWorkflow()
+    {
+        // Create the executors
+        RequestPort numberRequestPort = RequestPort.Create<NumberSignal, int>("GuessNumber");
+        JudgeExecutor judgeExecutor = new(42);
+
+        // Build the workflow by connecting executors in a loop
+        return new WorkflowBuilder(numberRequestPort)
+            .AddEdge(numberRequestPort, judgeExecutor)
+            .AddEdge(judgeExecutor, numberRequestPort)
+            .WithOutputFrom(judgeExecutor)
+            .Build();
+    }
+}
+
+/// <summary>
+/// Signals used for communication between guesses and the JudgeExecutor.
+/// </summary>
+internal enum NumberSignal
+{
+    Init,
+    Above,
+    Below,
+}
+
+/// <summary>
+/// Executor that judges the guess and provides feedback.
+/// </summary>
+[SendsMessage(typeof(NumberSignal))]
+[YieldsOutput(typeof(string))]
+internal sealed class JudgeExecutor() : Executor<int>("Judge")
+{
+    private readonly int _targetNumber;
+    private int _tries;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JudgeExecutor"/> class.
+    /// </summary>
+    /// <param name="targetNumber">The number to be guessed.</param>
+    public JudgeExecutor(int targetNumber) : this()
+    {
+        this._targetNumber = targetNumber;
+    }
+
+    public override async ValueTask HandleAsync(int message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._tries++;
+        if (message == this._targetNumber)
+        {
+            await context.YieldOutputAsync($"{this._targetNumber} found in {this._tries} tries!", cancellationToken);
+        }
+        else if (message < this._targetNumber)
+        {
+            await context.SendMessageAsync(NumberSignal.Below, cancellationToken: cancellationToken);
+        }
+        else
+        {
+            await context.SendMessageAsync(NumberSignal.Above, cancellationToken: cancellationToken);
+        }
+    }
+}

dotnet/samples/03-workflows/Loop/Loop.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Loop/Program.cs

@@ -0,0 +1,153 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowLoopSample;
+
+/// <summary>
+/// This sample demonstrates a simple number guessing game using a workflow with looping behavior.
+///
+/// The workflow consists of two executors that are connected in a feedback loop:
+/// 1. GuessNumberExecutor: Makes a guess based on the current known bounds.
+/// 2. JudgeExecutor: Evaluates the guess and provides feedback.
+/// The workflow continues until the correct number is guessed.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Create the executors
+        GuessNumberExecutor guessNumberExecutor = new("GuessNumber", 1, 100);
+        JudgeExecutor judgeExecutor = new("Judge", 42);
+
+        // Build the workflow by connecting executors in a loop
+        var workflow = new WorkflowBuilder(guessNumberExecutor)
+            .AddEdge(guessNumberExecutor, judgeExecutor)
+            .AddEdge(judgeExecutor, guessNumberExecutor)
+            .WithOutputFrom(judgeExecutor)
+            .Build();
+
+        // Execute the workflow
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, NumberSignal.Init);
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            if (evt is WorkflowOutputEvent outputEvent)
+            {
+                Console.WriteLine($"Result: {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>
+/// Signals used for communication between GuessNumberExecutor and JudgeExecutor.
+/// </summary>
+internal enum NumberSignal
+{
+    Init,
+    Above,
+    Below,
+}
+
+/// <summary>
+/// Executor that makes a guess based on the current bounds.
+/// </summary>
+[SendsMessage(typeof(int))]
+internal sealed class GuessNumberExecutor : Executor<NumberSignal>
+{
+    /// <summary>
+    /// The lower bound of the guessing range.
+    /// </summary>
+    public int LowerBound { get; private set; }
+
+    /// <summary>
+    /// The upper bound of the guessing range.
+    /// </summary>
+    public int UpperBound { get; private set; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GuessNumberExecutor"/> class.
+    /// </summary>
+    /// <param name="id">A unique identifier for the executor.</param>
+    /// <param name="lowerBound">The initial lower bound of the guessing range.</param>
+    /// <param name="upperBound">The initial upper bound of the guessing range.</param>
+    public GuessNumberExecutor(string id, int lowerBound, int upperBound) : base(id)
+    {
+        this.LowerBound = lowerBound;
+        this.UpperBound = upperBound;
+    }
+
+    private int NextGuess => (this.LowerBound + this.UpperBound) / 2;
+
+    public override async ValueTask HandleAsync(NumberSignal message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        switch (message)
+        {
+            case NumberSignal.Init:
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+            case NumberSignal.Above:
+                this.UpperBound = this.NextGuess - 1;
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+            case NumberSignal.Below:
+                this.LowerBound = this.NextGuess + 1;
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+        }
+    }
+}
+
+/// <summary>
+/// Executor that judges the guess and provides feedback.
+/// </summary>
+[SendsMessage(typeof(NumberSignal))]
+[YieldsOutput(typeof(string))]
+internal sealed class JudgeExecutor : Executor<int>
+{
+    private readonly int _targetNumber;
+    private int _tries;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JudgeExecutor"/> class.
+    /// </summary>
+    /// <param name="id">A unique identifier for the executor.</param>
+    /// <param name="targetNumber">The number to be guessed.</param>
+    public JudgeExecutor(string id, int targetNumber) : base(id)
+    {
+        this._targetNumber = targetNumber;
+    }
+
+    public override async ValueTask HandleAsync(int message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._tries++;
+        if (message == this._targetNumber)
+        {
+            await context.YieldOutputAsync($"{this._targetNumber} found in {this._tries} tries!", cancellationToken);
+        }
+        else if (message < this._targetNumber)
+        {
+            await context.SendMessageAsync(NumberSignal.Below, cancellationToken: cancellationToken);
+        }
+        else
+        {
+            await context.SendMessageAsync(NumberSignal.Above, cancellationToken: cancellationToken);
+        }
+    }
+}

dotnet/samples/03-workflows/Observability/ApplicationInsights/ApplicationInsights.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Monitor.OpenTelemetry.Exporter" />
+    <PackageReference Include="OpenTelemetry" />
+  </ItemGroup>
+
+  <ItemGroup Condition="!$([MSBuild]::IsTargetFrameworkCompatible($(TargetFramework), 'net10.0'))">
+    <PackageReference Include="System.Diagnostics.DiagnosticSource" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>