# Microsoft 365 代理 SDK (.NET) ## 概述使用具有 ASP.NET Core 托管、代理路由和基于 MSAL 的身份验证的 Microsoft.Agents SDK 为 Microsoft 365、Teams 和 Copilot Studio 构建企业代理。 ## 实施前 * 使用 microsoft-docs MCP 验证 AddAgent、AgentApplication 和身份验证选项的最新 API。 * 在 NuGet 中确认您计划使用的 Microsoft.Agents.* 包的包版本。 ## 安装 dotnet 添加包 Microsoft.Agents.Hosting.AspNetCore dotnet 添加包 Microsoft.Agents.Authentication.Msal dotnet 添加包 Microsoft.Agents.Storage dotnet 添加包 Microsoft.Agents.CopilotStudio.Client dotnet 添加包 Microsoft.Identity.Client.Extensions.Msal ## 配置（appsettings.json） { “令牌验证”：{ “启用”：正确， “观众”：[ “{{客户端ID}}” ], “租户Id”：“{{租户Id}}” }, “代理应用程序”：{ “开始打字定时器”：假， “删除收件人提及”：假， “NormalizeMentions”：假 }, “连接”：{ “服务连接”：{ “设置”：{ "AuthType": "客户端密码", "ClientId": "{{ClientId}}", "ClientSecret": "{{ClientSecret}}", "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId}}", “范围”：[ “https://api.botframework.com/.default” ] } } }, “连接地图”：[ { “服务网址”：“*”， “连接”：“服务连接” } ], “CopilotStudioClientSettings”：{ "DirectConnectUrl": "", "环境ID": "", "模式名称": "", "租户ID": "", "AppClientId": "", “AppClientSecret”：“” } } ## 核心工作流程：ASP.NET Core 代理主机使用 Microsoft.Agents.Builder；使用 Microsoft.Agents.Hosting.AspNetCore；使用 Microsoft.Agents.Storage；使用 Microsoft.AspNetCore.Builder；使用 Microsoft.AspNetCore.Http；使用 Microsoft.Extensions.DependencyInjection；使用 Microsoft.Extensions.Hosting； var builder = WebApplication.CreateBuilder(args); builder.Services.AddHttpClient(); 生成器.AddAgentApplicationOptions(); builder.AddAgent(); builder.Services.AddSingleton(); builder.Services.AddControllers(); builder.Services.AddAgentAspNetAuthentication(builder.Configuration); WebApplication 应用程序 = builder.Build(); app.UseAuthentication(); 应用程序.UseAuthorization(); app.MapGet("/", () => "Microsoft Agents SDK 示例"); var传入路由 = app.MapPost("/api/messages", 异步（HttpRequest 请求、HttpResponse 响应、IAgentHttpAdapter 适配器、IAgent 代理、CancellationToken ct）=> { 等待适配器.ProcessAsync（请求，响应，代理，ct）； }); if (!app.Environment.IsDevelopment()) { 传入Route.RequireAuthorization(); } 否则 { app.Urls.Add("http://localhost:3978"); } 应用程序.运行(); ## Agent应用程序路由使用 Microsoft.Agents.Builder；使用 Microsoft.Agents.Builder.App；使用 Microsoft.Agents.Builder.State；使用 Microsoft.Agents.Core.Models；使用系统；使用系统线程；使用 System.Threading.Tasks；公共密封类 MyAgent ：AgentApplication { 公共 MyAgent(AgentApplicationOptions 选项) : 基(选项) { OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeAsync); OnActivity(ActivityTypes.Message, OnMessageAsync, 排名：RouteRank.Last); OnTurnError(OnTurnErrorAsync); } 私有静态异步任务WelcomeAsync（ITurnContextturnContext，ITurnStateturnState，CancellationTokenct） { foreach（ChannelAccount成员依次Context.Activity.MembersAdded） { if (member.Id!=turnContext.Activity.Recipient.Id) { 等待turnContext.SendActivityAsync（ MessageFactory.Text("欢迎来到代理。"), CT）； } } } 私有静态异步任务OnMessageAsync（ITurnContextturnContext，ITurnStateturnState，CancellationTokenct） { 等待turnContext.SendActivityAsync（ MessageFactory.Text($"你说：{turnContext.Activity.Text}"), CT）； } 私有静态异步任务 OnTurnErrorAsync( ITurnContext 转上下文， ITurnState 转动状态，异常异常，取消令牌 ct) { 等待turnState.Conversation.DeleteStateAsync(turnContext, ct); var endOfConversation = Activity.CreateEndOfConversationActivity(); endOfConversation.Code = EndOfConversationCodes.Error; endOfConversation.Text = 异常.Message; 等待turnContext.SendActivityAsync(endOfConversation, ct); } } ## Copilot Studio 直接到引擎客户端 ### DelegatingHandler 用于令牌获取（交互流程）使用 System.Net.Http.Headers；使用 Microsoft.Agents.CopilotStudio.Client；使用 Microsoft.Identity.Client；内部密封类 AddTokenHandler ：DelegatingHandler { 私有只读 SampleConnectionSettings _settings； public AddTokenHandler（SampleConnectionSettings 设置）：base（new HttpClientHandler（）） { _settings=设置； } 受保护的覆盖异步任务 SendAsync( HttpRequest消息请求， CancellationToken（取消令牌） { if (request.Headers.Authorization 为 null) { string[] 范围 = [CopilotClient.ScopeFromSettings(_settings)]; IPublicClientApplication 应用程序 = PublicClientApplicationBuilder .Create(_settings.AppClientId) .WithAuthority(AadAuthorityAudience.AzureAdMyOrg) .WithTenantId(_settings.TenantId) .WithRedirectUri("http://localhost") .Build(); 验证结果 authResponse；尝试 { var account = (await app.GetAccountsAsync()).FirstOrDefault(); authResponse = 等待 app.AcquireTokenSilent(scopes, account).ExecuteAsync(cancellationToken); } 捕获（MsalUiRequiredException） { authResponse = 等待 app.AcquireTokenInteractive(scopes).ExecuteAsync(cancellationToken); } request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", authResponse.AccessToken); } 返回等待base.SendAsync（请求，cancelToken）； } } ### 带有 CopilotClient 的控制台主机使用 Microsoft.Agents.CopilotStudio.Client；使用 Microsoft.Extensions.DependencyInjection；使用 Microsoft.Extensions.Hosting； HostApplicationBuilder 构建器 = Host.CreateApplicationBuilder(args); var 设置 = 新 SampleConnectionSettings( builder.Configuration.GetSection("CopilotStudioClientSettings")); builder.Services.AddHttpClient("mcs").ConfigurePrimaryHttpMessageHandler(() => { 返回新的 AddTokenHandler(设置); }); 建造者服务 .AddSingleton(设置) .AddTransient(sp => { var logger = sp.GetRequiredService().CreateLogger(); 返回新 CopilotClient(设置, sp.GetRequiredService(), 记录器, "mcs"); }); IHost 主机 = builder.Build(); var client = host.Services.GetRequiredService(); 等待foreach（client.StartConversationAsync（emitStartConversationEvent：true）中的var活动） { Console.WriteLine(活动.类型); } 等待foreach（client.AskQuestionAsync（“Hello！”，null）中的var活动） { Console.WriteLine(活动.类型); } ## 最佳实践 1. 使用AgentApplication子类来集中路由和错误处理。 2、MemoryStorage仅用于开发；在生产中使用持久存储。 3. 在生产中启用 TokenValidation 并要求在 /api/messages 上进行授权。 4. 在配置提供程序中保留身份验证机密（Key Vault、托管身份、环境变量）。 5. 重用 IHttpClientFactory 中的 HttpClient 并缓存 MSAL 令牌。 6. 首选异步处理程序并将 CancellationToken 传递给 SDK 调用。 ## 参考文件文件|内容 ---|--- 参考文献/acceptance-criteria.md |导入路径、托管管道、Copilot Studio 客户端模式、反模式 ## 参考链接资源 |网址 ---|--- Microsoft 365 代理 SDK | 添加代理 API | 代理应用程序API | 身份验证配置选项 | Copilot Studio 集成 | GitHub 示例 | ## 何时使用此技能适用于执行概述中描述的工作流程或操作。

M365 特工 Dotnet

包含技能