Merge pull request #401 from microsoft/08-multi-agent-dotnet

feat: Chapter 08 Migrate .NET Multi-Agent Workflow Notebooks to Single File App Format

Author: koreyspace

08-multi-agent/code_samples/workflows-agent-framework/dotNET/01.dotnet-agent-framework-workflow-ghmodel-basic.cs

@@ -0,0 +1,100 @@
+#!/usr/bin/dotnet run
+#:package Microsoft.Extensions.AI@9.9.1
+#:package System.ClientModel@1.6.1.0
+#:package Azure.Identity@1.15.0
+#:package System.Linq.Async@6.0.3
+#:package OpenTelemetry.Api@1.0.0
+#:package Microsoft.Agents.AI.Workflows@1.0.0-preview.251001.3
+#:package Microsoft.Agents.AI.OpenAI@1.0.0-preview.251001.3
+#:package DotNetEnv@3.1.1
+
+using System;
+using System.ComponentModel;
+using System.ClientModel;
+using OpenAI;
+using Azure.Identity;
+using Microsoft.Extensions.AI;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using DotNetEnv;
+
+// Load environment variables from .env file
+Env.Load("../../../.env");
+
+// Configure GitHub Models endpoint and credentials
+var github_endpoint = Environment.GetEnvironmentVariable("GITHUB_ENDPOINT") ?? throw new InvalidOperationException("GITHUB_ENDPOINT is not set.");
+var github_model_id = Environment.GetEnvironmentVariable("GITHUB_MODEL_ID") ?? "gpt-4o-mini";
+var github_token = Environment.GetEnvironmentVariable("GITHUB_TOKEN") ?? throw new InvalidOperationException("GITHUB_TOKEN is not set.");
+
+// Configure OpenAI client options with GitHub Models endpoint
+var openAIOptions = new OpenAIClientOptions()
+{
+    Endpoint = new Uri(github_endpoint)
+};
+
+// Create OpenAI client with API key credential
+var openAIClient = new OpenAIClient(new ApiKeyCredential(github_token), openAIOptions);
+
+// Define Reviewer Agent (Concierge) configuration
+const string ReviewerAgentName = "Concierge";
+const string ReviewerAgentInstructions = @"
+    You are a hotel concierge who has opinions about providing the most local and authentic experiences for travelers.
+    The goal is to determine if the front desk travel agent has recommended the best non-touristy experience for a traveler.
+    If so, state that it is approved.
+    If not, provide insight on how to refine the recommendation without using a specific example. ";
+
+// Define Front Desk Agent configuration
+const string FrontDeskAgentName = "FrontDesk";
+const string FrontDeskAgentInstructions = @"""
+    You are a Front Desk Travel Agent with ten years of experience and are known for brevity as you deal with many customers.
+    The goal is to provide the best activities and locations for a traveler to visit.
+    Only provide a single recommendation per response.
+    You're laser focused on the goal at hand.
+    Don't waste time with chit chat.
+    Consider suggestions when refining an idea.
+    """;
+
+// Create AI agents with specialized instructions
+AIAgent reviewerAgent = openAIClient.GetChatClient(github_model_id).CreateAIAgent(
+    name: ReviewerAgentName, instructions: ReviewerAgentInstructions);
+AIAgent frontDeskAgent = openAIClient.GetChatClient(github_model_id).CreateAIAgent(
+    name: FrontDeskAgentName, instructions: FrontDeskAgentInstructions);
+
+// Build workflow with sequential agent execution
+var workflow = new WorkflowBuilder(frontDeskAgent)
+    .AddEdge(frontDeskAgent, reviewerAgent)
+    .Build();
+
+// Create user message for travel recommendation
+ChatMessage userMessage = new ChatMessage(ChatRole.User, [
+    new TextContent("I would like to go to Paris.")
+]);
+
+// Execute workflow with streaming
+StreamingRun run = await InProcessExecution.StreamAsync(workflow, userMessage);
+
+// Process workflow events and collect results
+await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+string id = "";
+string messageData = "";
+await foreach (WorkflowEvent evt in run.WatchStreamAsync().ConfigureAwait(false))
+{
+    if (evt is AgentRunUpdateEvent executorComplete)
+    {
+        if (id == "")
+        {
+            id = executorComplete.ExecutorId;
+        }
+        if (id == executorComplete.ExecutorId)
+        {
+            messageData += executorComplete.Data.ToString();
+        }
+        else
+        {
+            id = executorComplete.ExecutorId;
+        }
+    }
+}
+
+// Display final workflow results
+Console.WriteLine(messageData);

08-multi-agent/code_samples/workflows-agent-framework/dotNET/01.dotnet-agent-framework-workflow-ghmodel-basic.md

@@ -0,0 +1,162 @@
+# 🔄 Basic Agent Workflows with GitHub Models (.NET)
+
+## 📋 Workflow Orchestration Tutorial
+
+This notebook demonstrates how to build sophisticated **agent workflows** using the Microsoft Agent Framework for .NET and GitHub Models. You'll learn to create multi-step business processes where AI agents collaborate to accomplish complex tasks through structured orchestration patterns.
+
+## 🎯 Learning Objectives
+
+### 🏗️ **Workflow Architecture Fundamentals**
+- **Workflow Builder**: Design and orchestrate complex multi-step AI processes
+- **Agent Coordination**: Coordinate multiple specialized agents within workflows
+- **GitHub Models Integration**: Leverage GitHub's AI model inference service in workflows
+- **Visual Workflow Design**: Create and visualize workflow structures for better understanding
+
+### 🔄 **Process Orchestration Patterns**
+- **Sequential Processing**: Chain multiple agent tasks in logical order
+- **State Management**: Maintain context and data flow across workflow stages
+- **Error Handling**: Implement robust error recovery and workflow resilience
+- **Performance Optimization**: Design efficient workflows for enterprise-scale operations
+
+### 🏢 **Enterprise Workflow Applications**
+- **Business Process Automation**: Automate complex organizational workflows
+- **Content Production Pipeline**: Editorial workflows with review and approval stages
+- **Customer Service Automation**: Multi-step customer inquiry resolution
+- **Data Processing Workflows**: ETL workflows with AI-powered transformation
+
+## ⚙️ Prerequisites & Setup
+
+### 📦 **Required NuGet Packages**
+
+This workflow demonstration uses several key .NET packages:
+
+```xml
+<!-- Core AI Framework -->
+<PackageReference Include="Microsoft.Extensions.AI" Version="9.9.0" />
+
+<!-- Agent Framework (Local Development) -->
+<!-- Microsoft.Agents.AI.dll - Core agent abstractions -->
+<!-- Microsoft.Agents.AI.OpenAI.dll - OpenAI/GitHub Models integration -->
+
+<!-- Configuration and Environment -->
+<PackageReference Include="DotNetEnv" Version="3.1.1" />
+```
+
+### 🔑 **GitHub Models Configuration**
+
+**Environment Setup (.env file):**
+```env
+GITHUB_TOKEN=your_github_personal_access_token
+GITHUB_ENDPOINT=https://models.inference.ai.azure.com
+GITHUB_MODEL_ID=gpt-4o-mini
+```
+
+**GitHub Models Access:**
+1. Sign up for GitHub Models (currently in preview)
+2. Generate a personal access token with model access permissions
+3. Configure environment variables as shown above
+
+### 🏗️ **Workflow Architecture Overview**
+
+```mermaid
+graph TD
+    A[Workflow Builder] --> B[Agent Registry]
+    B --> C[Workflow Execution Engine]
+    C --> D[Agent 1: Content Generator]
+    C --> E[Agent 2: Content Reviewer] 
+    D --> F[Workflow Results]
+    E --> F
+    G[GitHub Models API] --> D
+    G --> E
+```
+
+**Key Components:**
+- **WorkflowBuilder**: Main orchestration engine for designing workflows
+- **AIAgent**: Individual specialized agents with specific capabilities
+- **GitHub Models Client**: AI model inference service integration
+- **Execution Context**: Manages state and data flow between workflow stages
+
+## 🎨 **Enterprise Workflow Design Patterns**
+
+### 📝 **Content Production Workflow**
+```
+User Request → Content Generation → Quality Review → Final Output
+```
+
+### 🔍 **Document Processing Pipeline**
+```
+Document Input → Analysis → Extraction → Validation → Structured Output
+```
+
+### 💼 **Business Intelligence Workflow**
+```
+Data Collection → Processing → Analysis → Report Generation → Distribution
+```
+
+### 🤝 **Customer Service Automation**
+```
+Customer Inquiry → Classification → Processing → Response Generation → Follow-up
+```
+
+## 🏢 **Enterprise Benefits**
+
+### 🎯 **Reliability & Scalability**
+- **Deterministic Execution**: Consistent, repeatable workflow outcomes
+- **Error Recovery**: Graceful handling of failures at any workflow stage
+- **Performance Monitoring**: Track execution metrics and optimization opportunities
+- **Resource Management**: Efficient allocation and utilization of AI model resources
+
+### 🔒 **Security & Compliance**
+- **Secure Authentication**: GitHub token-based authentication for API access
+- **Audit Trails**: Complete logging of workflow execution and decision points
+- **Access Control**: Granular permissions for workflow execution and monitoring
+- **Data Privacy**: Secure handling of sensitive information throughout workflows
+
+### 📊 **Observability & Management**
+- **Visual Workflow Design**: Clear representation of process flows and dependencies
+- **Execution Monitoring**: Real-time tracking of workflow progress and performance
+- **Error Reporting**: Detailed error analysis and debugging capabilities
+- **Performance Analytics**: Metrics for optimization and capacity planning
+
+Let's build your first enterprise-ready AI workflow! 🚀
+
+## 💻 Running the Code
+
+The complete implementation is available in `01.dotnet-agent-framework-workflow-ghmodel-basic.cs`. This file demonstrates:
+
+1. **Environment Configuration** - Loading GitHub Models credentials from `.env` file
+2. **OpenAI Client Setup** - Configuring the client to use GitHub Models endpoint
+3. **Agent Creation** - Defining specialized agents (Front Desk and Concierge)
+4. **Workflow Builder** - Creating a multi-agent workflow with sequential processing
+5. **Workflow Execution** - Running the workflow with streaming results
+
+### 🚀 Running the Example
+
+```bash
+# Make the script executable (Unix/Linux/macOS)
+chmod +x 01.dotnet-agent-framework-workflow-ghmodel-basic.cs
+
+# Run the workflow
+./01.dotnet-agent-framework-workflow-ghmodel-basic.cs
+```
+
+Or on Windows:
+```powershell
+dotnet run 01.dotnet-agent-framework-workflow-ghmodel-basic.cs
+```
+
+### 📝 Expected Output
+
+The workflow will:
+1. Accept your travel destination request ("I would like to go to Paris")
+2. The Front Desk agent provides an initial recommendation
+3. The Concierge agent reviews and refines the recommendation
+4. Final output displays the complete conversation stream
+
+### 🔧 Customization
+
+You can customize the workflow by:
+- Modifying agent instructions to change their behavior
+- Adding more agents to create complex multi-step workflows
+- Changing the user message to test different scenarios
+- Adjusting the workflow edges to create different execution patterns

08-multi-agent/code_samples/workflows-agent-framework/dotNET/02.dotnet-agent-framework-workflow-ghmodel-sequential.cs

@@ -0,0 +1,125 @@
+#!/usr/bin/dotnet run
+#:package Microsoft.Extensions.AI@9.9.1
+#:package System.ClientModel@1.6.1.0
+#:package Azure.Identity@1.15.0
+#:package System.Linq.Async@6.0.3
+#:package OpenTelemetry.Api@1.0.0
+#:package Microsoft.Agents.AI.Workflows@1.0.0-preview.251001.3
+#:package Microsoft.Agents.AI.OpenAI@1.0.0-preview.251001.3
+#:package DotNetEnv@3.1.1
+
+using System;
+using System.ComponentModel;
+using System.ClientModel;
+using System.IO;
+using OpenAI;
+using Azure.Identity;
+using Microsoft.Extensions.AI;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using DotNetEnv;
+
+// Load environment variables from .env file
+Env.Load("../../../.env");
+
+// Configure GitHub Models endpoint and credentials
+var github_endpoint = Environment.GetEnvironmentVariable("GITHUB_ENDPOINT") ?? throw new InvalidOperationException("GITHUB_ENDPOINT is not set.");
+var github_model_id = "gpt-4o";  // Using GPT-4o for vision capabilities
+var github_token = Environment.GetEnvironmentVariable("GITHUB_TOKEN") ?? throw new InvalidOperationException("GITHUB_TOKEN is not set.");
+
+// Path to furniture image for analysis
+var imgPath = "../imgs/home.png";
+
+// Configure OpenAI client options with GitHub Models endpoint
+var openAIOptions = new OpenAIClientOptions()
+{
+    Endpoint = new Uri(github_endpoint)
+};
+
+// Create OpenAI client with API key credential
+var openAIClient = new OpenAIClient(new ApiKeyCredential(github_token), openAIOptions);
+
+// Define Sales Agent (Stage 1) - Furniture Analysis
+const string SalesAgentName = "Sales-Agent";
+const string SalesAgentInstructions = "You are my furniture sales consultant, you can find different furniture elements from the pictures and give me a purchase suggestion";
+
+// Define Price Agent (Stage 2) - Pricing Specialist
+const string PriceAgentName = "Price-Agent";
+const string PriceAgentInstructions = @"You are a furniture pricing specialist and budget consultant. Your responsibilities include:
+        1. Analyze furniture items and provide realistic price ranges based on quality, brand, and market standards
+        2. Break down pricing by individual furniture pieces
+        3. Provide budget-friendly alternatives and premium options
+        4. Consider different price tiers (budget, mid-range, premium)
+        5. Include estimated total costs for room setups
+        6. Suggest where to find the best deals and shopping recommendations
+        7. Factor in additional costs like delivery, assembly, and accessories
+        8. Provide seasonal pricing insights and best times to buy
+        Always format your response with clear price breakdowns and explanations for the pricing rationale.";
+
+// Define Quote Agent (Stage 3) - Quote Document Generator
+const string QuoteAgentName = "Quote-Agent";
+const string QuoteAgentInstructions = @"You are an assistant that creates a quote for furniture purchase.
+        1. Create a well-structured quote document that includes:
+        2. A title page with the document title, date, and client name
+        3. An introduction summarizing the purpose of the document
+        4. A summary section with total estimated costs and recommendations
+        5. Use clear headings, bullet points, and tables for easy readability
+        6. All quotes are presented in markdown form";
+
+// Helper function to load image as byte array
+async Task<byte[]> OpenImageBytesAsync(string path)
+{
+    return await File.ReadAllBytesAsync(path);
+}
+
+// Load furniture image for analysis
+var imageBytes = await OpenImageBytesAsync(imgPath);
+
+// Create AI agents for the sequential workflow
+AIAgent salesagent = openAIClient.GetChatClient(github_model_id).CreateAIAgent(
+    name: SalesAgentName, instructions: SalesAgentInstructions);
+AIAgent priceagent = openAIClient.GetChatClient(github_model_id).CreateAIAgent(
+    name: PriceAgentName, instructions: PriceAgentInstructions);
+AIAgent quoteagent = openAIClient.GetChatClient(github_model_id).CreateAIAgent(
+    name: QuoteAgentName, instructions: QuoteAgentInstructions);
+
+// Build sequential workflow: Sales → Price → Quote
+var workflow = new WorkflowBuilder(salesagent)
+    .AddEdge(salesagent, priceagent)
+    .AddEdge(priceagent, quoteagent)
+    .Build();
+
+// Create user message with image and instructions
+ChatMessage userMessage = new ChatMessage(ChatRole.User, [
+    new DataContent(imageBytes, "image/png"),
+    new TextContent("Please find the relevant furniture according to the image and give the corresponding price for each piece of furniture. Finally output generates a quotation")
+]);
+
+// Execute workflow with streaming
+StreamingRun run = await InProcessExecution.StreamAsync(workflow, userMessage);
+
+// Process workflow events and collect results
+await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+string id = "";
+string messageData = "";
+await foreach (WorkflowEvent evt in run.WatchStreamAsync().ConfigureAwait(false))
+{
+    if (evt is AgentRunUpdateEvent executorComplete)
+    {
+        if (id == "")
+        {
+            id = executorComplete.ExecutorId;
+        }
+        if (id == executorComplete.ExecutorId)
+        {
+            messageData += executorComplete.Data.ToString();
+        }
+        else
+        {
+            id = executorComplete.ExecutorId;
+        }
+    }
+}
+
+// Display final workflow results (complete quote document)
+Console.WriteLine(messageData);