M365 Agents Dotnet

1---
2name: m365-agents-dotnet
3description: |
4  Microsoft 365 Agents SDK for .NET. Build multichannel agents for Teams/M365/Copilot Studio with ASP.NET Core hosting, AgentApplication routing, and MSAL-based auth. Triggers: "Microsoft 365 Agents SDK", "Microsoft.Agents", "AddAgentApplicationOptions", "AgentApplication", "AddAgentAspNetAuthentication", "Copilot Studio client", "IAgentHttpAdapter".
5package: Microsoft.Agents.Hosting.AspNetCore, Microsoft.Agents.Authentication.Msal, Microsoft.Agents.CopilotStudio.Client
6---
7 
8# Microsoft 365 Agents SDK (.NET)
9 
10## Overview
11Build enterprise agents for Microsoft 365, Teams, and Copilot Studio using the Microsoft.Agents SDK with ASP.NET Core hosting, agent routing, and MSAL-based authentication.
12 
13## Before implementation
14- Use the microsoft-docs MCP to verify the latest APIs for AddAgent, AgentApplication, and authentication options.
15- Confirm package versions in NuGet for the Microsoft.Agents.* packages you plan to use.
16 
17## Installation
18 
19```bash
20dotnet add package Microsoft.Agents.Hosting.AspNetCore
21dotnet add package Microsoft.Agents.Authentication.Msal
22dotnet add package Microsoft.Agents.Storage
23dotnet add package Microsoft.Agents.CopilotStudio.Client
24dotnet add package Microsoft.Identity.Client.Extensions.Msal
25```
26 
27## Configuration (appsettings.json)
28 
29```json
30{
31  "TokenValidation": {
32    "Enabled": true,
33    "Audiences": [
34      "{{ClientId}}"
35    ],
36    "TenantId": "{{TenantId}}"
37  },
38  "AgentApplication": {
39    "StartTypingTimer": false,
40    "RemoveRecipientMention": false,
41    "NormalizeMentions": false
42  },
43  "Connections": {
44    "ServiceConnection": {
45      "Settings": {
46        "AuthType": "ClientSecret",
47        "ClientId": "{{ClientId}}",
48        "ClientSecret": "{{ClientSecret}}",
49        "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}",
50        "Scopes": [
51          "https://api.botframework.com/.default"
52        ]
53      }
54    }
55  },
56  "ConnectionsMap": [
57    {
58      "ServiceUrl": "*",
59      "Connection": "ServiceConnection"
60    }
61  ],
62  "CopilotStudioClientSettings": {
63    "DirectConnectUrl": "",
64    "EnvironmentId": "",
65    "SchemaName": "",
66    "TenantId": "",
67    "AppClientId": "",
68    "AppClientSecret": ""
69  }
70}
71```
72 
73## Core Workflow: ASP.NET Core agent host
74 
75```csharp
76using Microsoft.Agents.Builder;
77using Microsoft.Agents.Hosting.AspNetCore;
78using Microsoft.Agents.Storage;
79using Microsoft.AspNetCore.Builder;
80using Microsoft.AspNetCore.Http;
81using Microsoft.Extensions.DependencyInjection;
82using Microsoft.Extensions.Hosting;
83 
84var builder = WebApplication.CreateBuilder(args);
85 
86builder.Services.AddHttpClient();
87builder.AddAgentApplicationOptions();
88builder.AddAgent<MyAgent>();
89builder.Services.AddSingleton<IStorage, MemoryStorage>();
90 
91builder.Services.AddControllers();
92builder.Services.AddAgentAspNetAuthentication(builder.Configuration);
93 
94WebApplication app = builder.Build();
95 
96app.UseAuthentication();
97app.UseAuthorization();
98 
99app.MapGet("/", () => "Microsoft Agents SDK Sample");
100 
101var incomingRoute = app.MapPost("/api/messages",
102    async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken ct) =>
103    {
104        await adapter.ProcessAsync(request, response, agent, ct);
105    });
106 
107if (!app.Environment.IsDevelopment())
108{
109    incomingRoute.RequireAuthorization();
110}
111else
112{
113    app.Urls.Add("http://localhost:3978");
114}
115 
116app.Run();
117```
118 
119## AgentApplication routing
120 
121```csharp
122using Microsoft.Agents.Builder;
123using Microsoft.Agents.Builder.App;
124using Microsoft.Agents.Builder.State;
125using Microsoft.Agents.Core.Models;
126using System;
127using System.Threading;
128using System.Threading.Tasks;
129 
130public sealed class MyAgent : AgentApplication
131{
132    public MyAgent(AgentApplicationOptions options) : base(options)
133    {
134        OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeAsync);
135        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
136        OnTurnError(OnTurnErrorAsync);
137    }
138 
139    private static async Task WelcomeAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken ct)
140    {
141        foreach (ChannelAccount member in turnContext.Activity.MembersAdded)
142        {
143            if (member.Id != turnContext.Activity.Recipient.Id)
144            {
145                await turnContext.SendActivityAsync(
146                    MessageFactory.Text("Welcome to the agent."),
147                    ct);
148            }
149        }
150    }
151 
152    private static async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken ct)
153    {
154        await turnContext.SendActivityAsync(
155            MessageFactory.Text($"You said: {turnContext.Activity.Text}"),
156            ct);
157    }
158 
159    private static async Task OnTurnErrorAsync(
160        ITurnContext turnContext,
161        ITurnState turnState,
162        Exception exception,
163        CancellationToken ct)
164    {
165        await turnState.Conversation.DeleteStateAsync(turnContext, ct);
166 
167        var endOfConversation = Activity.CreateEndOfConversationActivity();
168        endOfConversation.Code = EndOfConversationCodes.Error;
169        endOfConversation.Text = exception.Message;
170        await turnContext.SendActivityAsync(endOfConversation, ct);
171    }
172}
173```
174 
175## Copilot Studio direct-to-engine client
176 
177### DelegatingHandler for token acquisition (interactive flow)
178 
179```csharp
180using System.Net.Http.Headers;
181using Microsoft.Agents.CopilotStudio.Client;
182using Microsoft.Identity.Client;
183 
184internal sealed class AddTokenHandler : DelegatingHandler
185{
186    private readonly SampleConnectionSettings _settings;
187 
188    public AddTokenHandler(SampleConnectionSettings settings) : base(new HttpClientHandler())
189    {
190        _settings = settings;
191    }
192 
193    protected override async Task<HttpResponseMessage> SendAsync(
194        HttpRequestMessage request,
195        CancellationToken cancellationToken)
196    {
197        if (request.Headers.Authorization is null)
198        {
199            string[] scopes = [CopilotClient.ScopeFromSettings(_settings)];
200 
201            IPublicClientApplication app = PublicClientApplicationBuilder
202                .Create(_settings.AppClientId)
203                .WithAuthority(AadAuthorityAudience.AzureAdMyOrg)
204                .WithTenantId(_settings.TenantId)
205                .WithRedirectUri("http://localhost")
206                .Build();
207 
208            AuthenticationResult authResponse;
209            try
210            {
211                var account = (await app.GetAccountsAsync()).FirstOrDefault();
212                authResponse = await app.AcquireTokenSilent(scopes, account).ExecuteAsync(cancellationToken);
213            }
214            catch (MsalUiRequiredException)
215            {
216                authResponse = await app.AcquireTokenInteractive(scopes).ExecuteAsync(cancellationToken);
217            }
218 
219            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", authResponse.AccessToken);
220        }
221 
222        return await base.SendAsync(request, cancellationToken);
223    }
224}
225```
226 
227### Console host with CopilotClient
228 
229```csharp
230using Microsoft.Agents.CopilotStudio.Client;
231using Microsoft.Extensions.DependencyInjection;
232using Microsoft.Extensions.Hosting;
233 
234HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
235 
236var settings = new SampleConnectionSettings(
237    builder.Configuration.GetSection("CopilotStudioClientSettings"));
238 
239builder.Services.AddHttpClient("mcs").ConfigurePrimaryHttpMessageHandler(() =>
240{
241    return new AddTokenHandler(settings);
242});
243 
244builder.Services
245    .AddSingleton(settings)
246    .AddTransient<CopilotClient>(sp =>
247    {
248        var logger = sp.GetRequiredService<ILoggerFactory>().CreateLogger<CopilotClient>();
249        return new CopilotClient(settings, sp.GetRequiredService<IHttpClientFactory>(), logger, "mcs");
250    });
251 
252IHost host = builder.Build();
253var client = host.Services.GetRequiredService<CopilotClient>();
254 
255await foreach (var activity in client.StartConversationAsync(emitStartConversationEvent: true))
256{
257    Console.WriteLine(activity.Type);
258}
259 
260await foreach (var activity in client.AskQuestionAsync("Hello!", null))
261{
262    Console.WriteLine(activity.Type);
263}
264```
265 
266## Best Practices
267 
2681. Use AgentApplication subclasses to centralize routing and error handling.
2692. Use MemoryStorage only for development; use persisted storage in production.
2703. Enable TokenValidation in production and require authorization on /api/messages.
2714. Keep auth secrets in configuration providers (Key Vault, managed identity, env vars).
2725. Reuse HttpClient from IHttpClientFactory and cache MSAL tokens.
2736. Prefer async handlers and pass CancellationToken to SDK calls.
274 
275## Reference Files
276 
277| File | Contents |
278| --- | --- |
279| [references/acceptance-criteria.md](references/acceptance-criteria.md) | Import paths, hosting pipeline, Copilot Studio client patterns, anti-patterns |
280 
281## Reference Links
282 
283| Resource | URL |
284| --- | --- |
285| Microsoft 365 Agents SDK | https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/ |
286| AddAgent API | https://learn.microsoft.com/en-us/dotnet/api/microsoft.agents.hosting.aspnetcore.servicecollectionextensions.addagent?view=m365-agents-sdk |
287| AgentApplication API | https://learn.microsoft.com/en-us/dotnet/api/microsoft.agents.builder.app.agentapplication?view=m365-agents-sdk |
288| Auth configuration options | https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/microsoft-authentication-library-configuration-options |
289| Copilot Studio integration | https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/integrate-with-mcs |
290| GitHub samples | https://github.com/microsoft/agents |
291