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

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

using 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

using 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

var 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

using 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:

public 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:

agent.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:

public 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

var 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:

// 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:

agent.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)

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

Observability with OpenTelemetry

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

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

Dependency Injection

services.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:

var 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:

var 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

• Use Azure CLI credentials for local development

• Add OpenTelemetry for production observability

• Implement middleware for logging, error handling, rate limiting

• Use structured outputs when you need typed responses

• Persist conversation state for stateless services

• Use checkpointing in workflows for reliability

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

Resources

• GitHub Repository

• MS Learn Documentation

• Quick Start Guide

• Samples