---

name: microsoft-agent-framework description: Expert guidance for building AI agents and multi-agent workflows using Microsoft Agent Framework for .NET. Use when (1) creating AI agents with OpenAI or Azure OpenAI, (2) implementing function tools and structured outputs, (3) building multi-turn conversations, (4) designing graph-based workflows with streaming/checkpointing, (5) implementing middleware pipelines, (6) orchestrating multi-agent systems with fan-out/fan-in patterns, (7) adding human-in-the-loop interactions, (8) integrating OpenTelemetry observability, or (9) exposing agents as MCP tools.

Microsoft Agent Framework for .NET

Overview

Microsoft Agent Framework is a framework for building, orchestrating, and deploying AI agents and multi-agent workflows. It provides graph-based workflows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities.

Installation

Copy# Core AI package
dotnet add package Microsoft.Agents.AI

# OpenAI/Azure OpenAI support
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

# Google Gemini support (via Microsoft.Extensions.AI)
dotnet add package Mscc.GenerativeAI.Microsoft

# Azure identity for authentication
dotnet add package Azure.Identity

Quick Start

Basic Agent with OpenAI

Copyusing Microsoft.Agents.AI;
using OpenAI;

var agent = new OpenAIClient("<api-key>")
    .GetOpenAIResponseClient("gpt-4o-mini")
    .CreateAIAgent(
        name: "Assistant",
        instructions: "You are a helpful assistant."
    );

Console.WriteLine(await agent.RunAsync("Hello!"));

Azure OpenAI with Azure CLI Auth

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

var agent = new AzureOpenAIClient(
    new Uri("https://<resource>.openai.azure.com/"),
    new AzureCliCredential())
    .GetChatClient("gpt-4o-mini")
    .CreateAIAgent(instructions: "You are helpful.");

Console.WriteLine(await agent.RunAsync("Tell me a joke."));

Azure OpenAI with Bearer Token

Copyvar agent = new OpenAIClient(
    new BearerTokenPolicy(
        new AzureCliCredential(),
        "https://ai.azure.com/.default"),
    new OpenAIClientOptions
    {
        Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1")
    })
    .GetOpenAIResponseClient("gpt-4o-mini")
    .CreateAIAgent(name: "Bot", instructions: "You are helpful.");

Google Gemini

Copyusing Mscc.GenerativeAI;
using Mscc.GenerativeAI.Microsoft;
using Microsoft.Agents.AI;

var googleAI = new GoogleAI("<gemini-api-key>");
var geminiModel = googleAI.GenerativeModel("gemini-2.0-flash");
IChatClient chatClient = geminiModel.AsIChatClient();

var agent = chatClient.CreateAIAgent(
    name: "Assistant",
    instructions: "You are a helpful assistant."
);

Console.WriteLine(await agent.RunAsync("Hello!"));

Function Tools

Define tools using attributes:

Copypublic class WeatherTools
{
    [Description("Gets current weather for a location")]
    public static string GetWeather(
        [Description("City name")] string city)
    {
        return $"Weather in {city}: Sunny, 72F";
    }
}

// Register tools with agent
var agent = client.GetChatClient("gpt-4o-mini")
    .CreateAIAgent(
        instructions: "Help users check weather.",
        tools: [typeof(WeatherTools)]);

await agent.RunAsync("What's the weather in Seattle?");

Function Tools with Approval

For human-in-the-loop approval:

Copyagent.OnToolCall += (sender, args) =>
{
    Console.WriteLine($"Tool: {args.ToolName}");
    Console.Write("Approve? (y/n): ");
    args.Approved = Console.ReadLine()?.ToLower() == "y";
};

Structured Output

Return strongly-typed responses:

Copypublic class MovieRecommendation
{
    public string Title { get; set; }
    public string Genre { get; set; }
    public int Year { get; set; }
    public string Reason { get; set; }
}

var result = await agent.RunAsync<MovieRecommendation>(
    "Recommend a sci-fi movie from the 2020s");

Console.WriteLine($"{result.Title} ({result.Year}) - {result.Reason}");

Multi-Turn Conversations

Copyvar agent = client.GetChatClient("gpt-4o-mini")
    .CreateAIAgent(instructions: "You are a helpful assistant.");

// First turn
var response1 = await agent.RunAsync("My name is Alice.");

// Continues context
var response2 = await agent.RunAsync("What's my name?");

Persisted Conversations

Save and restore conversation state:

Copy// Save state
var state = agent.GetConversationState();
await File.WriteAllTextAsync("state.json", state.ToJson());

// Restore later
var savedState = ConversationState.FromJson(
    await File.ReadAllTextAsync("state.json"));
agent.LoadConversationState(savedState);

Middleware

Add custom processing pipelines:

Copyagent.UseMiddleware(async (context, next) =>
{
    Console.WriteLine($"Request: {context.Input}");
    var start = DateTime.UtcNow;

    await next();

    var duration = DateTime.UtcNow - start;
    Console.WriteLine($"Response time: {duration.TotalMilliseconds}ms");
});

Multi-Modal (Images)

Copyvar result = await agent.RunAsync(
    "Describe this image",
    images: [File.ReadAllBytes("photo.jpg")]);

Observability with OpenTelemetry

Copyusing var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Microsoft.Agents")
    .AddConsoleExporter()
    .Build();

// Agent calls are now traced
await agent.RunAsync("Hello!");

Dependency Injection

Copyservices.AddSingleton<AIAgent>(sp =>
{
    var client = sp.GetRequiredService<OpenAIClient>();
    return client.GetChatClient("gpt-4o-mini")
        .CreateAIAgent(instructions: "You are helpful.");
});

Agent as MCP Tool

Expose agent as Model Context Protocol tool:

Copyvar mcpTool = agent.AsMcpTool(
    name: "research_assistant",
    description: "Researches topics and provides summaries");

Agent as Function Tool

Compose agents by exposing one as a tool for another:

Copyvar researchAgent = client.GetChatClient("gpt-4o")
    .CreateAIAgent(instructions: "You do deep research.");

var mainAgent = client.GetChatClient("gpt-4o-mini")
    .CreateAIAgent(
        instructions: "Answer questions, use research tool for complex topics.",
        tools: [researchAgent.AsFunctionTool("research", "Deep research")]);

Workflows

For complex multi-agent orchestration, see references/workflows.md.

Key workflow patterns:

• Executors and Edges: Basic workflow building blocks
• Streaming: Real-time event streaming
• Fan-Out/Fan-In: Parallel processing
• Checkpointing: Save and resume workflow state
• Human-in-the-Loop: Pause for user input
• Writer-Critic: Iterative refinement loops

Best Practices

1. Use Azure CLI credentials for local development
2. Add OpenTelemetry for production observability
3. Implement middleware for logging, error handling, rate limiting
4. Use structured outputs when you need typed responses
5. Persist conversation state for stateless services
6. Use checkpointing in workflows for reliability
7. Implement human-in-the-loop for sensitive operations

Resources

• GitHub Repository
• MS Learn Documentation
• Quick Start Guide
• Samples