M365 Agents Dotnet

by microsoft354361d83247MITListed Oct 8, 2026Updated Oct 8, 2026

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".

FeaturedInstructions onlySoftware DevelopmentAI & Agents
AI-generated overview

Guides building Microsoft 365 agents in .NET with ASP.NET Core hosting, AgentApplication routing, and MSAL authentication.

What it does
This skill provides reference instructions and code samples for building multichannel agents with the Microsoft 365 Agents SDK for .NET. It covers NuGet package installation, appsettings.json configuration, an ASP.NET Core agent host with message routing, AgentApplication routing and error handling, and a Copilot Studio direct-to-engine client with MSAL token acquisition. It produces guidance and sample code rather than runnable scripts.
When to use it
Use it when implementing a Microsoft 365, Teams, or Copilot Studio agent in .NET and you need setup, hosting, routing, or authentication patterns. It is also useful when wiring Copilot Studio client conversations or configuring token validation and connections.
Requirements
Requires the .NET SDK and NuGet packages such as Microsoft.Agents.Hosting.AspNetCore, Microsoft.Agents.Authentication.Msal, Microsoft.Agents.Storage, Microsoft.Agents.CopilotStudio.Client, and Microsoft.Identity.Client.Extensions.Msal. Needs Microsoft 365 or Copilot Studio tenant credentials (client ID, secret, tenant ID) and network access to Microsoft identity and Bot Framework endpoints. Ships no scripts; instructions only.

Microsoft 365 Agents SDK (.NET)

Overview

Build 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.

Before implementation

  • Use the microsoft-docs MCP to verify the latest APIs for AddAgent, AgentApplication, and authentication options.
  • Confirm package versions in NuGet for the Microsoft.Agents.* packages you plan to use.

Installation

bash
dotnet add package Microsoft.Agents.Hosting.AspNetCoredotnet add package Microsoft.Agents.Authentication.Msaldotnet add package Microsoft.Agents.Storagedotnet add package Microsoft.Agents.CopilotStudio.Clientdotnet add package Microsoft.Identity.Client.Extensions.Msal

Configuration (appsettings.json)

json
{  "TokenValidation": {    "Enabled": true,    "Audiences": ["{{ClientId}}"],    "TenantId": "{{TenantId}}"  },  "AgentApplication": {    "StartTypingTimer": false,    "RemoveRecipientMention": false,    "NormalizeMentions": false  },  "Connections": {    "ServiceConnection": {      "Settings": {        "AuthType": "ClientSecret",        "ClientId": "{{ClientId}}",        "ClientSecret": "{{ClientSecret}}",        "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}",        "Scopes": ["https://api.botframework.com/.default"]      }    }  },  "ConnectionsMap": [    {      "ServiceUrl": "*",      "Connection": "ServiceConnection"    }  ],  "CopilotStudioClientSettings": {    "DirectConnectUrl": "",    "EnvironmentId": "",    "SchemaName": "",    "TenantId": "",    "AppClientId": "",    "AppClientSecret": ""  }}

Core Workflow: ASP.NET Core agent host

csharp
using Microsoft.Agents.Builder;using Microsoft.Agents.Hosting.AspNetCore;using Microsoft.Agents.Storage;using Microsoft.AspNetCore.Builder;using Microsoft.AspNetCore.Http;using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Hosting;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient();builder.AddAgentApplicationOptions();builder.AddAgent<MyAgent>();builder.Services.AddSingleton<IStorage, MemoryStorage>();
builder.Services.AddControllers();builder.Services.AddAgentAspNetAuthentication(builder.Configuration);
WebApplication app = builder.Build();
app.UseAuthentication();app.UseAuthorization();
app.MapGet("/", () => "Microsoft Agents SDK Sample");
var incomingRoute = app.MapPost("/api/messages",    async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken ct) =>    {        await adapter.ProcessAsync(request, response, agent, ct);    });
if (!app.Environment.IsDevelopment()){    incomingRoute.RequireAuthorization();}else{    app.Urls.Add("http://localhost:3978");}
app.Run();

AgentApplication routing

csharp
using Microsoft.Agents.Builder;using Microsoft.Agents.Builder.App;using Microsoft.Agents.Builder.State;using Microsoft.Agents.Core.Models;using System;using System.Threading;using System.Threading.Tasks;
public sealed class MyAgent : AgentApplication{    public MyAgent(AgentApplicationOptions options) : base(options)    {        OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeAsync);        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);        OnTurnError(OnTurnErrorAsync);    }
    private static async Task WelcomeAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken ct)    {        foreach (ChannelAccount member in turnContext.Activity.MembersAdded)        {            if (member.Id != turnContext.Activity.Recipient.Id)            {                await turnContext.SendActivityAsync(                    MessageFactory.Text("Welcome to the agent."),                    ct);            }        }    }
    private static async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken ct)    {        await turnContext.SendActivityAsync(            MessageFactory.Text($"You said: {turnContext.Activity.Text}"),            ct);    }
    private static async Task OnTurnErrorAsync(        ITurnContext turnContext,        ITurnState turnState,        Exception exception,        CancellationToken ct)    {        await turnState.Conversation.DeleteStateAsync(turnContext, ct);
        var endOfConversation = Activity.CreateEndOfConversationActivity();        endOfConversation.Code = EndOfConversationCodes.Error;        endOfConversation.Text = exception.Message;        await turnContext.SendActivityAsync(endOfConversation, ct);    }}

Copilot Studio direct-to-engine client

DelegatingHandler for token acquisition (interactive flow)

csharp
using System.Net.Http.Headers;using Microsoft.Agents.CopilotStudio.Client;using Microsoft.Identity.Client;
internal sealed class AddTokenHandler : DelegatingHandler{    private readonly SampleConnectionSettings _settings;
    public AddTokenHandler(SampleConnectionSettings settings) : base(new HttpClientHandler())    {        _settings = settings;    }
    protected override async Task<HttpResponseMessage> SendAsync(        HttpRequestMessage request,        CancellationToken cancellationToken)    {        if (request.Headers.Authorization is null)        {            string[] scopes = [CopilotClient.ScopeFromSettings(_settings)];
            IPublicClientApplication app = PublicClientApplicationBuilder                .Create(_settings.AppClientId)                .WithAuthority(AadAuthorityAudience.AzureAdMyOrg)                .WithTenantId(_settings.TenantId)                .WithRedirectUri("http://localhost")                .Build();
            AuthenticationResult authResponse;            try            {                var account = (await app.GetAccountsAsync()).FirstOrDefault();                authResponse = await app.AcquireTokenSilent(scopes, account).ExecuteAsync(cancellationToken);            }            catch (MsalUiRequiredException)            {                authResponse = await app.AcquireTokenInteractive(scopes).ExecuteAsync(cancellationToken);            }
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", authResponse.AccessToken);        }
        return await base.SendAsync(request, cancellationToken);    }}

Console host with CopilotClient

csharp
using Microsoft.Agents.CopilotStudio.Client;using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Hosting;
HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
var settings = new SampleConnectionSettings(    builder.Configuration.GetSection("CopilotStudioClientSettings"));
builder.Services.AddHttpClient("mcs").ConfigurePrimaryHttpMessageHandler(() =>{    return new AddTokenHandler(settings);});
builder.Services    .AddSingleton(settings)    .AddTransient<CopilotClient>(sp =>    {        var logger = sp.GetRequiredService<ILoggerFactory>().CreateLogger<CopilotClient>();        return new CopilotClient(settings, sp.GetRequiredService<IHttpClientFactory>(), logger, "mcs");    });
IHost host = builder.Build();var client = host.Services.GetRequiredService<CopilotClient>();
await foreach (var activity in client.StartConversationAsync(emitStartConversationEvent: true)){    Console.WriteLine(activity.Type);}
await foreach (var activity in client.AskQuestionAsync("Hello!", null)){    Console.WriteLine(activity.Type);}

Best Practices

  1. Use AgentApplication subclasses to centralize routing and error handling.
  2. Use MemoryStorage only for development; use persisted storage in production.
  3. Enable TokenValidation in production and require authorization on /api/messages.
  4. Keep auth secrets in configuration providers (Key Vault, managed identity, env vars).
  5. Reuse HttpClient from IHttpClientFactory and cache MSAL tokens.
  6. Prefer async handlers and pass CancellationToken to SDK calls.

Reference Links

Source and attribution

Source:microsoft/skillsin.github/plugins/azure-sdk-dotnet/skills/m365-agents-dotnetat commit354361d

License: MIT

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal