Microsoft Agent Framework for .NET: Architecture, MCP & Deployment Guide

What Microsoft Agent Framework Is

Microsoft Agent Framework is the official .NET SDK for building autonomous AI agents. Released as RC1 on February 19, 2026, it unifies the agent capabilities that were previously split between Semantic Kernel’s experimental agent subsystem and AutoGen.

If Semantic Kernel answers the question “how do I add AI to my .NET application,” Agent Framework answers “how do I build AI agents that coordinate, reason independently, and complete complex tasks.”

The framework sits in the Microsoft AI stack hierarchy like this:

Expand

Agent Framework builds on Semantic Kernel, not beside it. Your SK plugins, kernel configuration, and DI patterns all transfer directly. Agent Framework adds the agentic layer: agent lifecycle management, multi-agent orchestration, state persistence, and protocol integrations.

When You Need Agent Framework vs Semantic Kernel

This distinction matters because choosing the wrong one adds unnecessary complexity:

Use Semantic Kernel when:

• You’re adding AI chat to an existing application
• You need function calling with tool invocation
• You’re building RAG (retrieval-augmented generation)
• Your workflow is request-response, not autonomous
• You want AI features without agent complexity

Use Agent Framework when:

• You need agents that reason and act autonomously
• Multiple agents need to coordinate on a shared task
• Your workflow has branching, handoffs, or human approval gates
• You need persistent state across long-running agent tasks
• You want to connect agents to external tools via MCP

If you’re unsure, start with Semantic Kernel. When you hit a wall — usually when you need multi-step autonomous workflows or agent-to-agent communication — that’s when Agent Framework earns its complexity cost.

Core Architecture

Agents

An agent is a unit of AI capability with a defined role, instructions, and available tools. In Agent Framework, you create agents using the same SK kernel infrastructure you already know:

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion("chat-deployment", endpoint, apiKey)
    .Build();

kernel.Plugins.AddFromType<FileSystemPlugin>();
kernel.Plugins.AddFromType<DatabasePlugin>();

var researchAgent = new ChatCompletionAgent
{
    Name = "Researcher",
    Instructions = """
        You are a research assistant. Given a topic, use your tools to gather
        relevant information from files and databases. Return structured findings
        with source references. Be thorough but concise.
        """,
    Kernel = kernel
};

Every agent has:

• Name — Identifier for logging and orchestration
• Instructions — System prompt defining the agent’s role and behavior
• Kernel — The Semantic Kernel instance with plugins (tools)

Conversations

Agents communicate through conversation threads. A thread maintains the message history and state:

ChatHistory history = [];
history.AddUserMessage("Research the latest .NET 9 performance benchmarks");

await foreach (var message in researchAgent.InvokeAsync(history))
{
    Console.WriteLine($"[{message.AuthorName}]: {message.Content}");
    history.Add(message);
}

Orchestration Patterns

Agent Framework provides four built-in orchestration patterns. Each solves a different coordination shape:

1. Sequential — Pipeline Processing

Agents execute in order, each building on the previous agent’s output:

using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.Agents.Orchestration;

var sequential = new SequentialOrchestration(researchAgent, analystAgent, writerAgent)
{
    // Research → Analyze → Write
};

var runtime = new InProcessRuntime();
runtime.Start();

var result = await sequential.InvokeAsync(
    "Analyze .NET 9 adoption trends and write a summary report", runtime);

string finalOutput = await result.GetValueAsync(TimeSpan.FromMinutes(5));

Best for: Report generation, content pipelines, ETL-style data processing.

2. Concurrent — Parallel Execution

Multiple agents work simultaneously on the same input:

var concurrent = new ConcurrentOrchestration(
    securityReviewAgent, performanceReviewAgent, codeStyleAgent);

var runtime = new InProcessRuntime();
runtime.Start();

var result = await concurrent.InvokeAsync(codeSnippet, runtime);

// All three reviews complete in parallel
var reviews = await result.GetValueAsync(TimeSpan.FromMinutes(3));

Best for: Code review (multiple perspectives), parallel research, multi-criteria evaluation.

3. Handoff — Dynamic Routing

Agents transfer conversations to the most appropriate agent based on context:

var handoff = new HandoffOrchestration(
    generalSupportAgent, billingAgent, technicalAgent)
{
    // Agents decide when to transfer based on conversation content
};

var runtime = new InProcessRuntime();
runtime.Start();

var result = await handoff.InvokeAsync(
    "I was charged twice for my subscription", runtime);

Each agent’s instructions include handoff conditions:

var generalSupportAgent = new ChatCompletionAgent
{
    Name = "GeneralSupport",
    Instructions = """
        Greet the customer and understand their issue.
        Transfer to BillingAgent for payment/subscription issues.
        Transfer to TechnicalAgent for product/technical issues.
        """,
    Kernel = kernel
};

Best for: Customer support, triage systems, dynamic routing based on conversation intent.

4. Group Chat — Collaborative Discussion

Agents discuss a topic, contributing different expertise:

var groupChat = new GroupChatOrchestration(
    architectAgent, securityAgent, devOpsAgent)
{
    TerminationCondition = new MaxTurnTermination(maxTurns: 10)
};

var runtime = new InProcessRuntime();
runtime.Start();

var result = await groupChat.InvokeAsync(
    "Design a deployment strategy for our new microservice", runtime);

Best for: Design reviews, brainstorming, multi-perspective analysis.

MCP Integration

Agent Framework natively supports the Model Context Protocol (MCP), which lets agents use tools hosted by external MCP servers:

using ModelContextProtocol.Client;

var mcpClient = await McpClientFactory.CreateAsync(
    new McpServerConfig
    {
        Id = "filesystem",
        Name = "File System Tools",
        TransportType = TransportType.StdIO,
        TransportOptions = new Dictionary<string, string>
        {
            ["command"] = "dotnet",
            ["arguments"] = "run --project ./McpFileServer"
        }
    });

// Add MCP tools to the kernel
var tools = await mcpClient.ListToolsAsync();
kernel.Plugins.AddFromFunctions("mcp_filesystem",
    tools.Select(t => t.AsKernelFunction()));

The MCP C# SDK v1.0 (released March 5, 2026) supports authorization, tool sampling, and long-running requests. See MCP C# SDK v1.0: What .NET Developers Need to Know for the full feature breakdown.

Production Deployment

Checkpointing

Long-running agent workflows need state persistence. Agent Framework supports checkpointing so workflows can resume after process restarts:

// Checkpointing is built into the runtime
// When using durable runtimes (e.g., Azure-backed), 
// state persists automatically between invocations

Observability

Agent Framework integrates with OpenTelemetry for tracing agent interactions:

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddSource("Microsoft.SemanticKernel*");
        tracing.AddSource("Microsoft.Agents*");
        tracing.AddOtlpExporter();
    });

This gives you traces showing:

• Which agent handled each conversation turn
• Token usage per agent per turn
• Tool invocation latency and results
• Orchestration flow (handoffs, parallel branches)

Token Management

Multi-agent systems consume tokens rapidly. Each agent turn uses input tokens for context + output tokens for response. A sequential pipeline with three agents and a 4K context processes approximately 12K input tokens per request.

Mitigation strategies:

• Keep agent instructions concise — every token in the system prompt is repeated per turn
• Use context windows wisely — summarize previous agent output before passing to the next
• Set MaxTokens on completion settings to prevent runaway responses
• Track token usage per agent in your observability pipeline

Getting Started

Install the packages:

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core
dotnet add package Microsoft.SemanticKernel.Agents.Orchestration

Build your first two-agent pipeline:

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.Agents.Orchestration;
using Microsoft.SemanticKernel.Agents.Runtime.InProcess;

// Create the kernel
var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion("chat-deployment",
        Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!,
        Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY")!)
    .Build();

// Define two agents with different roles
var researcher = new ChatCompletionAgent
{
    Name = "Researcher",
    Instructions = "You research topics thoroughly and present factual findings.",
    Kernel = kernel
};

var writer = new ChatCompletionAgent
{
    Name = "Writer",
    Instructions = "You take research findings and write clear, engaging summaries.",
    Kernel = kernel
};

// Orchestrate sequentially: Research → Write
var pipeline = new SequentialOrchestration(researcher, writer);

var runtime = new InProcessRuntime();
runtime.Start();

var handle = await pipeline.InvokeAsync(
    "What are the key features of .NET 9 for AI development?", runtime);

string result = await handle.GetValueAsync(TimeSpan.FromMinutes(2));
Console.WriteLine(result);

await runtime.StopAsync();

Migration from Semantic Kernel Agents

If you’ve been using SK’s experimental agents namespace, migrating to Agent Framework is straightforward because the core concepts are identical. See Migrate from Semantic Kernel to Microsoft Agent Framework for a step-by-step guide with side-by-side code comparisons.

The key things that transfer directly:

• KernelFunction plugins — no changes needed
• Kernel configuration — identical
• DI registration patterns — identical
• Chat history management — identical API

What changes:

• Agent creation moves to the Microsoft.SemanticKernel.Agents namespace
• Orchestration uses dedicated pattern classes instead of custom loops
• State management gets built-in checkpointing

Next Steps

• Build Your First AI Agent in .NET — Hands-on agent workshop
• AI Agent Architecture for .NET Developers — Conceptual foundations
• Build a Multi-Agent System in .NET — Advanced multi-agent workshop
• Model Context Protocol Guide — Connect agents to external tools