Build Microsoft 365 Agents with .NET SDK

Microsoft 365 Agents SDK (.NET) covers building enterprise agents for Microsoft 365, Teams and Copilot Studio using the Microsoft.Agents SDK, with ASP.NET Core hosting, AgentApplication-based routing, and MSAL-based authentication. Before implementation it recommends using the microsoft-docs MCP to verify the latest AddAgent, AgentApplication and authentication APIs, and confirming NuGet package versions.

Installation pulls in the SDK's hosting, auth and storage packages:

dotnet add package Microsoft.Agents.Hosting.AspNetCore
dotnet add package Microsoft.Agents.Authentication.Msal
dotnet add package Microsoft.Agents.Storage
dotnet add package Microsoft.Agents.CopilotStudio.Client
dotnet add package Microsoft.Identity.Client.Extensions.Msal

Configuration in appsettings.json sets TokenValidation (audiences and tenant ID), AgentApplication behavior flags (typing timer, mention handling), a ServiceConnection with ClientSecret auth against https://login.microsoftonline.com/{{TenantId}} scoped to https://api.botframework.com/.default, a ConnectionsMap routing any service URL to that connection, and separate CopilotStudioClientSettings for direct-to-engine access.

The core ASP.NET Core host wires the agent with builder.AddAgentApplicationOptions() and builder.AddAgent<MyAgent>(), registers MemoryStorage as the IStorage implementation, adds agent authentication via AddAgentAspNetAuthentication, and exposes POST /api/messages, which hands the request to IAgentHttpAdapter.ProcessAsync and requires authorization outside development. The AgentApplication subclass pattern centralizes routing: OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeAsync) sends a welcome message to new members, OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last) echoes back user text, and OnTurnError(OnTurnErrorAsync) clears conversation state and sends an EndOfConversationActivity with the exception message on failure.

For Copilot Studio's direct-to-engine client, a DelegatingHandler named AddTokenHandler acquires an MSAL token - trying AcquireTokenSilent against a cached account first, falling back to AcquireTokenInteractive on MsalUiRequiredException - and attaches it as a Bearer header before the request proceeds. A console host example registers a named HttpClient using that handler, constructs a CopilotClient, and drives a conversation with StartConversationAsync followed by AskQuestionAsync("Hello!", null), printing each returned activity's type.

Its best practices: use AgentApplication subclasses to centralize routing and error handling; use MemoryStorage only in development and persisted storage in production; enable TokenValidation and require authorization on /api/messages in production; keep auth secrets in a configuration provider such as Key Vault, managed identity or environment variables rather than in code; reuse HttpClient from IHttpClientFactory and cache MSAL tokens; and prefer async handlers that pass CancellationToken through to every SDK call.

Use it to build multichannel Microsoft 365, Teams or Copilot Studio agents in .NET with ASP.NET Core hosting and MSAL authentication. A bundled reference file, references/acceptance-criteria.md, documents import paths, the hosting pipeline, Copilot Studio client patterns and anti-patterns to check against.

It suits .NET developers building enterprise-grade agents that need to run across Teams, Microsoft 365 and Copilot Studio with proper authentication and production-grade state storage rather than an in-memory prototype.