chore: import upstream snapshot with attribution

dotnet/samples/03-workflows/Orchestration/Handoff/AgentRegistry.cs

@@ -0,0 +1,72 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+/// <summary>
+/// The registry of agents used in the workflow.
+/// </summary>
+/// <param name="chatClient">The <see cref="IChatClient"/> to use as the agent backend.</param>
+internal sealed class AgentRegistry(IChatClient chatClient)
+{
+    internal const string IntakeAgentName = "Assistant";
+    public AIAgent IntakeAgent { get; } = chatClient.AsAIAgent(
+        instructions:
+            """
+                You receive a user request and are responsible for routing to the correct initial expert agent.
+                """,
+        IntakeAgentName
+        );
+
+    internal const string LiquidityAnalysisAgentName = "Liquidity Analysis";
+    public AIAgent LiquidityAnalysisAgent { get; } = chatClient.AsAIAgent(
+        instructions:
+            """
+                You are responsible for Liquidity Analysis.
+                """,
+        LiquidityAnalysisAgentName
+        );
+
+    internal const string TaxAnalysisAgentName = "Tax Analysis";
+    public AIAgent TaxAnalysisAgent { get; } = chatClient.AsAIAgent(
+        instructions:
+            """
+                You are responsible for Tax Analysis. 
+                """,
+        TaxAnalysisAgentName
+        );
+
+    internal const string ForeignExchangeAgentName = "Foreign Exchange Analysis";
+    public AIAgent ForeignExchangeAgent { get; } = chatClient.AsAIAgent(
+        instructions:
+            """
+                You are responsible for Foreign Exchange Analysis. 
+                """,
+        ForeignExchangeAgentName
+        );
+
+    internal const string EquityAgentName = "Equity Analysis";
+    public AIAgent EquityAgent { get; } = chatClient.AsAIAgent(
+        instructions:
+            """
+                You are responsible for Equity Analysis. 
+                """,
+        EquityAgentName
+        );
+
+    public IEnumerable<AIAgent> Experts => [this.LiquidityAnalysisAgent, this.TaxAnalysisAgent, this.ForeignExchangeAgent, this.EquityAgent];
+
+    public HashSet<AIAgent> All
+    {
+        get
+        {
+            if (field == null)
+            {
+                field = [this.IntakeAgent, .. this.Experts];
+            }
+
+            return field;
+        }
+    }
+}

dotnet/samples/03-workflows/Orchestration/Handoff/Handoff.csproj

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+
+    <NoWarn>MAAIW001</NoWarn>
+  </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/Orchestration/Handoff/Program.cs

@@ -0,0 +1,125 @@
+// 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;
+
+string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+            ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+string 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.
+AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+IChatClient chatClient = projectClient.ProjectOpenAIClient
+                                      .GetChatClient(deploymentName)
+                                      .AsIChatClient();
+
+Workflow workflow = CreateWorkflow(chatClient);
+
+await RunWorkflowAsync(workflow).ConfigureAwait(false);
+
+static Workflow CreateWorkflow(IChatClient chatClient)
+{
+    AgentRegistry agents = new(chatClient);
+
+    HandoffWorkflowBuilder handoffBuilder = AgentWorkflowBuilder.CreateHandoffBuilderWith(agents.IntakeAgent);
+
+    // Add a handoff to each of the experts from every agent in the registry (experts + Intake)
+    foreach (AIAgent expert in agents.Experts)
+    {
+        handoffBuilder.WithHandoffs(agents.All.Except([expert]), expert);
+    }
+
+    // Let agents request more user information and return to the asking agent (rather than going back to the intake agent)
+    handoffBuilder.EnableReturnToPrevious();
+
+    return handoffBuilder.Build();
+}
+
+static async Task RunWorkflowAsync(Workflow workflow)
+{
+    using CancellationTokenSource cts = CreateConsoleCancelKeySource();
+    await using StreamingRun run = await InProcessExecution.OpenStreamingAsync(workflow, cancellationToken: cts.Token)
+                                                           .ConfigureAwait(false);
+
+    bool hadError = false;
+    do
+    {
+        Console.Write("> ");
+        string userInput = Console.ReadLine() ?? string.Empty;
+
+        if (userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
+        {
+            break;
+        }
+
+        await run.TrySendMessageAsync(userInput);
+        string? speakingAgent = null;
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync(cts.Token))
+        {
+            switch (evt)
+            {
+                case AgentResponseUpdateEvent update:
+                {
+                    if (speakingAgent == null || speakingAgent != update.Update.AuthorName)
+                    {
+                        speakingAgent = update.Update.AuthorName;
+                        Console.Write($"\n{speakingAgent}: ");
+                    }
+
+                    Console.Write(update.Update.Text);
+                    break;
+                }
+
+                case WorkflowErrorEvent workflowError:
+                {
+                    Console.ForegroundColor = ConsoleColor.Red;
+
+                    if (workflowError.Exception != null)
+                    {
+                        Console.WriteLine($"\nWorkflow error: {workflowError.Exception}");
+                    }
+                    else
+                    {
+                        Console.WriteLine("\nUnknown workflow error occurred.");
+                    }
+
+                    Console.ResetColor();
+
+                    hadError = true;
+                    break;
+                }
+
+                case WorkflowWarningEvent workflowWarning when workflowWarning.Data is string message:
+                {
+                    Console.ForegroundColor = ConsoleColor.Yellow;
+                    Console.WriteLine(message);
+                    Console.ResetColor();
+                    break;
+                }
+            }
+        }
+    } while (!hadError);
+}
+
+static CancellationTokenSource CreateConsoleCancelKeySource()
+{
+    CancellationTokenSource cts = new();
+
+    // Normally, support a way to detach events, but in this case this is a termination signal, so cleanup will happen
+    // as part of application shutdown.
+    Console.CancelKeyPress += (s, args) =>
+    {
+        cts.Cancel();
+
+        // We handle cleanup + termination ourselves
+        args.Cancel = true;
+    };
+
+    return cts;
+}

dotnet/samples/03-workflows/Orchestration/Magentic/Magentic.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAIW001;OPENAI001</NoWarn>
+  </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/Orchestration/Magentic/Program.cs

@@ -0,0 +1,193 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample ports the Python Magentic orchestration sample to .NET.
+// A Magentic workflow coordinates a researcher and a coder, streams orchestration
+// events as the plan evolves, and prints the final conversation transcript.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Agents.AI.Workflows.Specialized.Magentic;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowMagenticOrchestrationSample;
+
+/// <summary>
+/// Demonstrates Magentic orchestration with a researcher, a coder, and an LLM manager.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - An Azure AI Foundry project endpoint and model deployment must be configured.
+/// - Run <c>az login</c> before executing the sample.
+/// </remarks>
+public static class Program
+{
+    private const string TaskPrompt =
+        "I am preparing a report on the energy efficiency of different machine learning model architectures. " +
+        "Compare the estimated training and inference energy consumption of ResNet-50, BERT-base, and GPT-2 " +
+        "on standard datasets (e.g., ImageNet for ResNet, GLUE for BERT, WebText for GPT-2). " +
+        "Then, estimate the CO2 emissions associated with each, assuming training on an Azure Standard_NC6s_v3 " +
+        "VM for 24 hours. Provide tables for clarity, and recommend the most energy-efficient model " +
+        "per task type (image classification, text classification, and text generation).";
+
+    private static async Task Main()
+    {
+        string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+            ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+        string 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.
+        AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
+
+        AIAgent researcherAgent = projectClient.AsAIAgent(
+            deploymentName,
+            name: "ResearcherAgent",
+            description: "Specialist in research and information gathering.",
+            instructions: "You are a researcher. Find relevant information without doing additional computation or quantitative analysis.");
+
+        AIAgent coderAgent = projectClient.AsAIAgent(
+            deploymentName,
+            name: "CoderAgent",
+            description: "A helpful assistant that writes and executes code to analyze data.",
+            instructions: "You solve quantitative questions by writing and running code. Show the analysis and the computation process clearly.",
+            tools: [new HostedCodeInterpreterTool()]);
+
+        AIAgent managerAgent = projectClient.AsAIAgent(
+            deploymentName,
+            name: "MagenticManager",
+            description: "Orchestrator that coordinates the research and coding workflow.",
+            instructions: "You coordinate the team to complete complex tasks efficiently.");
+
+        Workflow workflow = new MagenticWorkflowBuilder(managerAgent)
+            .AddParticipants([researcherAgent, coderAgent])
+            .WithName("Magentic Orchestration Workflow")
+            .WithDescription("Coordinates a researcher and coder to solve a complex analytical task.")
+            .RequirePlanSignoff(false)
+            .WithMaxRounds(10)
+            .WithMaxStalls(3)
+            .WithMaxResets(2)
+            .Build();
+
+        Console.WriteLine("Building Magentic workflow...");
+        Console.WriteLine();
+        Console.WriteLine($"Task: {TaskPrompt}");
+        Console.WriteLine();
+        Console.WriteLine("Starting workflow execution...");
+
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(
+            workflow,
+            new List<ChatMessage> { new(ChatRole.User, TaskPrompt) });
+
+        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+
+        string? lastResponseId = null;
+        WorkflowOutputEvent? finalOutput = null;
+
+        await foreach (WorkflowEvent workflowEvent in run.WatchStreamAsync())
+        {
+            switch (workflowEvent)
+            {
+                case AgentResponseUpdateEvent updateEvent:
+                    WriteStreamingUpdate(updateEvent, ref lastResponseId);
+                    break;
+
+                case MagenticPlanCreatedEvent planCreated:
+                    WriteMagenticMessage("Initial Plan", planCreated.FullTaskLedger.Text);
+                    PauseIfInteractive();
+                    break;
+
+                case MagenticReplannedEvent replanned:
+                    WriteMagenticMessage("Replanned", replanned.FullTaskLedger.Text);
+                    PauseIfInteractive();
+                    break;
+
+                case MagenticProgressLedgerUpdatedEvent progressUpdated:
+                    WriteMagenticMessage("Progress Ledger", FormatProgressLedger(progressUpdated.ProgressLedger));
+                    PauseIfInteractive();
+                    break;
+
+                case WorkflowOutputEvent outputEvent when outputEvent.Is<List<ChatMessage>>():
+                    finalOutput = outputEvent;
+                    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 is null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+
+        if (finalOutput?.As<List<ChatMessage>>() is { } transcript)
+        {
+            Console.WriteLine();
+            Console.WriteLine(new string('=', 80));
+            Console.WriteLine();
+            Console.WriteLine("Final Conversation Transcript:");
+            Console.WriteLine();
+
+            foreach (ChatMessage message in transcript)
+            {
+                Console.WriteLine($"{message.AuthorName ?? message.Role.ToString()}: {message.Text}");
+                Console.WriteLine();
+            }
+        }
+    }
+
+    private static void WriteStreamingUpdate(AgentResponseUpdateEvent updateEvent, ref string? lastResponseId)
+    {
+        string responseId = updateEvent.Update.ResponseId ?? updateEvent.Update.MessageId ?? updateEvent.ExecutorId;
+        if (!string.Equals(responseId, lastResponseId, StringComparison.Ordinal))
+        {
+            if (lastResponseId is not null)
+            {
+                Console.WriteLine();
+                Console.WriteLine();
+            }
+
+            Console.Write($"- {updateEvent.ExecutorId}: ");
+            lastResponseId = responseId;
+        }
+
+        if (!string.IsNullOrEmpty(updateEvent.Update.Text))
+        {
+            Console.Write(updateEvent.Update.Text);
+        }
+    }
+
+    private static void WriteMagenticMessage(string title, string? content)
+    {
+        Console.WriteLine();
+        Console.WriteLine($"[Magentic {title}]");
+        Console.WriteLine(content);
+    }
+
+    private static string FormatProgressLedger(MagenticProgressLedger ledger) =>
+        string.Join(Environment.NewLine,
+            $"Request satisfied: {ledger.IsRequestSatisfied}",
+            $"In loop: {ledger.IsInLoop}",
+            $"Making progress: {ledger.IsProgressBeingMade}",
+            $"Next speaker: {ledger.NextSpeaker}",
+            $"Instruction: {ledger.InstructionOrQuestion}");
+
+    private static void PauseIfInteractive()
+    {
+        if (Console.IsInputRedirected || Console.IsOutputRedirected)
+        {
+            return;
+        }
+
+        Console.Write("Press Enter to continue...");
+        Console.ReadLine();
+        Console.WriteLine();
+    }
+}

dotnet/samples/03-workflows/Orchestration/Magentic/README.md

@@ -0,0 +1,40 @@
+# Magentic Orchestration Sample
+
+This sample showcases the Magentic Orchestration Pattern in .NET, setting up a team with three roles:
+
+- **ResearcherAgent** gathers factual background information.
+- **CoderAgent** uses `HostedCodeInterpreterTool` for quantitative analysis.
+- **MagenticManager** plans the work, tracks progress, and decides who should act next.
+
+## What This Sample Demonstrates
+
+- Building a Magentic workflow with `MagenticWorkflowBuilder`
+- Combining standard responses-based agents with a code interpreter-enabled participant
+- Streaming orchestration events such as the initial plan, replans, and progress-ledger updates
+- Printing the final multi-agent conversation transcript
+
+## Prerequisites
+
+- `FOUNDRY_PROJECT_ENDPOINT` set to your Azure AI Foundry project endpoint
+- `FOUNDRY_MODEL` set to your model deployment name (defaults to `gpt-5.4-mini`)
+- `az login` completed before running the sample
+
+## Running the Sample
+
+```bash
+dotnet run
+```
+
+## Expected Output
+
+The sample prints:
+
+1. The original task prompt
+2. Streamed updates from the participating agents
+3. Magentic plan and progress-ledger events as the workflow coordinates the team
+4. The final conversation transcript returned by the workflow
+
+## Related Samples
+
+- [Handoff Orchestration](../Handoff) - another multi-agent orchestration pattern in .NET workflows
+- [Python Magentic workflow sample](../../../../../python/samples/03-workflows/orchestrations/magentic.py) - the source scenario that this sample ports