Microsoft Agent Framework (.NET) — Feature Tour
A short tour of the .NET framework's main features beyond the single agent, with links to the pages that cover each: A2A, graph workflows, checkpointing, human-in-the-loop, orchestrations, hosting, OpenTelemetry and evaluation, plus declarative YAML agents, content-safety middleware and dependency-injection patterns with compiled examples.
First written: November 2025, for the October 2025 public preview
Verified against: Microsoft.Agents.AI 1.28.0 (checked 2026-11-19). Every C# block on this page was compiled against that release, and the declarative agent was run against a local stand-in for the OpenAI API.
Target audience: .NET/C# developers
.NET version: 8.0+
This page started as a tour of the preview’s headline features. Most of them now have their own pages; the sections below summarise each and link to the full treatment, and keep the code only for the features that are not covered elsewhere (declarative agents, content-safety middleware and dependency-injection patterns).
The preview-era version of this page described Microsoft.Agents.AI.Graphs, .Config, .Telemetry and .Safety namespaces (AgentGraph, HITLConfig, A2AProtocolAdapter, AgentTelemetry, ContentSafetyConfig). They never shipped. The shipped equivalents are:
| Feature | Package / namespace | Key types | Covered on |
|---|---|---|---|
| A2A client | Microsoft.Agents.AI.A2A (preview) | A2ACardResolver.GetAIAgentAsync(), A2AAgent | Hosting: A2A |
| A2A server | Microsoft.Agents.AI.Hosting.A2A.AspNetCore (preview) | AddA2AServer, MapA2AJsonRpc, MapA2AHttpJson | Hosting: A2A |
| Graph workflows | Microsoft.Agents.AI.Workflows | WorkflowBuilder, Executor<TIn,TOut>, InProcessExecution | Workflows |
| Checkpointing | Microsoft.Agents.AI.Workflows | CheckpointManager, CheckpointInfo | Workflows: checkpointing |
| Human-in-the-loop | Microsoft.Agents.AI.Workflows | RequestPort, RequestInfoEvent | Workflows: request ports |
| Orchestrations | Microsoft.Agents.AI.Workflows | AgentWorkflowBuilder | Orchestrations |
| Declarative agents | Microsoft.Agents.AI.Declarative (rc) | ChatClientPromptAgentFactory, CreateFromYamlAsync | Below |
| Declarative workflows | Microsoft.Agents.AI.Workflows.Declarative | DeclarativeWorkflowBuilder | Workflows: declarative |
| OpenTelemetry | Microsoft.Agents.AI, Microsoft.Agents.AI.Workflows | .AsBuilder().UseOpenTelemetry(), WithOpenTelemetry() | Observability |
| Evaluation | Microsoft.Agents.AI | LocalEvaluator, EvalChecks, EvaluateAsync | Testing and evaluation |
| Content safety | your middleware over Azure.AI.ContentSafety | .AsBuilder().Use(...), DelegatingAIAgent | Below |
| Hosting / DI | Microsoft.Agents.AI.Hosting (preview) | AddAIAgent, AddWorkflow | Hosting, and below |
The examples on this page share one helper for creating a chat client:
using Azure.AI.OpenAI;using Azure.Identity;using Microsoft.Extensions.AI;
public static class Models{ public static IChatClient ChatClient() => new AzureOpenAIClient( new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!), new DefaultAzureCredential()) .GetChatClient(Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT") ?? "gpt-6-luna") .AsIChatClient();}Table of Contents
Section titled “Table of Contents”- Agent2Agent (A2A) Protocol - .NET
- Graph-Based Workflows - .NET
- Declarative Agents with .NET
- OpenTelemetry Integration - .NET
- Content Safety - .NET
- Dependency Injection Patterns
- Best Practices
Agent2Agent (A2A) Protocol - .NET
Section titled “Agent2Agent (A2A) Protocol - .NET”A2A lets agents on different frameworks call each other over HTTP. In the framework a remote A2A agent is just another AIAgent (await new A2ACardResolver(url, http).GetAIAgentAsync(http)), so it can sit in a workflow, be wrapped with middleware, or become a tool with AsAIFunction(). Any AIAgent can be published with AddA2AServer and MapA2AJsonRpc / MapA2AHttpJson; publish its agent card as well with MapWellKnownAgentCard, because the server does not do it for you and clients discover agents from the card. A complete server and client, both run, are on the hosting page. Earlier versions of this page showed a server without a card, which a card-resolving client cannot find.
For a typed contract over A2A, which carries messages rather than typed calls, serialise the request into the message and ask the remote side for JSON; against a local agent, RunAsync<T> gives you the same safety directly.
Graph-Based Workflows - .NET
Section titled “Graph-Based Workflows - .NET”Workflows are typed graphs of executors joined by edges, run in supersteps. The workflows page covers them in full, with run examples for each feature:
- Executors:
Executor<TIn, TOut>, function executors, multi-handler executors and the[MessageHandler]source generator. - Edges and routing: conditions, switch, fan-out and fan-in, multi-selection.
- Shared state, events and errors.
- Human input with request ports and checkpointing, including resuming in another process.
- Sub-workflows, agents in workflows and workflows as agents.
Human-in-the-loop
Section titled “Human-in-the-loop”A RequestPort is a node whose input leaves the workflow as a RequestInfoEvent; the caller answers with request.CreateResponse(value) and the run continues from the port. With a durable checkpoint store the answer can arrive days later in another process, and agent tool approvals inside workflows surface the same way. See human input with request ports, and HostedWorkflowState for doing it over HTTP. For tool-level approval inside a single agent, wrap the tool in ApprovalRequiredAIFunction; see the comprehensive guide.
The prebuilt multi-agent patterns (sequential, concurrent, group chat, handoff, Magentic) are on the orchestrations page. Two behaviours that catch people coming from Python: there is no superstep limit, so every cycle needs its own exit, and agent nodes only start when the run receives a TurnToken.
Declarative Agents with .NET
Section titled “Declarative Agents with .NET”Microsoft.Agents.AI.Declarative (release candidate) builds agents from a YAML definition, so instructions, model options and output schema can live in configuration rather than code.
dotnet add package Microsoft.Agents.AI.Declarative --prereleaseYAML definition
Section titled “YAML definition”kind: Promptname: CustomerServiceAgentdescription: Handles customer enquiriesinstructions: | You are a helpful customer service agent. Always be polite and professional.model: options: temperature: 0.7 topP: 0.95outputSchema: properties: category: type: string required: true description: billing, technical or general answer: type: string required: true description: The reply to the customer.Loading the definition
Section titled “Loading the definition”using Microsoft.Agents.AI;using Microsoft.Extensions.AI;
public static class DeclarativeAgents{ public static async Task<AIAgent> LoadAsync(IChatClient chatClient, string path) { var factory = new ChatClientPromptAgentFactory(chatClient); string yaml = await File.ReadAllTextAsync(path); return await factory.CreateFromYamlAsync(yaml); }
public static async Task RunAsync() { AIAgent agent = await LoadAsync(Models.ChatClient(), "agents/customer-service.yaml"); Console.WriteLine(await agent.RunAsync("My invoice is wrong.")); }}The model is the chat client you pass in; the YAML sets the options. With the definition above, the request carries temperature 0.7, top_p 0.95, the instructions as the system prompt and a JSON schema built from outputSchema, so the reply is a JSON object with category and answer. Workflows have a declarative form too, covered on the workflows page.
Strongly-typed configuration with the options pattern
Section titled “Strongly-typed configuration with the options pattern”When you would rather keep agent settings in appsettings.json, bind them with the ordinary .NET options pattern and build the agent from them. Nothing here is framework-specific, which is the point.
{ "Agents": { "Support": { "Name": "support", "Instructions": "You are a helpful customer service agent.", "Temperature": 0.7, "MaxOutputTokens": 800 } }}using Microsoft.Agents.AI;using Microsoft.Agents.AI.Hosting;using Microsoft.Extensions.AI;using Microsoft.Extensions.Options;
public sealed class AgentSettings{ public required string Name { get; init; } public required string Instructions { get; init; } public float Temperature { get; init; } = 0.7f; public int MaxOutputTokens { get; init; } = 1000;}
public static class ConfiguredAgentRegistration{ public static void AddConfiguredSupportAgent(this IHostApplicationBuilder builder) { builder.Services.AddOptions<AgentSettings>() .Bind(builder.Configuration.GetSection("Agents:Support")) .ValidateDataAnnotations() .ValidateOnStart();
builder.AddAIAgent("support", (sp, name) => { AgentSettings settings = sp.GetRequiredService<IOptions<AgentSettings>>().Value; return new ChatClientAgent(sp.GetRequiredService<IChatClient>(), new ChatClientAgentOptions { Name = name, ChatOptions = new ChatOptions { Instructions = settings.Instructions, Temperature = settings.Temperature, MaxOutputTokens = settings.MaxOutputTokens, }, }); }); }}OpenTelemetry Integration - .NET
Section titled “OpenTelemetry Integration - .NET”Wrap an agent with .AsBuilder().UseOpenTelemetry(sourceName) and subscribe to that source with AddSource and AddMeter; workflows have WorkflowBuilder.WithOpenTelemetry(), whose spans go to Microsoft.Agents.AI.Workflows unless you pass your own ActivitySource. The spans follow the GenAI conventions (invoke_agent, chat, execute_tool) and carry token usage, and the meters record gen_ai.client.operation.duration and gen_ai.client.token.usage. Prompt text is excluded unless you set EnableSensitiveData. The observability page lists every span and attribute and has set-ups for OTLP, the Aspire dashboard and Azure Monitor, and your own business metrics.
Content Safety - .NET
Section titled “Content Safety - .NET”There is no Microsoft.Agents.AI.Safety namespace and no contentSafety: option on ChatClientAgent. Content safety is middleware you write over Azure.AI.ContentSafety, attached with agent.AsBuilder().Use(...) or written as a DelegatingAIAgent. The full input-and-output screening example is on the enterprise page, and middleware in general on the middleware page.
dotnet add package Azure.AI.ContentSafetydotnet add package Azure.AI.TextAnalytics # for PII redactionA reusable safety wrapper
Section titled “A reusable safety wrapper”The middleware can also be written as a class deriving from DelegatingAIAgent, which is easier to test and to register in DI.
using Azure.AI.ContentSafety;using Microsoft.Agents.AI;using Microsoft.Extensions.AI;using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
public sealed class ContentSafetyAgent(AIAgent inner, ContentSafetyClient safety, int maxSeverity = 2) : DelegatingAIAgent(inner){ protected override async Task<AgentResponse> RunCoreAsync( IEnumerable<ChatMessage> messages, AgentSession? session, AgentRunOptions? options, CancellationToken cancellationToken) { var text = string.Join("\n", messages.Where(m => m.Role == ChatRole.User).Select(m => m.Text)); var analysis = await safety.AnalyzeTextAsync(new AnalyzeTextOptions(text), cancellationToken); if (analysis.Value.CategoriesAnalysis.Any(c => c.Severity > maxSeverity)) { return new AgentResponse(new ChatMessage(ChatRole.Assistant, "I can't help with that request.")); }
return await base.RunCoreAsync(messages, session, options, cancellationToken); }}
// AIAgent safe = new ContentSafetyAgent(agent, new ContentSafetyClient(endpoint, credential));Override RunCoreStreamingAsync as well if callers stream; otherwise streaming calls bypass the check.
PII detection
Section titled “PII detection”Azure AI Language (Azure.AI.TextAnalytics) redacts PII; run it on user messages before the model sees them.
using Azure.AI.TextAnalytics;using Microsoft.Agents.AI;using Microsoft.Extensions.AI;using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
public static class PiiRedaction{ public static AIAgent WithPiiRedaction(this AIAgent agent, TextAnalyticsClient language) => agent.AsBuilder() .Use( runFunc: async (messages, session, options, inner, ct) => { var redacted = new List<ChatMessage>(); foreach (ChatMessage message in messages) { if (message.Role == ChatRole.User && !string.IsNullOrWhiteSpace(message.Text)) { PiiEntityCollection entities = await language.RecognizePiiEntitiesAsync(message.Text, cancellationToken: ct); redacted.Add(new ChatMessage(ChatRole.User, entities.RedactedText)); } else { redacted.Add(message); } } return await inner.RunAsync(redacted, session, options, ct); }, runStreamingFunc: null) .Build();}Dependency Injection Patterns
Section titled “Dependency Injection Patterns”Registering agents and workflows
Section titled “Registering agents and workflows”Microsoft.Agents.AI.Hosting registers agents (and workflows) as keyed AIAgent services. A workflow registered with AddWorkflow(...).AddAsAIAgent() is callable exactly like an agent, and both can then be mapped to OpenAI-compatible, A2A or AG-UI endpoints (see the hosting page).
using Microsoft.Agents.AI;using Microsoft.Agents.AI.Hosting;using Microsoft.Agents.AI.Workflows;using Microsoft.AspNetCore.Mvc;using Microsoft.Extensions.AI;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddChatClient(Models.ChatClient());
builder.AddAIAgent("researcher", "You research topics thoroughly.");builder.AddAIAgent("writer", "You turn research into a short, clear brief.");
builder.AddWorkflow("research-brief", (sp, name) => AgentWorkflowBuilder.BuildSequential( name, [sp.GetRequiredKeyedService<AIAgent>("researcher"), sp.GetRequiredKeyedService<AIAgent>("writer")])) .AddAsAIAgent();
builder.AddOpenAIResponses();
var app = builder.Build();
app.MapPost("/brief", async (BriefRequest request, [FromKeyedServices("research-brief")] AIAgent workflow) => Results.Ok(new { brief = (await workflow.RunAsync(request.Topic)).Text }));
app.MapOpenAIResponses(); // POST /v1/responses with "agent": {"name": "researcher" | "writer" | "research-brief"}app.Run();
public record BriefRequest(string Topic);The shared Responses route selects the agent with agent.name in the request body (or metadata.entity_id); the model field does not select anything. Earlier versions of this page said otherwise.
Lifetimes
Section titled “Lifetimes”- Register the
IChatClientas a singleton; it owns the HTTP connection pool. - Agents are safe to share as singletons (the default for
AddAIAgent); keep per-user state in sessions. - Use
ServiceLifetime.ScopedonAddAIAgentonly when the agent depends on scoped services (for example a per-requestDbContextused by its tools). - Build workflows per run (a factory, or
AddWorkflow’s delegate) in services that run several at once: oneWorkflowinstance can only be in one run at a time.
Best Practices
Section titled “Best Practices”1. Async all the way
Section titled “1. Async all the way”- Use
async/awaitthroughout; never block on.Resultor.Wait(). - Flow
CancellationTokens from the request intoRunAsyncand into workflow runs.
2. Dependency injection
Section titled “2. Dependency injection”- One
IChatClientper model deployment, registered once. - Resolve agents as
AIAgent(keyed by name) so implementations can change without touching callers. - Bind configuration with
IOptions<T>and validate it on start-up.
3. Type safety
Section titled “3. Type safety”- Use records for workflow messages and structured output.
- Prefer
RunAsync<T>over parsing JSON out ofresponse.Text.
4. Error handling
Section titled “4. Error handling”- Catch
ClientResultException(OpenAI SDK) orRequestFailedException(Azure SDK) around model calls; add retries withMicrosoft.Extensions.Http.Resilienceon theHttpClient(production guide). - Workflow executors do not throw out of the run: watch for
WorkflowErrorEventandExecutorFailedEvent.
5. Performance
Section titled “5. Performance”- Stream (
RunStreamingAsync) for user-facing latency. - Use
AgentWorkflowBuilder.BuildConcurrentor fan-out edges for independent work. - Keep histories bounded with compaction or a chat reducer.