Microsoft Agent Framework - Learn - Open AI

 Perfect! Now I have comprehensive information about .NET Agent frameworks. Let me create a detailed learning guide tailored specifically for you as a .NET developer.

.NET Agent Framework Learning Path - Complete Guide

As a .NET developer, you're in an excellent position—Microsoft has built three complementary frameworks specifically for you. Here's your step-by-step learning path:

---

The Three .NET Agent Frameworks

Framework	Best For	Maturity	Complexity
Microsoft Agent Framework	Multi-agent orchestration, workflows, enterprise	🟢 Production-Ready (Oct 2025)	Advanced
Azure AI Foundry Agent Service	Code-first agents, quick deployment, integration	🟢 Production-Ready (Dec 2025)	Medium
Semantic Kernel	Flexible plugins, planning, research-driven	🟢 Mature (evolving)	Medium

TL;DR for .NET devs: Agent Framework = next-gen (most powerful), Foundry = quick start (easiest), Semantic Kernel = flexible (most versatile)

---

Phase 1: Foundation (Days 1-3)

Step 1: Understand the .NET Agent Ecosystem

Key Architectural Change (Critical!):
Microsoft unified .NET agent development around Microsoft.Extensions.AI.* namespaces:​

• ❌ OLD: Microsoft.SemanticKernel.* (still works, but migrating)

• ✅ NEW: Microsoft.Extensions.AI.* (unified foundation)

• ✅ NEW: Microsoft.Agent.Framework.* (orchestration)

Why This Matters:

• Standardized AI building blocks across all frameworks

• Agents now manage threads natively

• Simpler tool registration without attributes/wrappers

• Better integration with dependency injection

Step 2: Set Up Your .NET Development Environment

bash
# Prerequisites
✅ .NET 8 or later (required)
✅ Visual Studio 2022 or VS Code
✅ Azure CLI: az login (authenticate to Azure)
✅ Azure Subscription with resources

# Create your first project
dotnet new console -n MyAgentApp
cd MyAgentApp

# Install core NuGet packages
dotnet add package Azure.AI.Projects --version 1.0.0
dotnet add package Microsoft.Extensions.AI --version 9.0.0
dotnet add package Microsoft.SemanticKernel --version 1.34.0 # if using SK

Step 3: Choose Your Starting Framework

Quick Decision Matrix:

text
Need enterprise multi-agent orchestration? 
  → Start with Microsoft Agent Framework
  
Need to deploy quickly with minimal setup?
  → Start with Azure AI Foundry Service
  
Need flexibility and plugin-based design?
  → Start with Semantic Kernel

---

Phase 2A: Azure AI Foundry Agent Service (Easiest Start)

Best if: You want the fastest path to a working agent (Days 4-6)

Step 4: Create Your First Foundry Agent in the Portal

1. Go to Azure AI Foundry: https://ai.azure.com

2. Create a Project → Select gpt-4o-mini model

3. Build & Customize → Agents → + Create agent

4. Configure:

   text
   Name: MyFirstAgent
   Instructions: You are a helpful C# code assistant
   Model: gpt-4o-mini
   Tools: Code Interpreter ✓
   

5. Test in Playground → Ask: "Write a simple C# LINQ example"

Step 5: Build with Azure AI Foundry .NET SDK

C# Code Example:

csharp
using Azure;
using Azure.AI.Projects;
using Azure.Identity;

// Initialize client (uses DefaultAzureCredential)
var projectClient = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")),
    new DefaultAzureCredential()
);

// Create agent with code interpreter
var agent = await projectClient.Agents.CreateAgentAsync(
    new CreateAgentOptions
    {
        Name = "CodeHelper",
        Instructions = "You are a C# programming expert. Help users with .NET code.",
        Model = "gpt-4o-mini",
        Tools = new List<ToolDefinition>
        {
            new CodeInterpreterToolDefinition()
        }
    }
);

// Create a thread (conversation)
var thread = await projectClient.Agents.Threads.CreateThreadAsync();

// Send a message
var message = await projectClient.Agents.Messages.CreateMessageAsync(
    thread.Id,
    new CreateMessageOptions
    {
        Role = "user",
        Content = "Write a C# async method to fetch weather data"
    }
);

// Run the agent
var run = await projectClient.Agents.Runs.CreateAndProcessRunAsync(
    thread.Id,
    agent.Id
);

// Get responses
var messages = await projectClient.Agents.Messages.ListMessagesAsync(
    thread.Id
);

foreach (var msg in messages)
{
    Console.WriteLine($"Role: {msg.Role}, Content: {msg.Content}");
}

Key Points:

• ✅ No special configuration needed beyond PROJECT_ENDPOINT environment variable

• ✅ Built-in code interpreter for executing C# code

• ✅ Thread management is automatic

• ✅ Minimal boilerplate code

---

Phase 2B: Semantic Kernel (Maximum Flexibility)

Best if: You need plugins, planners, and fine-grained control (Days 4-6)

Step 6: Build Agents with Semantic Kernel

Installation:

bash
dotnet add package Microsoft.SemanticKernel --version 1.34.0

Example: Email Agent with Plugins

csharp
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

// Initialize kernel
var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(
        deploymentName: "gpt-4o-mini",
        endpoint: new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")),
        apiKey: Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
    )
    .Build();

// Define email plugin
public class EmailPlugin
{
    [KernelFunction]
    [Description("Send an email")]
    public async Task SendEmailAsync(
        [Description("Recipient email")] string to,
        [Description("Subject")] string subject,
        [Description("Body")] string body)
    {
        // Simulate sending
        Console.WriteLine($"Email sent to {to}: {subject}");
        return "Email sent successfully";
    }

    [KernelFunction]
    [Description("Get email templates")]
    public string GetEmailTemplate(string category)
    {
        return category switch
        {
            "meeting" => "Meeting invitation template...",
            "followup" => "Follow-up template...",
            _ => "Generic template..."
        };
    }
}

// Register plugin
kernel.Plugins.AddFromType<EmailPlugin>();

// Create agent
var agent = new ChatCompletionAgent
{
    Name = "EmailAssistant",
    Instructions = "You are a professional email assistant. Use email tools to compose and send emails.",
    Kernel = kernel,
    ExecutionSettings = new OpenAIPromptExecutionSettings { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions }
};

// Use agent
var chat = new AgentGroupChat(agent);
await chat.AddUserMessageAsync("Send a meeting invitation to john@example.com");
await agent.InvokeAsync(chat);

// Get responses
foreach (var message in chat.GetMessages())
{
    Console.WriteLine($"{message.Role}: {message.Content}");
}

Key Semantic Kernel Concepts:

Concept	Purpose	Usage
Kernel	Core engine	Coordinates plugins, models, functions
Plugin	Reusable function set	[KernelFunction] decorated methods
ChatCompletionAgent	Agent type	Multi-turn conversation with plugins
ChatGroupAgent	Multi-agent	Multiple agents collaborating

---

Phase 2C: Microsoft Agent Framework (Production Enterprise)

Best if: You need orchestration, workflows, and multi-agent systems (Days 7-11)

Step 7: Master Agent Framework

Installation:

bash
# Core framework
dotnet add package Microsoft.Agent.Framework --version 1.0.0

# For Azure AI Foundry integration
dotnet add package Microsoft.Agent.Framework.Azure --version 1.0.0

# For code interpreter
dotnet add package Microsoft.Extensions.AI --version 9.0.0

Key Capabilities:​

✅ Multi-Agent Orchestration - Sequential, concurrent, hand-off, magentic patterns
✅ Workflow Checkpointing - Save/resume long-running processes
✅ Human-in-the-Loop - Route approvals before tool execution
✅ Native Thread Management - Agents handle state automatically
✅ OpenTelemetry Integration - Built-in observability
✅ MCP Server Support - Model Context Protocol for external tools

Step 8: Build Your First Agent Framework Agent

csharp
using Microsoft.Agent.Framework;
using Microsoft.Agent.Framework.Azure;
using Microsoft.Extensions.AI;
using Azure.Identity;

// Initialize with Azure OpenAI
var chatClient = new AzureOpenAIClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")),
    new DefaultAzureCredential()
).AsChatClient("gpt-4o-mini");

// Create agent
var agent = new Agent(
    id: "sales-analyst",
    name: "Sales Analyst Agent",
    instructions: """
        You are a sales data analyst. 
        Use database tools to query sales data.
        Provide insights and recommendations.
        """,
    chatClient: chatClient
);

// Add tools (native support - no attributes needed!)
agent.AddTool("fetch_sales_data", new ToolDefinition(
    name: "fetch_sales_data",
    description: "Fetch sales data from database",
    inputSchema: new JsonSchema
    {
        Type = "object",
        Properties = new Dictionary<string, JsonSchema>
        {
            { "month", new JsonSchema { Type = "string", Description = "Month name" } },
            { "year", new JsonSchema { Type = "integer", Description = "Year" } }
        }
    },
    handler: async (input) => 
    {
        // Query database
        return await FetchSalesFromDatabase(input["month"], input["year"]);
    }
));

// Run agent
var thread = new AgentThread();
var response = await agent.RunAsync(
    thread: thread,
    input: "What were our Q3 2025 sales by region?",
    cancellationToken: CancellationToken.None
);

Console.WriteLine(response);

---

Phase 3: Advanced Features (Days 8-11)

Step 9: Multi-Agent Orchestration

Use Case: Sales agent + Customer service agent + Billing agent working together

csharp
// Define specialized agents
var salesAgent = new Agent(id: "sales", instructions: "You handle sales inquiries");
var serviceAgent = new Agent(id: "service", instructions: "You handle support tickets");
var billingAgent = new Agent(id: "billing", instructions: "You handle billing issues");

// Create orchestrator
var orchestrator = new AgentOrchestrator(
    agents: new[] { salesAgent, serviceAgent, billingAgent },
    routingStrategy: RoutingStrategy.Magentic // LLM decides which agent handles it
);

// Route customer inquiry
var result = await orchestrator.ProcessAsync(
    input: "I have a billing problem but also want to upgrade my plan"
);

// Both agents collaborate on the response
Console.WriteLine(result); // Multi-agent response

Orchestration Patterns:​

• Sequential: Agent A → Agent B → Agent C (ordered)

• Concurrent: All agents run in parallel

• Hand-off: Agent transfers to another mid-conversation

• Magentic: LLM intelligently routes between agents

Step 10: Implement Workflows

csharp
using Microsoft.Agent.Framework.Workflows;

// Define workflow steps
var workflow = new AgentWorkflow()
    .AddStep(
        name: "validate_order",
        agent: validationAgent,
        input: "Validate customer order"
    )
    .AddStep(
        name: "process_payment",
        agent: paymentAgent,
        input: context => context.GetStepOutput("validate_order")
    )
    .AddStep(
        name: "confirm_shipment",
        agent: shippingAgent,
        input: context => context.GetStepOutput("process_payment")
    )
    .WithCheckpoint() // Save state for recovery
    .WithApproval(requiresApproval: true, forStep: "process_payment"); // Human approval

// Execute workflow
var executionResult = await workflow.ExecuteAsync(
    input: new { customerId = "12345", orderAmount = 500 }
);

Console.WriteLine($"Workflow completed: {executionResult.Success}");

Step 11: Add Custom Tools with MCP

Model Context Protocol Integration:

csharp
// Connect MCP server (e.g., database access)
var mcpServer = new MCPServerClient(
    uri: "stdio:///path/to/mcp-database-server"
);

await agent.AddMCPToolsAsync(mcpServer);

// Now agent can directly query databases via MCP
var response = await agent.RunAsync(
    thread: thread,
    input: "Get all customers from the database where revenue > $100k"
);

---

Phase 4: Production Deployment (Days 12-14)

Step 12: Host on Azure App Service

csharp
// Program.cs for ASP.NET Core
var builder = WebApplication.CreateBuilder(args);

// Register agents as services
builder.Services.AddSingleton<SalesAgent>();
builder.Services.AddSingleton<SupportAgent>();

// Register Agent Framework
builder.Services.AddAgentFramework()
    .WithAzureAIFoundry(config =>
    {
        config.Endpoint = builder.Configuration["Azure:AIFoundryEndpoint"];
        config.SubscriptionId = builder.Configuration["Azure:SubscriptionId"];
    })
    .WithObservability(config =>
    {
        config.EnableOpenTelemetry = true;
        config.ApplicationInsightsKey = builder.Configuration["ApplicationInsights:InstrumentationKey"];
    });

var app = builder.Build();

// API endpoint to invoke agent
app.MapPost("/api/chat", async (ChatRequest request, SalesAgent agent) =>
{
    var thread = new AgentThread();
    var response = await agent.RunAsync(thread, request.Message);
    return Results.Ok(new { response });
});

app.Run();

Deployment Checklist:

•  Use managed identity (DefaultAzureCredential)

•  Configure RBAC: Azure AI User role at project scope

•  Enable OpenTelemetry → Application Insights

•  Set up CI/CD with GitHub Actions

•  Implement human-in-the-loop for sensitive operations

•  Add telemetry and monitoring

•  Test error handling and recovery

Step 13: Testing & Validation

csharp
// Unit test with mocked tools
[Test]
public async Task Agent_Should_Call_Database_Tool()
{
    var mockTool = new Mock<IToolDefinition>();
    var agent = new Agent(instructions: "test", tools: new[] { mockTool.Object });
    
    var result = await agent.RunAsync(
        thread: new AgentThread(),
        input: "Fetch sales data"
    );
    
    mockTool.Verify(t => t.InvokeAsync(It.IsAny<object>()), Times.Once);
}

---

Recommended Learning Resources for .NET Devs

Resource	Type	Focus	Duration
Agent Framework Quick-Start	Quickstart	Setup & basics	15 mins
Foundry Agent Service (.NET) Tutorial	Tutorial	Code-first agents	30 mins
Semantic Kernel Samples (C#)	GitHub	Plugins & planning	Self-paced
Build Agentic Web App (ASP.NET Core)	Full Tutorial	Production patterns	1-2 hours
.NET AI Community Standup	Video	Framework overview	1 hour
Building AI Agents in .NET with Semantic Kernel	Video	Hands-on example	30 mins

---

Key Differences: Which Framework to Use?

Azure AI Foundry Service

✅ Use when:

• You want quick deployment with portal + SDK

• You need code interpreter, Bing grounding, knowledge base

• You prefer managed service (less infrastructure)

❌ Don't use when:

• You need advanced orchestration patterns

• You want completely local-first development

Best for: Quick prototypes, startups, managed service preference

Semantic Kernel

✅ Use when:

• You want flexible plugin-based architecture

• You need planning/reasoning capabilities

• You like research-driven patterns

❌ Don't use when:

• You need multi-agent orchestration

• You want enterprise-grade workflows

Best for: Flexibility, plugins, experimentation

Microsoft Agent Framework

✅ Use when:

• You need multi-agent orchestration

• You want workflows with checkpointing

• You need production-grade features (human approvals, observability)

• You're building enterprise systems

❌ Don't use when:

• You want simplicity (Framework has more concepts)

• You're building single-agent chatbots

Best for: Enterprise, complex systems, production

---

Quick 14-Day .NET Agent Mastery Plan

text
Days 1-3:   Foundation + Environment Setup
Days 4-6:   Azure Foundry Agent Service (Easiest)
Days 7-9:   Semantic Kernel Plugins & Agents
Days 10-11: Agent Framework Orchestration
Days 12-13: Multi-Agent Workflows & Tools
Day 14:     Production Deployment on App Service

---

Your Advantage as a .NET Developer

You have several advantages over Python developers:

1. ✅ Dependency Injection - Built-in DI with ASP.NET Core

2. ✅ Type Safety - C# static typing prevents bugs

3. ✅ Enterprise Patterns - Know middleware, authentication, RBAC

4. ✅ Async/Await - Better async patterns than Python

5. ✅ Hosting - Deep knowledge of App Service, deployment patterns

---

Would you like me to create:

1. A working code-first agent project you can clone and modify?

2. A detailed comparison spreadsheet of all three frameworks?

3. A production-ready ASP.NET Core web app with agents integrated?

Let me know which direction you'd like to go! 🚀