Install
dotnet add package Microsoft.Agents.AI --version 1.28.0dotnet add package Microsoft.Agents.AI.OpenAI # AsAIAgent() for OpenAI / Azure OpenAIThe .NET agent SDK (Microsoft.Agents.AI): ChatClientAgent and providers, tools, MCP, middleware, sessions and memory, graph workflows, multi-agent orchestrations, hosting over OpenAI, A2A and AG-UI, observability, testing and evaluation.
The .NET SDK that succeeds Semantic Kernel’s agent features and AutoGen (generally available since 2 April 2026). Build C# agents with ChatClientAgent on any IChatClient, compose them in graph workflows and prebuilt orchestrations, serve them over OpenAI-compatible, A2A and AG-UI endpoints, and use Azure services through managed identity.
Install
dotnet add package Microsoft.Agents.AI --version 1.28.0dotnet add package Microsoft.Agents.AI.OpenAI # AsAIAgent() for OpenAI / Azure OpenAIVersion
Microsoft.Agents.AI 1.28.0 (checked 2026-11-19) · .NET 8.0+, also .NET Standard 2.0 / .NET Framework 4.7.2
Best for
Enterprise .NET agents, Azure-native deployments, ASP.NET Core hosting, multi-agent workflows.
In sidebar order.
The Microsoft.Agents.AI.* packages release together under the core’s version number, except the durable ones; preview, alpha and release-candidate builds carry a suffix, so install them with --prerelease. Status as listed on NuGet on 2026-11-19.
| Package | Status | What it adds | Covered on |
|---|---|---|---|
Microsoft.Agents.AI, .Abstractions | stable | AIAgent, ChatClientAgent, sessions, context providers, compaction, evaluation | Providers |
Microsoft.Agents.AI.OpenAI | stable | AsAIAgent() on the OpenAI SDK’s ChatClient and ResponsesClient | Providers |
Microsoft.Agents.AI.Anthropic | stable | AsAIAgent() on AnthropicClient | Providers |
Microsoft.Agents.AI.GitHub.Copilot | stable | GitHubCopilotAgent | Providers |
Microsoft.Agents.AI.Harness | stable | HarnessAgent | Comprehensive guide |
Microsoft.Agents.AI.Workflows, .Workflows.Generators | stable | Graph workflows and orchestrations; the [MessageHandler] source generator | Workflows |
Microsoft.Agents.AI.Workflows.Declarative, .Workflows.Declarative.Mcp | stable | YAML workflows; MCP servers inside them | Workflows |
Microsoft.Agents.AI.Declarative | release candidate | YAML agents | Feature tour |
Microsoft.Agents.AI.Foundry | preview | Foundry models and agents, FoundryAITool, Foundry memory and evaluators | Providers |
Microsoft.Agents.AI.A2A | preview | A2AAgent client | Hosting |
Microsoft.Agents.AI.CopilotStudio | preview | CopilotStudioAgent | Providers |
Microsoft.Agents.AI.Mcp | alpha | MCP tasks and MCP-served skills | MCP |
Microsoft.Agents.AI.CosmosNoSql | preview | CosmosChatHistoryProvider | Sessions and memory |
Microsoft.Agents.AI.Valkey | alpha | Valkey (Redis-compatible) history and search | Sessions and memory |
Microsoft.Agents.AI.Tools.Shell | preview | Local and Docker shell tools | Tools |
Microsoft.Agents.AI.LocalCodeAct, .Hyperlight | preview | CodeAct in a local Python process or a Hyperlight micro-VM | Tools |
Microsoft.Agents.AI.AgentHooks | alpha | AGENT-HOOKS policy interception | Middleware |
Microsoft.Agents.AI.Purview | release candidate | Microsoft Purview DLP policies | Production guide |
Microsoft.Agents.AI.Hosting, .Hosting.AspNetCore, .Hosting.AzureStorage | preview | AddAIAgent, AddWorkflow, session stores, claims-based isolation | Hosting |
Microsoft.Agents.AI.Hosting.OpenAI | alpha | OpenAI Responses, Conversations and Chat Completions endpoints | Hosting |
Microsoft.Agents.AI.Hosting.A2A.AspNetCore | preview | A2A server | Hosting |
Microsoft.Agents.AI.Hosting.AGUI.AspNetCore | preview | AG-UI server | Hosting |
AGUI.Client | stable, from the AG-UI project | AG-UI client (AGUIChatClient); replaces Microsoft.Agents.AI.AGUI, which is no longer updated | Hosting |
Microsoft.Agents.AI.DevUI | preview | Browser UI for development | Hosting |
Microsoft.Agents.AI.Foundry.Hosting | preview | Your agent as a Foundry hosted agent | Hosting |
Microsoft.Agents.AI.Hosting.AzureFunctions, .DurableTask | preview, released separately | Durable agents and workflows; now built in the agent-framework-durable-extension repository, on their own version line, separate from the core’s | Hosting |
Microsoft.Agents.AI.AzureAI.Persistent | preview, obsolete | The classic Azure AI Agents service; every extension is marked [Obsolete], use Foundry agents instead | Providers |
Other models (Ollama, Bedrock, Gemini and so on) plug in through any Microsoft.Extensions.AI IChatClient implementation; there are no separate Microsoft.Agents.AI.* packages for them. MCP clients and servers come from the official C# SDK, ModelContextProtocol.
using Azure.AI.OpenAI;using Azure.Identity;using Microsoft.Agents.AI;using OpenAI.Chat;
var client = new AzureOpenAIClient( new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!), new DefaultAzureCredential());
// AsAIAgent (Microsoft.Agents.AI.OpenAI) wraps the OpenAI SDK ChatClient in a ChatClientAgent.AIAgent agent = client .GetChatClient("gpt-6.1-sol") .AsAIAgent(instructions: "You are a helpful assistant.");
AgentSession session = await agent.CreateSessionAsync(); // multi-turn statevar response = await agent.RunAsync("What is 15 + 27?", session);Console.WriteLine(response.Text);If you already have an IChatClient (from Microsoft.Extensions.AI), construct the agent directly: new ChatClientAgent(chatClient, instructions: "..."). Earlier previews used AgentThread / GetNewThread() and CreateAIAgent(...); the GA names are AgentSession / CreateSessionAsync() and AsAIAgent(...).
Ready? Start Zero → Hero Step 1 →
| Date | Version | Changes |
|---|---|---|
| 2026-10-25 | 1.26.0 | Expanded the .NET guide from 9 to 19 pages: new providers, tools, MCP, middleware, sessions and memory, workflows, orchestrations, hosting, observability and testing-and-evaluation pages, each compiled against 1.26.0. The comprehensive guide now summarises those topics and links to them; the feature tour and streaming-server page point to their new homes. Index rebuilt: a page map in sidebar order, Zero → Hero and topic links repointed, and a package table checked on NuGet (adds .Mcp, .Valkey, .Tools.Shell, .LocalCodeAct, .Hyperlight, .AgentHooks, .Purview, .Declarative, AGUI.Client and the separately released durable packages; marks .AzureAI.Persistent obsolete). |
| 2026-10-25 | 1.26.0 | Rebuilt the C# blocks against 1.26.0: 59 of 78 build on their own and the rest fail identically against 1.25.0 because they use types from neighbouring blocks or packages outside the test project (the GitHub Copilot block was not built). Production guide: custom AgentSessionStores must now implement DeleteSessionAsync; added MapAGUIServer with a per-request agent selector. DockerShellExecutorOptions.ExtraRunArgs is now UnsafeExtraRunArgs (not used in this guide). |
| 2026-10-25 | 1.25.0 | Re-compiled every C# block on the .NET and cross-language pages against 1.25.0 (75 of 77 build; the Semantic Kernel interop block builds with Microsoft.SemanticKernel 1.81.0 added; the GitHub Copilot block was not built). Noted the deprecation of the classic Persistent Agents service. Added sidebar order and root-absolute links. |
| 2026-10-21 | 1.25.0 | Added HarnessAgent, Anthropic and GitHub Copilot agents, evaluation and DevUI to the comprehensive guide; rewrote the Azure RBAC, advanced and production pages (Foundry hosted agents, durable Azure Functions agents, prompt-injection defence, evaluation in CI). |
| 2026-10-21 | 1.25.0 | Version sweep. Install card pins and version card now read Microsoft.Agents.AI from the site’s version data. Minimal example fixed (GetChatClient(...) returns an OpenAI SDK client, not an IChatClient — use AsAIAgent); thread API updated to AgentSession / CreateSessionAsync across the .NET pages. Comprehensive guide, recipes and feature tour rewritten against the real hosting, DI and workflow APIs; every C# block compiled against 1.25.0 and the workflow examples run against a stub chat client. |
| 2026-09-08 | 1.1.0 | Consistency sweep. Version card moved 1.0.1 → 1.1.0 to match the Latest: stamps already carried by the .NET pages; those stamps now name the package (Microsoft.Agents.AI). No package installation or symbol verification performed. |
| 2026-04-21 | 1.1.0 | Index redesigned with Zero → Hero + Jump-to-topic grid. |
| 2026-04-10 | 1.1.0 | First minor release after GA (NuGet). |
| 2026-04-02 | 1.0.0 | GA on NuGet. |
| 2025-10-01 | 1.0.0-preview.251001.1 | First public preview on NuGet. |