Dotnet Microsoft Agent Framework

dotnet-microsoft-agent-framework

Microsoft Agent Framework for building agentic AI applications in .NET. Covers agents, workflows, multi-agent orchestration, tool integration (MCP servers, function calling), provider configuration (Azure OpenAI, OpenAI, Microsoft Foundry, Anthropic, Ollama), chat history management, middleware, and enterprise features (observability, authentication, responsible AI).

Scope

• Agent creation and configuration for all supported providers
• Workflow orchestration (sequential, concurrent, group chat, handoff, magentic)
• Tool integration (MCP servers, function calling, hosted tools)
• Chat history and session management
• Middleware for intercepting agent actions
• Enterprise observability with OpenTelemetry
• Authentication with Microsoft Entra
• Responsible AI features (prompt injection protection, content safety)

Out of scope

• General async/await patterns and cancellation token propagation -- see [skill:dotnet-csharp-async-patterns]
• DI container mechanics and service lifetime management -- see [skill:dotnet-csharp-dependency-injection]
• HTTP client resilience and retry policies -- see [skill:dotnet-resilience]
• Configuration binding (options pattern, secrets) -- see [skill:dotnet-csharp-configuration]

Cross-references: [skill:dotnet-csharp-async-patterns] for async streaming patterns used with chat completions, [skill:dotnet-csharp-dependency-injection] for agent service registration in ASP.NET Core, [skill:dotnet-resilience] for retry policies on AI service calls, [skill:dotnet-csharp-configuration] for managing API keys and model configuration.

Package Landscape

Agents

OpenAI

The OpenAI provider supports three client types with different capabilities:

Chat Completion Agent

using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var chatClient = client.GetChatClient("gpt-4o-mini");

AIAgent agent = chatClient.AsAIAgent(
    instructions: "You are a helpful assistant specialized in data analysis.",
    name: "DataAnalyst");

var response = await agent.RunAsync("Analyze Q3 sales trends.");
Console.WriteLine(response);

Responses API Agent

using Microsoft.Agents.AI.OpenAI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var responsesClient = client.GetResponsesClient("gpt-4o");

AIAgent agent = responsesClient.AsAIAgent(
    instructions: "You are a research assistant with access to web search.",
    name: "ResearchAssistant");

// Responses API supports hosted tools (web search, file search, code interpreter)
var response = await agent.RunAsync("Find recent articles about .NET 10 features.");

OpenAI Assistants

using Microsoft.Agents.AI.OpenAI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var assistantClient = client.GetAssistantClient();

// Create a persistent assistant with built-in tools
var assistant = await assistantClient.CreateAssistantAsync(
    model: "gpt-4o",
    name: "CodeReviewer",
    instructions: "You review code for best practices and potential issues.",
    tools: ["code_interpreter"]);

AIAgent agent = assistant.AsAIAgent();

Azure OpenAI

Azure OpenAI provides enterprise-grade AI with managed endpoints, private networking, and Microsoft Entra authentication.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;

AzureOpenAIClient client = new AzureOpenAIClient(
    new Uri("https://<resource>.openai.azure.com"),
    new DefaultAzureCredential());

var chatClient = client.GetChatClient("gpt-4o");

AIAgent agent = chatClient.AsAIAgent(
    instructions: "You are a customer support agent for Contoso.");

var response = await agent.RunAsync("I need help with my order.");

Azure OpenAI also supports Responses and Assistants APIs:

// Responses API
var responsesClient = client.GetResponsesClient("gpt-4o");
AIAgent agent = responsesClient.AsAIAgent(instructions: "...");

// Assistants API
var assistantClient = client.GetAssistantClient();
var assistant = await assistantClient.CreateAssistantAsync(model: "gpt-4o", ...);
AIAgent agent = assistant.AsAIAgent();

Microsoft Foundry Agent Service

Foundry Agent Service provides managed, scalable agents with built-in content safety, persistent storage, and Microsoft 365 integration.

using Azure.AI.Agents.Persistent;
using Azure.Identity;
using Microsoft.Agents.AI;

var persistentAgentsClient = new PersistentAgentsClient(
    "https://<resource>.services.ai.azure.com/api/projects/<project>",
    new DefaultAzureCredential());

// Create a new agent in the service
AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
    model: "gpt-4o-mini",
    name: "SupportBot",
    instructions: "You handle customer support inquiries.");

// Use the agent
var response = await agent.RunAsync("My account is locked.");

// Or retrieve an existing agent
AIAgent existingAgent = await persistentAgentsClient.GetAIAgentAsync("<agent-id>");

Anthropic

using Microsoft.Agents.AI.Anthropic;
using Anthropic;

var client = new AnthropicClient("<api_key>");
var agent = client.AsAIAgent(
    model: "claude-3-opus-20240229",
    instructions: "You are a helpful assistant.");

var response = await agent.RunAsync("Explain quantum computing.");

Ollama (Local Models)

using Microsoft.Agents.AI.Ollama;

var client = new OllamaClient(new Uri("http://localhost:11434"));
var agent = client.AsAIAgent(
    model: "llama3.2",
    instructions: "You are a local AI assistant.");

var response = await agent.RunAsync("Summarize this document.");

Generic IChatClient Agent

Any service implementing Microsoft.Extensions.AI.IChatClient can be used with ChatClientAgent:

using Microsoft.Agents.AI;

// IChatClient from any provider
IChatClient chatClient = GetChatClientFromAnyProvider();

AIAgent agent = new ChatClientAgent(
    chatClient,
    instructions: "You are a helpful assistant.");

var response = await agent.RunAsync("Hello!");

Workflows

Workflows provide graph-based orchestration for multi-step tasks with type-safe routing, checkpointing, and human-in-the-loop support.

Sequential Workflow

using Microsoft.Agents.AI.Workflows;

var workflow = WorkflowBuilder.CreateSequential()
    .AddStep<ResearchStep>("research")
    .AddStep<WriteStep>("write")
    .AddStep<ReviewStep>("review")
    .Build();

var result = await workflow.ExecuteAsync(new ResearchInput { Topic = "AI in Healthcare" });

Conditional/Branching Workflow

var workflow = WorkflowBuilder.Create()
    .AddStep<AnalyzeIntentStep>("analyze")
    .AddBranch(
        condition: ctx => ctx.Get<Intent>("intent") == Intent.Support,
        thenBranch: b => b.AddStep<HandleSupportStep>("support"),
        elseBranch: b => b.AddStep<HandleSalesStep>("sales"))
    .Build();

Agent Group Chat

Multiple agents collaborating with termination conditions:

using Microsoft.Agents.AI.Workflows;

var analyst = new ChatClientAgent(chatClient,
    instructions: "You analyze data and provide insights. Be concise.");

var writer = new ChatClientAgent(chatClient,
    instructions: "You take analysis and write clear reports.");

var workflow = WorkflowBuilder.CreateGroupChat()
    .AddAgent(analyst, "analyst")
    .AddAgent(writer, "writer")
    .WithTerminationCondition(ctx =>
        ctx.Messages.Last().Content.Contains("[COMPLETE]"))
    .WithMaxIterations(10)
    .Build();

var result = await workflow.ExecuteAsync("Analyze Q4 sales and write a summary report.");

Handoff Pattern

Transfer control between specialized agents:

var triage = new ChatClientAgent(chatClient,
    instructions: "You triage requests and hand off to specialists.");

var billing = new ChatClientAgent(chatClient,
    instructions: "You handle billing questions.");

var technical = new ChatClientAgent(chatClient,
    instructions: "You handle technical support.");

var workflow = WorkflowBuilder.Create()
    .AddStep<AgentStep>("triage", triage)
    .AddHandoff(
        from: "triage",
        condition: ctx => ctx.Get<string>("department") == "billing",
        to: billing)
    .AddHandoff(
        from: "triage",
        condition: ctx => ctx.Get<string>("department") == "technical",
        to: technical)
    .Build();

Magentic Pattern (Lead Agent)

A lead agent directs other agents:

var orchestrator = new ChatClientAgent(chatClient,
    instructions: "You are an orchestrator. Delegate tasks to specialists and synthesize results.");

var workflow = WorkflowBuilder.CreateMagentic()
    .WithLeadAgent(orchestrator)
    .AddSpecialist("researcher", researchAgent, "Research specialist")
    .AddSpecialist("coder", codeAgent, "Code specialist")
    .Build();

var result = await workflow.ExecuteAsync("Build a web scraper that extracts product prices.");

Tools and Function Calling

Function Tools

public sealed class OrderTools
{
    [Function("get_order_status")]
    [Description("Retrieves the status of an order by ID")]
    public async Task<OrderStatus> GetOrderStatusAsync(
        [Description("The order ID to look up")] string orderId,
        CancellationToken ct = default)
    {
        // Implementation
        return await _orderService.GetStatusAsync(orderId, ct);
    }

    [Function("cancel_order")]
    [Description("Cancels an order if eligible")]
    public async Task<CancelResult> CancelOrderAsync(
        [Description("The order ID to cancel")] string orderId,
        CancellationToken ct = default)
    {
        // Implementation
        return await _orderService.CancelAsync(orderId, ct);
    }
}

// Register tools with agent
var agent = chatClient.AsAIAgent(
    instructions: "You help customers with their orders.",
    tools: new OrderTools());

MCP (Model Context Protocol) Tools

Connect to MCP servers for external tools:

using Microsoft.Agents.AI.Tools.MCP;

// Connect to an MCP server
var mcpClient = new MCPClient("https://api.example.com/mcp");

// Get available tools from the server
var tools = await mcpClient.ListToolsAsync();

// Create agent with MCP tools
var agent = chatClient.AsAIAgent(
    instructions: "You have access to external data sources via MCP.",
    tools: tools);

// Or connect to hosted MCP servers (Azure OpenAI, OpenAI Responses API)
var responsesClient = client.GetResponsesClient("gpt-4o");
var agent = responsesClient.AsAIAgent(
    instructions: "You have access to hosted tools.",
    hostedTools: ["web_search", "file_search", "code_interpreter"]);

Hosted Tools (Responses API)

using Microsoft.Agents.AI.OpenAI;

var responsesClient = client.GetResponsesClient("gpt-4o");

var agent = responsesClient.AsAIAgent(
    instructions: "You are a research assistant.",
    hostedTools: new HostedTools
    {
        WebSearch = new WebSearchTool(),
        FileSearch = new FileSearchTool { VectorStoreIds = ["vs_123"] },
        CodeInterpreter = new CodeInterpreterTool()
    });

var response = await agent.RunAsync("Search for recent papers on climate change and analyze the data.");

Chat History and Sessions

Session Management

using Microsoft.Agents.AI.Sessions;

// Create a new session
var session = new AgentSession();

// Multi-turn conversation
await agent.RunAsync("What's the weather?", session);
await agent.RunAsync("Will it rain tomorrow?", session); // Has context from previous turn

// Persist session for later
var sessionData = session.Serialize();
// ... save to database ...

// Restore session later
var restoredSession = AgentSession.Deserialize(sessionData);

Chat History Providers

Use Redis or other providers for distributed session storage:

using Microsoft.Agents.AI.Sessions.Redis;

builder.Services.AddRedisChatHistoryProvider(
    connectionString: "localhost:6379");

// Agent automatically uses Redis for session persistence
var agent = chatClient.AsAIAgent(
    instructions: "You remember previous conversations.",
    chatHistoryProvider: provider);

Custom Context Providers

public class RAGContextProvider : IContextProvider
{
    private readonly IVectorStore _vectorStore;

    public async Task<IEnumerable<ChatMessage>> GetContextAsync(
        string userMessage,
        CancellationToken ct)
    {
        // Retrieve relevant documents
        var embedding = await GenerateEmbeddingAsync(userMessage, ct);
        var docs = await _vectorStore.SearchAsync(embedding, top: 5, ct);

        return docs.Select(d => new ChatMessage(
            Role.System,
            $"Context: {d.Content}"));
    }
}

var agent = chatClient.AsAIAgent(
    instructions: "You answer based on the provided context.",
    contextProviders: [new RAGContextProvider(vectorStore)]);

Middleware

Middleware intercepts agent actions for logging, authorization, rate limiting, and modification.

Authorization Middleware

public class AuthorizationMiddleware : IAgentMiddleware
{
    public async Task<AgentResponse> InvokeAsync(
        AgentContext context,
        Func<AgentContext, Task<AgentResponse>> next)
    {
        // Check authorization before processing
        if (context.FunctionName == "cancel_order")
        {
            var userId = context.User.Identity?.Name;
            var orderId = context.Arguments["orderId"]?.ToString();

            if (!await _authService.CanCancelOrderAsync(userId, orderId))
            {
                return new AgentResponse("You are not authorized to cancel this order.");
            }
        }

        return await next(context);
    }
}

// Register middleware
var agent = chatClient.AsAIAgent(instructions: "...")
    .UseMiddleware<AuthorizationMiddleware>();

Logging Middleware

public class LoggingMiddleware : IAgentMiddleware
{
    private readonly ILogger<LoggingMiddleware> _logger;

    public async Task<AgentResponse> InvokeAsync(
        AgentContext context,
        Func<AgentContext, Task<AgentResponse>> next)
    {
        _logger.LogInformation(
            "Agent {AgentName} processing: {Message}",
            context.AgentName,
            context.UserMessage);

        var stopwatch = Stopwatch.StartNew();
        var response = await next(context);
        stopwatch.Stop();

        _logger.LogInformation(
            "Agent {AgentName} completed in {ElapsedMs}ms",
            context.AgentName,
            stopwatch.ElapsedMilliseconds);

        return response;
    }
}

Rate Limiting Middleware

public class RateLimitMiddleware : IAgentMiddleware
{
    private readonly IRateLimiter _rateLimiter;

    public async Task<AgentResponse> InvokeAsync(
        AgentContext context,
        Func<AgentContext, Task<AgentResponse>> next)
    {
        var userId = context.User.Identity?.Name;

        if (!await _rateLimiter.TryAcquireAsync(userId))
        {
            return new AgentResponse("Rate limit exceeded. Please try again later.");
        }

        return await next(context);
    }
}

Enterprise Features

Observability with OpenTelemetry

using Microsoft.Agents.AI.Telemetry;

// Configure OpenTelemetry
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddAgentFrameworkInstrumentation();
        tracing.AddAzureMonitorTraceExporter();
    })
    .WithMetrics(metrics =>
    {
        metrics.AddAgentFrameworkMetrics();
        metrics.AddAzureMonitorMetricExporter();
    });

// All agent interactions automatically emit traces and metrics

Authentication with Microsoft Entra

using Azure.Identity;
using Microsoft.Agents.AI;

// Use managed identity in production
AzureOpenAIClient client = new AzureOpenAIClient(
    new Uri("https://<resource>.openai.azure.com"),
    new ManagedIdentityCredential());

// Or use Entra ID for user-delegated access
var credential = new InteractiveBrowserCredential();

Responsible AI

using Microsoft.Agents.AI.Safety;

var agent = chatClient.AsAIAgent(instructions: "...")
    .UseSafetyFilters(new SafetyOptions
    {
        // Prompt injection protection
        PromptInjectionDetection = true,

        // Content safety
        ContentSafety = new ContentSafetyOptions
        {
            HateSpeech = FilterSeverity.Medium,
            SelfHarm = FilterSeverity.High,
            Violence = FilterSeverity.Medium
        },

        // Task adherence monitoring
        TaskAdherenceMonitoring = true
    });

Streaming Responses

var agent = chatClient.AsAIAgent(instructions: "...");
var session = new AgentSession();

await foreach (var chunk in agent.RunStreamingAsync("Tell me a story.", session))
{
    Console.Write(chunk.Content);
}

Key Principles

• Prefer Agents for open-ended tasks -- Use agents when the task is conversational or requires autonomous tool use. If you can write a deterministic function, do that instead.
• Use Workflows for structured processes -- When the process has well-defined steps or requires explicit control over execution order, use workflows over single agents.
• Choose the right API -- Chat Completion for simple cases, Responses API for hosted tools, Assistants for persistent stateful conversations.
• Design focused tools -- Each tool should represent a single domain. Use [Description] attributes so the model knows when and how to call them.
• Do not store API keys in code -- Use environment variables, Azure Key Vault, or Managed Identity (see [skill:dotnet-csharp-configuration])
• Implement middleware for cross-cutting concerns -- Use middleware for logging, authorization, and rate limiting rather than duplicating logic in tools.
• Use chat history providers for distributed apps -- In multi-instance deployments, use Redis or other providers for session persistence.
• Enable observability in production -- Always configure OpenTelemetry tracing and metrics for production deployments.
• Validate inputs in tools -- AI models may call tools with unexpected arguments. Validate all inputs before executing operations.
• Handle cancellation tokens -- Always propagate CancellationToken through tool methods to support timeouts and user cancellations.

Agent Gotchas

1. Do not hardcode API keys -- Use DefaultAzureCredential for development and ManagedIdentityCredential for production. Hardcoded secrets leak into source control.
2. Do not ignore function return types -- The model receives the serialized result. Return summary DTOs, not full entity graphs, to avoid exceeding token limits.
3. Do not create agents per request -- Agents are designed to be long-lived. Register in DI and reuse across requests.
4. Do not forget middleware ordering -- Middleware executes in registration order. Place authorization before logging if you want to log only authorized requests.
5. Do not assume MCP availability -- Always handle cases where MCP servers are unavailable or return errors.
6. Do not store sensitive data in chat history -- Filter out PII before persisting chat history. Use context providers for sensitive data instead.
7. Do not skip cancellation token propagation -- AI calls can hang or take too long. Always propagate CancellationToken to allow cancellation.
8. Do not mix streaming and non-streaming inconsistently -- Choose one pattern per endpoint to avoid confusing client behavior.

Prerequisites

• .NET 8.0 or later
• Microsoft.Agents.AI NuGet package (prerelease)
• Provider-specific packages (e.g., Microsoft.Agents.AI.OpenAI, Microsoft.Agents.AI.AzureAI)
• Azure subscription (for Azure OpenAI or Foundry)
• OpenAI API key (for OpenAI direct)
• Ollama installation (for local models)

References

• Microsoft Agent Framework documentation
• .NET AI ecosystem tools
• Agent Framework samples
• MCP Protocol
• Azure OpenAI documentation
• Microsoft Foundry Agent Service

Code Navigation (Serena MCP)

Primary approach: Use Serena symbol operations for efficient code navigation:

1. Find definitions: serena_find_symbol instead of text search
2. Understand structure: serena_get_symbols_overview for file organization
3. Track references: serena_find_referencing_symbols for impact analysis
4. Precise edits: serena_replace_symbol_body for clean modifications

When to use Serena vs traditional tools:

• Use Serena: Navigation, refactoring, dependency analysis, precise edits
• Use Read/Grep: Reading full files, pattern matching, simple text operations
• Fallback: If Serena unavailable, traditional tools work fine

Example workflow:

# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"

# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"