[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69B8459X5NJ7HDWKH8NSC3Q":3,"skill-same:01M69B8459X5NJ7HDWKH8NSC3Q":76},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":31,"linkOnly":32,"markdownContent":33,"markdownBody":34,"frontMatter":35,"refName":36,"commitSha":37,"skillDirectory":38,"forksCount":39,"repositoryHtmlUrl":40,"repositoryHomepageUrl":41,"ownerHtmlUrl":42,"ownerBlogUrl":43,"ownerDescription":44,"updatedAt":45,"install":46,"resources":59},"01M69B8459X5NJ7HDWKH8NSC3Q","agents-sdk-dotnet",null,"Use when any code imports Microsoft.Agents.Hosting.AspNetCore, Microsoft.Agents.Builder, or related Agents SDK packages, or when the user is building, configuring, or asking questions about a Microsoft 365 Agents SDK agent in C# \u002F .NET. Trigger on questions about appsettings.json, connection configuration, AgentApplication patterns, OAuth sign-in flows, storage backends, cards, streaming, or local testing with the Agents Playground — even if no code exists yet and the user is planning or asking how to get started.","microsoft\u002FAgents","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69B7CR81D1HSNV69XDT8KAR",1109,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",[24,25,26,27,28,29,9,30],"agents sdk","sdk","dotnet","agents sdk dotnet","testing","storage","packages","2026-11-10 10:12:30",false,"---\nname: agents-sdk-dotnet\ndescription: >\n  Use when any code imports Microsoft.Agents.Hosting.AspNetCore,\n  Microsoft.Agents.Builder, or related Agents SDK packages, or when the user is\n  building, configuring, or asking questions about a Microsoft 365 Agents SDK\n  agent in C# \u002F .NET. Trigger on questions about appsettings.json,\n  connection configuration, AgentApplication patterns, OAuth sign-in flows,\n  storage backends, cards, streaming, or local testing with the Agents Playground\n  — even if no code exists yet and the user is planning or asking how to get started.\n---\n\n## Overview\n\nThe Microsoft 365 Agents SDK builds multichannel agents for Teams, Copilot Studio, and web chat.\n\n| Package | Purpose |\n|---|---|\n| `Microsoft.Agents.Hosting.AspNetCore` | ASP.NET Core hosting, auth, endpoint mapping |\n| `Microsoft.Agents.Authentication.Msal` | MSAL-based auth (client credentials, OBO) |\n| `Microsoft.Agents.Builder` | Core: AgentApplication, ITurnContext, ITurnState |\n| `Microsoft.Agents.Core` | Models, activity types, channel accounts |\n| `Microsoft.Agents.Storage` | IStorage, MemoryStorage |\n| `Microsoft.Agents.Extensions.Teams` | Teams-specific models and extensions |\n| `Microsoft.Agents.Builder.Dialogs` | Dialog system (waterfall, prompts) |\n| `Microsoft.Agents.AI` | AI-specific features |\n\n**Minimal project requires only:** `Microsoft.Agents.Hosting.AspNetCore` + `Microsoft.Agents.Authentication.Msal`. The others are transitive dependencies pulled in automatically.\n\n**Always use the latest non-beta (stable) version.** Do not use `--prerelease` unless specifically needed.\n\nRequires .NET 8+.\n\n## Azure Resources Required\n\n**Microsoft Entra App Registration**\n- `ClientId` — Application (client) ID\n- `ClientSecret` — Certificates & secrets\n- `TenantId` — Directory (tenant) ID\n\n**Azure Bot Resource**\n- Messaging endpoint: `https:\u002F\u002F\u003Cyour-host>\u002Fapi\u002Fmessages`\n- Microsoft App ID must match `ClientId`\n\nLocal dev: Set `TokenValidation:Enabled` to `false`. No Azure Bot needed until deployment.\n\n## Configuration (appsettings.json)\n\n### Single connection (most common)\n\n**appsettings.json** — no secret here (safe to commit):\n\n```json\n{\n  \"Connections\": {\n    \"ServiceConnection\": {\n      \"Settings\": {\n        \"AuthType\": \"ClientSecret\",\n        \"AuthorityEndpoint\": \"https:\u002F\u002Flogin.microsoftonline.com\u002F\u003CtenantId>\",\n        \"ClientId\": \"\u003CappId>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    }\n  },\n  \"ConnectionsMap\": [\n    {\n      \"ServiceUrl\": \"*\",\n      \"Connection\": \"ServiceConnection\"\n    }\n  ],\n  \"TokenValidation\": {\n    \"Enabled\": true,\n    \"Audiences\": [\"\u003CappId>\"],\n    \"TenantId\": \"\u003CtenantId>\"\n  }\n}\n```\n\n**appsettings.Development.json** — secret lives here (excluded via `.gitignore`):\n\n```json\n{\n  \"Connections\": {\n    \"ServiceConnection\": {\n      \"Settings\": {\n        \"ClientSecret\": \"\u003Csecret>\"\n      }\n    }\n  },\n  \"TokenValidation\": {\n    \"Enabled\": false\n  }\n}\n```\n\n### How ConnectionsMap works\n\nEach entry maps a `ServiceUrl` pattern to a named connection. The first matching entry wins.\n- `ServiceUrl: \"*\"` — matches any service URL (use as the default\u002Ffallback)\n- Other values are treated as regex patterns\n\n### Multiple connections (different identities per channel)\n\n```json\n{\n  \"Connections\": {\n    \"MainConn\": {\n      \"Settings\": {\n        \"AuthType\": \"ClientSecret\",\n        \"AuthorityEndpoint\": \"https:\u002F\u002Flogin.microsoftonline.com\u002F\u003CtenantId>\",\n        \"ClientId\": \"\u003Capp-id-1>\",\n        \"ClientSecret\": \"\u003Csecret-1>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    },\n    \"TeamsConn\": {\n      \"Settings\": {\n        \"AuthType\": \"ClientSecret\",\n        \"AuthorityEndpoint\": \"https:\u002F\u002Flogin.microsoftonline.com\u002F\u003CtenantId>\",\n        \"ClientId\": \"\u003Capp-id-2>\",\n        \"ClientSecret\": \"\u003Csecret-2>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    }\n  },\n  \"ConnectionsMap\": [\n    {\n      \"ServiceUrl\": \"https:\u002F\u002Fsmba.trafficmanager.net\u002F.*\",\n      \"Connection\": \"TeamsConn\"\n    },\n    {\n      \"ServiceUrl\": \"*\",\n      \"Connection\": \"MainConn\"\n    }\n  ]\n}\n```\n\n### Auth type variants\n\n**UserManagedIdentity** (no secret, Azure-hosted only):\n```json\n{\n  \"Connections\": {\n    \"ServiceConnection\": {\n      \"Settings\": {\n        \"AuthType\": \"UserManagedIdentity\",\n        \"ClientId\": \"\u003Cmsi-clientId>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    }\n  }\n}\n```\n\n**FederatedCredentials** (no secret, App Registration + MSI):\n```json\n{\n  \"Connections\": {\n    \"ServiceConnection\": {\n      \"Settings\": {\n        \"AuthType\": \"FederatedCredentials\",\n        \"AuthorityEndpoint\": \"https:\u002F\u002Flogin.microsoftonline.com\u002F\u003CtenantId>\",\n        \"ClientId\": \"\u003CappId>\",\n        \"FederatedClientId\": \"\u003Cmsi-clientId>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    }\n  }\n}\n```\n\n### Available connection settings fields\n\n`AuthType`, `AuthorityEndpoint`, `ClientId`, `ClientSecret`, `TenantId`, `FederatedClientId`, `Scopes`, `CertificateSubject`, `CertificateThumbprint`\n\n### Local development (disable token validation)\n\nPut in `appsettings.Development.json` (not `appsettings.json`):\n\n```json\n{\n  \"TokenValidation\": {\n    \"Enabled\": false\n  }\n}\n```\n\n## Quick Start\n\n**Prerequisite:** Copy [`AspNetExtensions.cs`](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents-for-net\u002Fblob\u002Fmain\u002Fsrc\u002Fsamples\u002FShared\u002FAspNetExtensions.cs) into your project. This provides `AddAgentAspNetAuthentication` for JWT token validation.\n\n**Program.cs:**\n\n```csharp\nusing Microsoft.Agents.Hosting.AspNetCore;\nusing Microsoft.Agents.Storage;\n\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddHttpClient();\nbuilder.AddAgent\u003CMyAgent>();\nbuilder.Services.AddSingleton\u003CIStorage, MemoryStorage>();\nbuilder.Services.AddAgentAspNetAuthentication(builder.Configuration);\n\nvar app = builder.Build();\n\napp.UseAuthentication();\napp.UseAuthorization();\napp.MapAgentRootEndpoint();\napp.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());\n\napp.Run();\n```\n\n**MyAgent.cs** — put the `AgentApplication` subclass in its own file (see [AgentApplication Patterns](#agentapplication-patterns) below for routing, state, and auth examples).\n\n**Properties\u002FlaunchSettings.json:**\n\n```json\n{\n  \"profiles\": {\n    \"MyAgent\": {\n      \"commandName\": \"Project\",\n      \"launchBrowser\": false,\n      \"environmentVariables\": {\n        \"ASPNETCORE_ENVIRONMENT\": \"Development\"\n      },\n      \"applicationUrl\": \"https:\u002F\u002Flocalhost:3979;http:\u002F\u002Flocalhost:3978\"\n    }\n  }\n}\n```\n\nRun: `dotnet run`\n\n**.gitignore** — ensure `appsettings.Development.json` is excluded (it contains secrets):\n\n```\nappsettings.Development.json\n```\n\n**Teams app manifest (if targeting Teams):** Copy the `appManifest\u002F` folder from [`Agents-for-net\u002Fsrc\u002Fsamples\u002FEmptyAgent\u002FappManifest`](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents-for-net\u002Ftree\u002Fmain\u002Fsrc\u002Fsamples\u002FEmptyAgent\u002FappManifest) into your project. Then update `manifest.json`:\n- Replace all `${{AAD_APP_CLIENT_ID}}` with your bot's Client ID\n- Set `name.short` and `name.full` to your bot's display name\n\n## Program.cs Structure\n\n### Minimal setup\n\n```csharp\nusing Microsoft.Agents.Hosting.AspNetCore;\nusing Microsoft.Agents.Storage;\n\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddHttpClient();\nbuilder.AddAgent\u003CMyAgent>();\nbuilder.Services.AddSingleton\u003CIStorage, MemoryStorage>();\nbuilder.Services.AddAgentAspNetAuthentication(builder.Configuration);\n\nvar app = builder.Build();\n\napp.UseAuthentication();\napp.UseAuthorization();\napp.MapAgentRootEndpoint();\napp.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());\n\napp.Run();\n```\n\n### With proactive messaging endpoints\n\n```csharp\napp.MapAgentProactiveEndpoints\u003CMyAgent>(requireAuth: !app.Environment.IsDevelopment());\n```\n\n### With custom routes\n\n```csharp\nvar app = builder.Build();\n\napp.UseAuthentication();\napp.UseAuthorization();\napp.MapAgentRootEndpoint();\napp.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());\napp.MapGet(\"\u002Fhealth\", () => Results.Json(new { ok = true }));\n\napp.Run();\n```\n\n### Agent class decorators\n\n```csharp\n[Agent(name: \"MyAgent\", description: \"A helpful agent\", version: \"1.0\")]\n[AgentInterface(protocol: AgentTransportProtocol.ActivityProtocol, path: \"\u002Fapi\u002Fmessages\")]\npublic class MyAgent : AgentApplication\n{\n    \u002F\u002F ...\n}\n```\n\n### Important: AddAgent vs AddAgentApplicationOptions\n\n- `builder.AddAgent\u003CT>()` — registers the agent class. **Always required.**\n- Do **not** call `AddAgentApplicationOptions()` separately unless you have a specific reason — `AddAgent` handles it.\n\n### Important: MapAgentEndpoints vs MapAgentApplicationEndpoints\n\n- `MapAgentApplicationEndpoints` — for `AgentApplication` subclasses (modern pattern)\n- `MapAgentEndpoints` — for `ActivityHandler` \u002F `TeamsActivityHandler` compat layer bots\n\nUsing the wrong one causes runtime routing failures with no clear error.\n\n## Validating Your Configuration\n\n### 1. Validate bot credentials (ClientId \u002F ClientSecret \u002F TenantId)\n\n```bash\ncurl -s -X POST \\\n  \"https:\u002F\u002Flogin.microsoftonline.com\u002F$tenantId\u002Foauth2\u002Fv2.0\u002Ftoken\" \\\n  -d \"grant_type=client_credentials\\\n&client_id=$clientId\\\n&client_secret=$clientSecret\\\n&scope=https:\u002F\u002Fapi.botframework.com\u002F.default\" \\\n  | jq '{token_type, expires_in, error, error_description}'\n```\n\nCommon errors:\n- `AADSTS700016` — `ClientId` not found in tenant (wrong ID or wrong tenant)\n- `AADSTS7000215` — invalid `ClientSecret` (expired or incorrect)\n- `AADSTS90002` — `TenantId` not found\n\n### 2. Validate the agent is running and reachable\n\n```bash\ncurl -s -o \u002Fdev\u002Fnull -w \"%{http_code}\" \\\n  -X POST http:\u002F\u002Flocalhost:3978\u002Fapi\u002Fmessages \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{}'\n```\n\n- `401` — agent is running; JWT auth rejected the empty request (expected)\n- `000` or connection refused — agent is not running or wrong port\n- `200` — agent is running with auth disabled (local dev with `TokenValidation:Enabled = false`)\n\n### 3. Validate an OAuth connection name\n\nOAuth connection names can only be tested end-to-end via:\n\n**Azure Portal → Your Bot Resource → Settings → OAuth Connection Settings → [your connection] → Test Connection**\n\n## Local Testing with Agents Playground\n\nThe Agents Playground lets you test locally without deploying to Azure.\n\n**Install:**\n```bash\nnpm install -g agentsplayground\n```\n\n**Run against an anonymous agent:**\n```bash\nagentsplayground -c emulator\n```\n\nThen start your agent separately with `dotnet run`.\n\n**With authentication:**\n```bash\nagentsplayground -c msteams \\\n  --client-id \u003Cyour-app-id> \\\n  --client-secret \u003Cyour-secret> \\\n  --tenant-id \u003Cyour-tenant-id>\n```\n\n**Channel options** (`-c`): `msteams`, `webchat`, `directline`, `emulator`, `agents`\n\nIf the playground connects but messages don't get responses, add a fallback handler to confirm:\n\n```csharp\nOnActivity(ActivityTypes.Message, async (ctx, state, ct) =>\n{\n    await ctx.SendActivityAsync($\"Echo: {ctx.Activity.Text}\", cancellationToken: ct);\n}, rank: RouteRank.Last);\n```\n\n## AgentApplication Patterns\n\n**Routing**\n```csharp\nOnMessage(\"\u002Fcmd\", handler);                                         \u002F\u002F exact command\nOnActivity(ActivityTypes.Message, handler, rank: RouteRank.Last);   \u002F\u002F all messages (fallback)\nOnConversationUpdate(ConversationUpdateEvents.MembersAdded, handler);\nOnActivity(ActivityTypes.Invoke, handler);\n```\n\n**Per-route auth:**\n```csharp\nOnMessage(\"-me\", OnMe, autoSignInHandlers: [\"me\"]);\n```\n\n**TurnState** — dot-notation keys scoped to conversation\u002Fuser\u002Ftemp:\n```csharp\nint count = state.GetValue(\"conversation.counter\", () => 0);\nstate.SetValue(\"conversation.counter\", count + 1);\nstate.DeleteValue(\"conversation.counter\");\n```\n\n**Storage backends**\n\n| Backend | Use case |\n|---|---|\n| `MemoryStorage` | Local dev only — not persistent |\n| Cosmos DB (via `IStorage` impl) | Production |\n| Blob Storage (via `IStorage` impl) | Production |\n\n## Authorization (User Token Flow)\n\n### Configuration in appsettings.json\n\n```json\n{\n  \"AgentApplication\": {\n    \"UserAuthorization\": {\n      \"DefaultHandlerName\": \"graph\",\n      \"AutoSignin\": true,\n      \"Handlers\": {\n        \"graph\": {\n          \"Settings\": {\n            \"AzureBotOAuthConnectionName\": \"GraphOAuthConnection\",\n            \"Title\": \"Sign in with Microsoft\",\n            \"Text\": \"Please sign in to continue\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n### Code patterns\n\n```csharp\npublic class MyAgent : AgentApplication\n{\n    public MyAgent(AgentApplicationOptions options) : base(options)\n    {\n        \u002F\u002F Handle sign-in failure\n        UserAuthorization.OnUserSignInFailure(\n            async (ctx, state, handler, response, activity, ct) =>\n            {\n                await ctx.SendActivityAsync($\"Sign-in failed: {response.Error?.Message}\", cancellationToken: ct);\n            });\n\n        \u002F\u002F Protected route — requires sign-in via \"graph\" handler\n        OnMessage(\"-profile\", OnProfileAsync, autoSignInHandlers: [\"graph\"]);\n\n        \u002F\u002F Fallback message handler\n        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);\n\n        \u002F\u002F Sign out\n        OnMessage(\"\u002Flogout\", OnLogoutAsync);\n    }\n\n    private async Task OnProfileAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n    {\n        \u002F\u002F Token is guaranteed here — route won't run until user is signed in\n        string token = await UserAuthorization.GetTurnTokenAsync(ctx, \"graph\");\n        \u002F\u002F Use token to call Graph API\n    }\n\n    private async Task OnLogoutAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n    {\n        await UserAuthorization.SignOutUserAsync(ctx, state, cancellationToken: ct);\n        await ctx.SendActivityAsync(\"Signed out.\", cancellationToken: ct);\n    }\n}\n```\n\n**OBO (on-behalf-of) — exchange user token for a downstream service token:**\n```csharp\nstring newToken = await UserAuthorization.ExchangeTurnTokenAsync(\n    ctx,\n    \"graph\",\n    exchangeScopes: [\"https:\u002F\u002Fgraph.microsoft.com\u002F.default\"]\n);\n```\n\n### Multiple OAuth handlers\n\n```json\n{\n  \"AgentApplication\": {\n    \"UserAuthorization\": {\n      \"DefaultHandlerName\": \"auto\",\n      \"AutoSignin\": true,\n      \"Handlers\": {\n        \"auto\": {\n          \"Settings\": {\n            \"AzureBotOAuthConnectionName\": \"AutoConnection\"\n          }\n        },\n        \"me\": {\n          \"Settings\": {\n            \"AzureBotOAuthConnectionName\": \"MeConnection\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n## Cards\n\n```csharp\nusing Microsoft.Agents.Core.Models;\nusing System.Text.Json;\n```\n\n**Adaptive Card** (from JSON):\n```csharp\nstring cardJson = File.ReadAllText(\"Resources\u002FmyCard.json\");\nvar card = new Attachment\n{\n    ContentType = ContentTypes.AdaptiveCard,\n    Content = JsonSerializer.Deserialize\u003Cobject>(cardJson)\n};\nawait ctx.SendActivityAsync(MessageFactory.Attachment(card), cancellationToken: ct);\n```\n\n**Hero Card:**\n```csharp\nvar card = new HeroCard\n{\n    Title = \"Card Title\",\n    Images = new List\u003CCardImage> { new CardImage(\"https:\u002F\u002Fexample.com\u002Fimage.jpg\") },\n    Buttons = new List\u003CCardAction>\n    {\n        new CardAction(ActionTypes.OpenUrl, \"Learn more\", value: \"https:\u002F\u002Fexample.com\")\n    }\n};\nawait ctx.SendActivityAsync(MessageFactory.Attachment(card.ToAttachment()), cancellationToken: ct);\n```\n\n**Adaptive Card Action Execute:**\n```csharp\npublic MyAgent(AgentApplicationOptions options) : base(options)\n{\n    AdaptiveCards.OnActionExecute(\"approve\", OnApproveAsync);\n    AdaptiveCards.OnActionExecute(\"reject\", OnRejectAsync);\n}\n\nprivate Task\u003CAdaptiveCardInvokeResponse> OnApproveAsync(\n    ITurnContext ctx, ITurnState state, object data, CancellationToken ct)\n{\n    var actionData = ProtocolJsonSerializer.ToObject\u003CMyDataModel>(data);\n    return Task.FromResult(new AdaptiveCardInvokeResponse\n    {\n        StatusCode = 200,\n        Type = \"application\u002Fvnd.microsoft.card.adaptive\",\n        Value = BuildCard(actionData)\n    });\n}\n```\n\n**Adaptive Card Search (typeahead):**\n```csharp\nAdaptiveCards.OnSearch(\"myDataset\", OnSearchAsync);\n\nprivate Task\u003CIList\u003CAdaptiveCardsSearchResult>> OnSearchAsync(\n    ITurnContext ctx, ITurnState state, Query\u003CAdaptiveCardsSearchParams> query, CancellationToken ct)\n{\n    var results = new List\u003CAdaptiveCardsSearchResult>\n    {\n        new AdaptiveCardsSearchResult(\"Result 1\", \"value1\")\n    };\n    return Task.FromResult\u003CIList\u003CAdaptiveCardsSearchResult>>(results);\n}\n```\n\n## Streaming\n\n```csharp\nprivate async Task OnMessageAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n{\n    try\n    {\n        ctx.StreamingResponse.SetFeedbackLoop(true);\n        ctx.StreamingResponse.SetGeneratedByAILabel(true);\n        await ctx.StreamingResponse.QueueInformativeUpdateAsync(\"Working on it...\", ct);\n        ctx.StreamingResponse.QueueTextChunk(\"Part 1 \");\n        ctx.StreamingResponse.QueueTextChunk(\"Part 2\");\n    }\n    finally\n    {\n        await ctx.StreamingResponse.EndStreamAsync(ct);\n    }\n}\n```\n\n**Streaming with Azure OpenAI:**\n```csharp\nprivate async Task OnMessageAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n{\n    try\n    {\n        await ctx.StreamingResponse.QueueInformativeUpdateAsync(\"Thinking...\", ct);\n\n        await foreach (var update in chatClient.CompleteChatStreamingAsync(messages, cancellationToken: ct))\n        {\n            if (update.ContentUpdate.Count > 0 && !string.IsNullOrEmpty(update.ContentUpdate[0]?.Text))\n            {\n                ctx.StreamingResponse.QueueTextChunk(update.ContentUpdate[0].Text);\n            }\n        }\n    }\n    finally\n    {\n        await ctx.StreamingResponse.EndStreamAsync(ct);\n    }\n}\n```\n\n**Streaming with a final card:**\n```csharp\nctx.StreamingResponse.FinalMessage = MessageFactory.Attachment(new Attachment\n{\n    ContentType = ContentTypes.AdaptiveCard,\n    Content = cardJson\n});\nawait ctx.StreamingResponse.EndStreamAsync(ct);\n```\n\n## Proactive Messaging\n\n```csharp\npublic class MyAgent : AgentApplication\n{\n    public MyAgent(AgentApplicationOptions options) : base(options)\n    {\n        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);\n    }\n\n    private async Task OnMessageAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n    {\n        \u002F\u002F Store the conversation reference for later\n        string convId = await Proactive.StoreConversationAsync(ctx, ct);\n        await ctx.SendActivityAsync($\"Stored conversation: {convId}\", cancellationToken: ct);\n    }\n\n    [ContinueConversation]\n    public async Task OnProactiveAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n    {\n        await ctx.SendActivityAsync(\"Proactive message!\", cancellationToken: ct);\n    }\n}\n```\n\nIn `Program.cs`:\n```csharp\napp.MapAgentProactiveEndpoints\u003CMyAgent>(requireAuth: !app.Environment.IsDevelopment());\n```\n\n## OpenTelemetry \u002F Observability\n\nUse the `agents-sdk-dotnet-otel` skill for OpenTelemetry setup, SDK trace and\nmetric subscriptions, safe custom instrumentation, OTLP configuration, Azure\nMonitor export, validation, and the local Aspire Dashboard.\n\n## Common Mistakes\n\n**1. Wrong endpoint mapping method**\n\n```csharp\n\u002F\u002F WRONG — for ActivityHandler compat layer only\napp.MapAgentEndpoints(requireAuth: false);\n\n\u002F\u002F CORRECT — for AgentApplication subclasses\napp.MapAgentApplicationEndpoints(requireAuth: false);\n```\n\n**2. Missing IStorage registration**\n\n```csharp\n\u002F\u002F WRONG — no storage registered, runtime error\nbuilder.AddAgent\u003CMyAgent>();\n\n\u002F\u002F CORRECT — always register IStorage\nbuilder.AddAgent\u003CMyAgent>();\nbuilder.Services.AddSingleton\u003CIStorage, MemoryStorage>();\n```\n\n**3. Calling AddAgentApplicationOptions separately**\n\n```csharp\n\u002F\u002F WRONG — double registration\nbuilder.AddAgent\u003CMyAgent>();\nbuilder.Services.AddAgentApplicationOptions(builder.Configuration);\n\n\u002F\u002F CORRECT — AddAgent handles everything\nbuilder.AddAgent\u003CMyAgent>();\n```\n\n**4. Wrong ConversationReference field name**\n\n```csharp\n\u002F\u002F WRONG\nvar reference = new ConversationReference { Bot = new ChannelAccount(appId) };\n\n\u002F\u002F CORRECT\nvar reference = new ConversationReference { Agent = new ChannelAccount(appId) };\n```\n\n**5. Forgetting UseAuthentication\u002FUseAuthorization**\n\n```csharp\n\u002F\u002F WRONG — auth middleware missing\nvar app = builder.Build();\napp.MapAgentApplicationEndpoints(requireAuth: true);\n\n\u002F\u002F CORRECT\nvar app = builder.Build();\napp.UseAuthentication();\napp.UseAuthorization();\napp.MapAgentApplicationEndpoints(requireAuth: true);\n```\n\n**6. TokenValidation:Enabled left true for local dev**\n\nIf `TokenValidation:Enabled` is `true` with no valid credentials configured, every incoming request will be rejected with 401. Set to `false` for local anonymous development.\n\n**7. Missing AspNetExtensions.cs for AddAgentAspNetAuthentication**\n\n`AddAgentAspNetAuthentication` is NOT built into the SDK packages — it's a helper extension that must be copied into your project from the shared samples.\n\n```csharp\n\u002F\u002F ERROR — CS1061: 'IServiceCollection' does not contain a definition for 'AddAgentAspNetAuthentication'\nbuilder.Services.AddAgentAspNetAuthentication(builder.Configuration);\n\n\u002F\u002F FIX — Copy AspNetExtensions.cs from the samples repo into your project:\n\u002F\u002F https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents-for-net\u002Fblob\u002Fmain\u002Fsrc\u002Fsamples\u002FShared\u002FAspNetExtensions.cs\n```\n\n**8. Missing `Microsoft.Agents.Builder.State` using for ITurnState**\n\n```csharp\n\u002F\u002F WRONG — CS0246: ITurnState could not be found\nusing Microsoft.Agents.Builder;\nusing Microsoft.Agents.Builder.App;\n\n\u002F\u002F CORRECT — add the State namespace\nusing Microsoft.Agents.Builder;\nusing Microsoft.Agents.Builder.App;\nusing Microsoft.Agents.Builder.State;\n```\n\n## Contributing\n\nIf you hit a problem this skill couldn't solve, found a workaround, or noticed something wrong or outdated, that's valuable — please help improve this skill for everyone.\n\nDraft a suggested issue title and body based on the conversation, then ask the user to open it at: https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagents\u002Fissues\u002Fnew\n\nA good issue includes:\n- What the user was trying to do\n- What went wrong (errors, unexpected behavior)\n- What worked — including any workaround found during this conversation\n- Relevant code or config snippets\n","## Overview\n\nThe Microsoft 365 Agents SDK builds multichannel agents for Teams, Copilot Studio, and web chat.\n\n| Package | Purpose |\n|---|---|\n| `Microsoft.Agents.Hosting.AspNetCore` | ASP.NET Core hosting, auth, endpoint mapping |\n| `Microsoft.Agents.Authentication.Msal` | MSAL-based auth (client credentials, OBO) |\n| `Microsoft.Agents.Builder` | Core: AgentApplication, ITurnContext, ITurnState |\n| `Microsoft.Agents.Core` | Models, activity types, channel accounts |\n| `Microsoft.Agents.Storage` | IStorage, MemoryStorage |\n| `Microsoft.Agents.Extensions.Teams` | Teams-specific models and extensions |\n| `Microsoft.Agents.Builder.Dialogs` | Dialog system (waterfall, prompts) |\n| `Microsoft.Agents.AI` | AI-specific features |\n\n**Minimal project requires only:** `Microsoft.Agents.Hosting.AspNetCore` + `Microsoft.Agents.Authentication.Msal`. The others are transitive dependencies pulled in automatically.\n\n**Always use the latest non-beta (stable) version.** Do not use `--prerelease` unless specifically needed.\n\nRequires .NET 8+.\n\n## Azure Resources Required\n\n**Microsoft Entra App Registration**\n- `ClientId` — Application (client) ID\n- `ClientSecret` — Certificates & secrets\n- `TenantId` — Directory (tenant) ID\n\n**Azure Bot Resource**\n- Messaging endpoint: `https:\u002F\u002F\u003Cyour-host>\u002Fapi\u002Fmessages`\n- Microsoft App ID must match `ClientId`\n\nLocal dev: Set `TokenValidation:Enabled` to `false`. No Azure Bot needed until deployment.\n\n## Configuration (appsettings.json)\n\n### Single connection (most common)\n\n**appsettings.json** — no secret here (safe to commit):\n\n```json\n{\n  \"Connections\": {\n    \"ServiceConnection\": {\n      \"Settings\": {\n        \"AuthType\": \"ClientSecret\",\n        \"AuthorityEndpoint\": \"https:\u002F\u002Flogin.microsoftonline.com\u002F\u003CtenantId>\",\n        \"ClientId\": \"\u003CappId>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    }\n  },\n  \"ConnectionsMap\": [\n    {\n      \"ServiceUrl\": \"*\",\n      \"Connection\": \"ServiceConnection\"\n    }\n  ],\n  \"TokenValidation\": {\n    \"Enabled\": true,\n    \"Audiences\": [\"\u003CappId>\"],\n    \"TenantId\": \"\u003CtenantId>\"\n  }\n}\n```\n\n**appsettings.Development.json** — secret lives here (excluded via `.gitignore`):\n\n```json\n{\n  \"Connections\": {\n    \"ServiceConnection\": {\n      \"Settings\": {\n        \"ClientSecret\": \"\u003Csecret>\"\n      }\n    }\n  },\n  \"TokenValidation\": {\n    \"Enabled\": false\n  }\n}\n```\n\n### How ConnectionsMap works\n\nEach entry maps a `ServiceUrl` pattern to a named connection. The first matching entry wins.\n- `ServiceUrl: \"*\"` — matches any service URL (use as the default\u002Ffallback)\n- Other values are treated as regex patterns\n\n### Multiple connections (different identities per channel)\n\n```json\n{\n  \"Connections\": {\n    \"MainConn\": {\n      \"Settings\": {\n        \"AuthType\": \"ClientSecret\",\n        \"AuthorityEndpoint\": \"https:\u002F\u002Flogin.microsoftonline.com\u002F\u003CtenantId>\",\n        \"ClientId\": \"\u003Capp-id-1>\",\n        \"ClientSecret\": \"\u003Csecret-1>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    },\n    \"TeamsConn\": {\n      \"Settings\": {\n        \"AuthType\": \"ClientSecret\",\n        \"AuthorityEndpoint\": \"https:\u002F\u002Flogin.microsoftonline.com\u002F\u003CtenantId>\",\n        \"ClientId\": \"\u003Capp-id-2>\",\n        \"ClientSecret\": \"\u003Csecret-2>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    }\n  },\n  \"ConnectionsMap\": [\n    {\n      \"ServiceUrl\": \"https:\u002F\u002Fsmba.trafficmanager.net\u002F.*\",\n      \"Connection\": \"TeamsConn\"\n    },\n    {\n      \"ServiceUrl\": \"*\",\n      \"Connection\": \"MainConn\"\n    }\n  ]\n}\n```\n\n### Auth type variants\n\n**UserManagedIdentity** (no secret, Azure-hosted only):\n```json\n{\n  \"Connections\": {\n    \"ServiceConnection\": {\n      \"Settings\": {\n        \"AuthType\": \"UserManagedIdentity\",\n        \"ClientId\": \"\u003Cmsi-clientId>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    }\n  }\n}\n```\n\n**FederatedCredentials** (no secret, App Registration + MSI):\n```json\n{\n  \"Connections\": {\n    \"ServiceConnection\": {\n      \"Settings\": {\n        \"AuthType\": \"FederatedCredentials\",\n        \"AuthorityEndpoint\": \"https:\u002F\u002Flogin.microsoftonline.com\u002F\u003CtenantId>\",\n        \"ClientId\": \"\u003CappId>\",\n        \"FederatedClientId\": \"\u003Cmsi-clientId>\",\n        \"Scopes\": [\"https:\u002F\u002Fapi.botframework.com\u002F.default\"]\n      }\n    }\n  }\n}\n```\n\n### Available connection settings fields\n\n`AuthType`, `AuthorityEndpoint`, `ClientId`, `ClientSecret`, `TenantId`, `FederatedClientId`, `Scopes`, `CertificateSubject`, `CertificateThumbprint`\n\n### Local development (disable token validation)\n\nPut in `appsettings.Development.json` (not `appsettings.json`):\n\n```json\n{\n  \"TokenValidation\": {\n    \"Enabled\": false\n  }\n}\n```\n\n## Quick Start\n\n**Prerequisite:** Copy [`AspNetExtensions.cs`](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents-for-net\u002Fblob\u002Fmain\u002Fsrc\u002Fsamples\u002FShared\u002FAspNetExtensions.cs) into your project. This provides `AddAgentAspNetAuthentication` for JWT token validation.\n\n**Program.cs:**\n\n```csharp\nusing Microsoft.Agents.Hosting.AspNetCore;\nusing Microsoft.Agents.Storage;\n\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddHttpClient();\nbuilder.AddAgent\u003CMyAgent>();\nbuilder.Services.AddSingleton\u003CIStorage, MemoryStorage>();\nbuilder.Services.AddAgentAspNetAuthentication(builder.Configuration);\n\nvar app = builder.Build();\n\napp.UseAuthentication();\napp.UseAuthorization();\napp.MapAgentRootEndpoint();\napp.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());\n\napp.Run();\n```\n\n**MyAgent.cs** — put the `AgentApplication` subclass in its own file (see [AgentApplication Patterns](#agentapplication-patterns) below for routing, state, and auth examples).\n\n**Properties\u002FlaunchSettings.json:**\n\n```json\n{\n  \"profiles\": {\n    \"MyAgent\": {\n      \"commandName\": \"Project\",\n      \"launchBrowser\": false,\n      \"environmentVariables\": {\n        \"ASPNETCORE_ENVIRONMENT\": \"Development\"\n      },\n      \"applicationUrl\": \"https:\u002F\u002Flocalhost:3979;http:\u002F\u002Flocalhost:3978\"\n    }\n  }\n}\n```\n\nRun: `dotnet run`\n\n**.gitignore** — ensure `appsettings.Development.json` is excluded (it contains secrets):\n\n```\nappsettings.Development.json\n```\n\n**Teams app manifest (if targeting Teams):** Copy the `appManifest\u002F` folder from [`Agents-for-net\u002Fsrc\u002Fsamples\u002FEmptyAgent\u002FappManifest`](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents-for-net\u002Ftree\u002Fmain\u002Fsrc\u002Fsamples\u002FEmptyAgent\u002FappManifest) into your project. Then update `manifest.json`:\n- Replace all `${{AAD_APP_CLIENT_ID}}` with your bot's Client ID\n- Set `name.short` and `name.full` to your bot's display name\n\n## Program.cs Structure\n\n### Minimal setup\n\n```csharp\nusing Microsoft.Agents.Hosting.AspNetCore;\nusing Microsoft.Agents.Storage;\n\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddHttpClient();\nbuilder.AddAgent\u003CMyAgent>();\nbuilder.Services.AddSingleton\u003CIStorage, MemoryStorage>();\nbuilder.Services.AddAgentAspNetAuthentication(builder.Configuration);\n\nvar app = builder.Build();\n\napp.UseAuthentication();\napp.UseAuthorization();\napp.MapAgentRootEndpoint();\napp.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());\n\napp.Run();\n```\n\n### With proactive messaging endpoints\n\n```csharp\napp.MapAgentProactiveEndpoints\u003CMyAgent>(requireAuth: !app.Environment.IsDevelopment());\n```\n\n### With custom routes\n\n```csharp\nvar app = builder.Build();\n\napp.UseAuthentication();\napp.UseAuthorization();\napp.MapAgentRootEndpoint();\napp.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());\napp.MapGet(\"\u002Fhealth\", () => Results.Json(new { ok = true }));\n\napp.Run();\n```\n\n### Agent class decorators\n\n```csharp\n[Agent(name: \"MyAgent\", description: \"A helpful agent\", version: \"1.0\")]\n[AgentInterface(protocol: AgentTransportProtocol.ActivityProtocol, path: \"\u002Fapi\u002Fmessages\")]\npublic class MyAgent : AgentApplication\n{\n    \u002F\u002F ...\n}\n```\n\n### Important: AddAgent vs AddAgentApplicationOptions\n\n- `builder.AddAgent\u003CT>()` — registers the agent class. **Always required.**\n- Do **not** call `AddAgentApplicationOptions()` separately unless you have a specific reason — `AddAgent` handles it.\n\n### Important: MapAgentEndpoints vs MapAgentApplicationEndpoints\n\n- `MapAgentApplicationEndpoints` — for `AgentApplication` subclasses (modern pattern)\n- `MapAgentEndpoints` — for `ActivityHandler` \u002F `TeamsActivityHandler` compat layer bots\n\nUsing the wrong one causes runtime routing failures with no clear error.\n\n## Validating Your Configuration\n\n### 1. Validate bot credentials (ClientId \u002F ClientSecret \u002F TenantId)\n\n```bash\ncurl -s -X POST \\\n  \"https:\u002F\u002Flogin.microsoftonline.com\u002F$tenantId\u002Foauth2\u002Fv2.0\u002Ftoken\" \\\n  -d \"grant_type=client_credentials\\\n&client_id=$clientId\\\n&client_secret=$clientSecret\\\n&scope=https:\u002F\u002Fapi.botframework.com\u002F.default\" \\\n  | jq '{token_type, expires_in, error, error_description}'\n```\n\nCommon errors:\n- `AADSTS700016` — `ClientId` not found in tenant (wrong ID or wrong tenant)\n- `AADSTS7000215` — invalid `ClientSecret` (expired or incorrect)\n- `AADSTS90002` — `TenantId` not found\n\n### 2. Validate the agent is running and reachable\n\n```bash\ncurl -s -o \u002Fdev\u002Fnull -w \"%{http_code}\" \\\n  -X POST http:\u002F\u002Flocalhost:3978\u002Fapi\u002Fmessages \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{}'\n```\n\n- `401` — agent is running; JWT auth rejected the empty request (expected)\n- `000` or connection refused — agent is not running or wrong port\n- `200` — agent is running with auth disabled (local dev with `TokenValidation:Enabled = false`)\n\n### 3. Validate an OAuth connection name\n\nOAuth connection names can only be tested end-to-end via:\n\n**Azure Portal → Your Bot Resource → Settings → OAuth Connection Settings → [your connection] → Test Connection**\n\n## Local Testing with Agents Playground\n\nThe Agents Playground lets you test locally without deploying to Azure.\n\n**Install:**\n```bash\nnpm install -g agentsplayground\n```\n\n**Run against an anonymous agent:**\n```bash\nagentsplayground -c emulator\n```\n\nThen start your agent separately with `dotnet run`.\n\n**With authentication:**\n```bash\nagentsplayground -c msteams \\\n  --client-id \u003Cyour-app-id> \\\n  --client-secret \u003Cyour-secret> \\\n  --tenant-id \u003Cyour-tenant-id>\n```\n\n**Channel options** (`-c`): `msteams`, `webchat`, `directline`, `emulator`, `agents`\n\nIf the playground connects but messages don't get responses, add a fallback handler to confirm:\n\n```csharp\nOnActivity(ActivityTypes.Message, async (ctx, state, ct) =>\n{\n    await ctx.SendActivityAsync($\"Echo: {ctx.Activity.Text}\", cancellationToken: ct);\n}, rank: RouteRank.Last);\n```\n\n## AgentApplication Patterns\n\n**Routing**\n```csharp\nOnMessage(\"\u002Fcmd\", handler);                                         \u002F\u002F exact command\nOnActivity(ActivityTypes.Message, handler, rank: RouteRank.Last);   \u002F\u002F all messages (fallback)\nOnConversationUpdate(ConversationUpdateEvents.MembersAdded, handler);\nOnActivity(ActivityTypes.Invoke, handler);\n```\n\n**Per-route auth:**\n```csharp\nOnMessage(\"-me\", OnMe, autoSignInHandlers: [\"me\"]);\n```\n\n**TurnState** — dot-notation keys scoped to conversation\u002Fuser\u002Ftemp:\n```csharp\nint count = state.GetValue(\"conversation.counter\", () => 0);\nstate.SetValue(\"conversation.counter\", count + 1);\nstate.DeleteValue(\"conversation.counter\");\n```\n\n**Storage backends**\n\n| Backend | Use case |\n|---|---|\n| `MemoryStorage` | Local dev only — not persistent |\n| Cosmos DB (via `IStorage` impl) | Production |\n| Blob Storage (via `IStorage` impl) | Production |\n\n## Authorization (User Token Flow)\n\n### Configuration in appsettings.json\n\n```json\n{\n  \"AgentApplication\": {\n    \"UserAuthorization\": {\n      \"DefaultHandlerName\": \"graph\",\n      \"AutoSignin\": true,\n      \"Handlers\": {\n        \"graph\": {\n          \"Settings\": {\n            \"AzureBotOAuthConnectionName\": \"GraphOAuthConnection\",\n            \"Title\": \"Sign in with Microsoft\",\n            \"Text\": \"Please sign in to continue\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n### Code patterns\n\n```csharp\npublic class MyAgent : AgentApplication\n{\n    public MyAgent(AgentApplicationOptions options) : base(options)\n    {\n        \u002F\u002F Handle sign-in failure\n        UserAuthorization.OnUserSignInFailure(\n            async (ctx, state, handler, response, activity, ct) =>\n            {\n                await ctx.SendActivityAsync($\"Sign-in failed: {response.Error?.Message}\", cancellationToken: ct);\n            });\n\n        \u002F\u002F Protected route — requires sign-in via \"graph\" handler\n        OnMessage(\"-profile\", OnProfileAsync, autoSignInHandlers: [\"graph\"]);\n\n        \u002F\u002F Fallback message handler\n        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);\n\n        \u002F\u002F Sign out\n        OnMessage(\"\u002Flogout\", OnLogoutAsync);\n    }\n\n    private async Task OnProfileAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n    {\n        \u002F\u002F Token is guaranteed here — route won't run until user is signed in\n        string token = await UserAuthorization.GetTurnTokenAsync(ctx, \"graph\");\n        \u002F\u002F Use token to call Graph API\n    }\n\n    private async Task OnLogoutAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n    {\n        await UserAuthorization.SignOutUserAsync(ctx, state, cancellationToken: ct);\n        await ctx.SendActivityAsync(\"Signed out.\", cancellationToken: ct);\n    }\n}\n```\n\n**OBO (on-behalf-of) — exchange user token for a downstream service token:**\n```csharp\nstring newToken = await UserAuthorization.ExchangeTurnTokenAsync(\n    ctx,\n    \"graph\",\n    exchangeScopes: [\"https:\u002F\u002Fgraph.microsoft.com\u002F.default\"]\n);\n```\n\n### Multiple OAuth handlers\n\n```json\n{\n  \"AgentApplication\": {\n    \"UserAuthorization\": {\n      \"DefaultHandlerName\": \"auto\",\n      \"AutoSignin\": true,\n      \"Handlers\": {\n        \"auto\": {\n          \"Settings\": {\n            \"AzureBotOAuthConnectionName\": \"AutoConnection\"\n          }\n        },\n        \"me\": {\n          \"Settings\": {\n            \"AzureBotOAuthConnectionName\": \"MeConnection\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n## Cards\n\n```csharp\nusing Microsoft.Agents.Core.Models;\nusing System.Text.Json;\n```\n\n**Adaptive Card** (from JSON):\n```csharp\nstring cardJson = File.ReadAllText(\"Resources\u002FmyCard.json\");\nvar card = new Attachment\n{\n    ContentType = ContentTypes.AdaptiveCard,\n    Content = JsonSerializer.Deserialize\u003Cobject>(cardJson)\n};\nawait ctx.SendActivityAsync(MessageFactory.Attachment(card), cancellationToken: ct);\n```\n\n**Hero Card:**\n```csharp\nvar card = new HeroCard\n{\n    Title = \"Card Title\",\n    Images = new List\u003CCardImage> { new CardImage(\"https:\u002F\u002Fexample.com\u002Fimage.jpg\") },\n    Buttons = new List\u003CCardAction>\n    {\n        new CardAction(ActionTypes.OpenUrl, \"Learn more\", value: \"https:\u002F\u002Fexample.com\")\n    }\n};\nawait ctx.SendActivityAsync(MessageFactory.Attachment(card.ToAttachment()), cancellationToken: ct);\n```\n\n**Adaptive Card Action Execute:**\n```csharp\npublic MyAgent(AgentApplicationOptions options) : base(options)\n{\n    AdaptiveCards.OnActionExecute(\"approve\", OnApproveAsync);\n    AdaptiveCards.OnActionExecute(\"reject\", OnRejectAsync);\n}\n\nprivate Task\u003CAdaptiveCardInvokeResponse> OnApproveAsync(\n    ITurnContext ctx, ITurnState state, object data, CancellationToken ct)\n{\n    var actionData = ProtocolJsonSerializer.ToObject\u003CMyDataModel>(data);\n    return Task.FromResult(new AdaptiveCardInvokeResponse\n    {\n        StatusCode = 200,\n        Type = \"application\u002Fvnd.microsoft.card.adaptive\",\n        Value = BuildCard(actionData)\n    });\n}\n```\n\n**Adaptive Card Search (typeahead):**\n```csharp\nAdaptiveCards.OnSearch(\"myDataset\", OnSearchAsync);\n\nprivate Task\u003CIList\u003CAdaptiveCardsSearchResult>> OnSearchAsync(\n    ITurnContext ctx, ITurnState state, Query\u003CAdaptiveCardsSearchParams> query, CancellationToken ct)\n{\n    var results = new List\u003CAdaptiveCardsSearchResult>\n    {\n        new AdaptiveCardsSearchResult(\"Result 1\", \"value1\")\n    };\n    return Task.FromResult\u003CIList\u003CAdaptiveCardsSearchResult>>(results);\n}\n```\n\n## Streaming\n\n```csharp\nprivate async Task OnMessageAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n{\n    try\n    {\n        ctx.StreamingResponse.SetFeedbackLoop(true);\n        ctx.StreamingResponse.SetGeneratedByAILabel(true);\n        await ctx.StreamingResponse.QueueInformativeUpdateAsync(\"Working on it...\", ct);\n        ctx.StreamingResponse.QueueTextChunk(\"Part 1 \");\n        ctx.StreamingResponse.QueueTextChunk(\"Part 2\");\n    }\n    finally\n    {\n        await ctx.StreamingResponse.EndStreamAsync(ct);\n    }\n}\n```\n\n**Streaming with Azure OpenAI:**\n```csharp\nprivate async Task OnMessageAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n{\n    try\n    {\n        await ctx.StreamingResponse.QueueInformativeUpdateAsync(\"Thinking...\", ct);\n\n        await foreach (var update in chatClient.CompleteChatStreamingAsync(messages, cancellationToken: ct))\n        {\n            if (update.ContentUpdate.Count > 0 && !string.IsNullOrEmpty(update.ContentUpdate[0]?.Text))\n            {\n                ctx.StreamingResponse.QueueTextChunk(update.ContentUpdate[0].Text);\n            }\n        }\n    }\n    finally\n    {\n        await ctx.StreamingResponse.EndStreamAsync(ct);\n    }\n}\n```\n\n**Streaming with a final card:**\n```csharp\nctx.StreamingResponse.FinalMessage = MessageFactory.Attachment(new Attachment\n{\n    ContentType = ContentTypes.AdaptiveCard,\n    Content = cardJson\n});\nawait ctx.StreamingResponse.EndStreamAsync(ct);\n```\n\n## Proactive Messaging\n\n```csharp\npublic class MyAgent : AgentApplication\n{\n    public MyAgent(AgentApplicationOptions options) : base(options)\n    {\n        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);\n    }\n\n    private async Task OnMessageAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n    {\n        \u002F\u002F Store the conversation reference for later\n        string convId = await Proactive.StoreConversationAsync(ctx, ct);\n        await ctx.SendActivityAsync($\"Stored conversation: {convId}\", cancellationToken: ct);\n    }\n\n    [ContinueConversation]\n    public async Task OnProactiveAsync(ITurnContext ctx, ITurnState state, CancellationToken ct)\n    {\n        await ctx.SendActivityAsync(\"Proactive message!\", cancellationToken: ct);\n    }\n}\n```\n\nIn `Program.cs`:\n```csharp\napp.MapAgentProactiveEndpoints\u003CMyAgent>(requireAuth: !app.Environment.IsDevelopment());\n```\n\n## OpenTelemetry \u002F Observability\n\nUse the `agents-sdk-dotnet-otel` skill for OpenTelemetry setup, SDK trace and\nmetric subscriptions, safe custom instrumentation, OTLP configuration, Azure\nMonitor export, validation, and the local Aspire Dashboard.\n\n## Common Mistakes\n\n**1. Wrong endpoint mapping method**\n\n```csharp\n\u002F\u002F WRONG — for ActivityHandler compat layer only\napp.MapAgentEndpoints(requireAuth: false);\n\n\u002F\u002F CORRECT — for AgentApplication subclasses\napp.MapAgentApplicationEndpoints(requireAuth: false);\n```\n\n**2. Missing IStorage registration**\n\n```csharp\n\u002F\u002F WRONG — no storage registered, runtime error\nbuilder.AddAgent\u003CMyAgent>();\n\n\u002F\u002F CORRECT — always register IStorage\nbuilder.AddAgent\u003CMyAgent>();\nbuilder.Services.AddSingleton\u003CIStorage, MemoryStorage>();\n```\n\n**3. Calling AddAgentApplicationOptions separately**\n\n```csharp\n\u002F\u002F WRONG — double registration\nbuilder.AddAgent\u003CMyAgent>();\nbuilder.Services.AddAgentApplicationOptions(builder.Configuration);\n\n\u002F\u002F CORRECT — AddAgent handles everything\nbuilder.AddAgent\u003CMyAgent>();\n```\n\n**4. Wrong ConversationReference field name**\n\n```csharp\n\u002F\u002F WRONG\nvar reference = new ConversationReference { Bot = new ChannelAccount(appId) };\n\n\u002F\u002F CORRECT\nvar reference = new ConversationReference { Agent = new ChannelAccount(appId) };\n```\n\n**5. Forgetting UseAuthentication\u002FUseAuthorization**\n\n```csharp\n\u002F\u002F WRONG — auth middleware missing\nvar app = builder.Build();\napp.MapAgentApplicationEndpoints(requireAuth: true);\n\n\u002F\u002F CORRECT\nvar app = builder.Build();\napp.UseAuthentication();\napp.UseAuthorization();\napp.MapAgentApplicationEndpoints(requireAuth: true);\n```\n\n**6. TokenValidation:Enabled left true for local dev**\n\nIf `TokenValidation:Enabled` is `true` with no valid credentials configured, every incoming request will be rejected with 401. Set to `false` for local anonymous development.\n\n**7. Missing AspNetExtensions.cs for AddAgentAspNetAuthentication**\n\n`AddAgentAspNetAuthentication` is NOT built into the SDK packages — it's a helper extension that must be copied into your project from the shared samples.\n\n```csharp\n\u002F\u002F ERROR — CS1061: 'IServiceCollection' does not contain a definition for 'AddAgentAspNetAuthentication'\nbuilder.Services.AddAgentAspNetAuthentication(builder.Configuration);\n\n\u002F\u002F FIX — Copy AspNetExtensions.cs from the samples repo into your project:\n\u002F\u002F https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents-for-net\u002Fblob\u002Fmain\u002Fsrc\u002Fsamples\u002FShared\u002FAspNetExtensions.cs\n```\n\n**8. Missing `Microsoft.Agents.Builder.State` using for ITurnState**\n\n```csharp\n\u002F\u002F WRONG — CS0246: ITurnState could not be found\nusing Microsoft.Agents.Builder;\nusing Microsoft.Agents.Builder.App;\n\n\u002F\u002F CORRECT — add the State namespace\nusing Microsoft.Agents.Builder;\nusing Microsoft.Agents.Builder.App;\nusing Microsoft.Agents.Builder.State;\n```\n\n## Contributing\n\nIf you hit a problem this skill couldn't solve, found a workaround, or noticed something wrong or outdated, that's valuable — please help improve this skill for everyone.\n\nDraft a suggested issue title and body based on the conversation, then ask the user to open it at: https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagents\u002Fissues\u002Fnew\n\nA good issue includes:\n- What the user was trying to do\n- What went wrong (errors, unexpected behavior)\n- What worked — including any workaround found during this conversation\n- Relevant code or config snippets\n",{"name":5,"description":7},"main","8171bc7e0ca3b8defd578a6bb317367c2901983f","agent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet",346,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents","https:\u002F\u002Faka.ms\u002Fagentsdkdocs","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-14 08:54:12",{"source":8,"skillName":5,"commands":47,"prompt":57,"zipAvailable":58},[48,51,54],{"tool":49,"command":50},"npx","npx skills add microsoft\u002FAgents --skill agents-sdk-dotnet",{"tool":52,"command":53},"bunx","bunx skills add microsoft\u002FAgents --skill agents-sdk-dotnet",{"tool":55,"command":56},"pnpm","pnpm dlx skills add microsoft\u002FAgents --skill agents-sdk-dotnet","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet\u002FSKILL.md",true,[60,66,70],{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fcards.md","REFERENCE","参考文档",5411,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet\u002Freferences\u002Fcards.md",{"path":67,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fstreaming.md",2404,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet\u002Freferences\u002Fstreaming.md",{"path":71,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":74,"sourceHtmlUrl":75},"scripts\u002Fmermaid_view.py","SCRIPT","脚本",16777,"https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Fmy_skills\u002Fmermaid-view\u002Fscripts\u002Fmermaid_view.py",[77,95,115,130,142,151],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":31},"01M6PJCYCYJQDX318SQN3EBF0E","sync-teams-samples-to-agents-sdk","CI instructions for a bounded Teams SDK to Agents SDK sample synchronization using the selected language profile.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fautomation\u002Fteams-sample-sync\u002Fskills\u002Fsync-teams-samples-to-agents-sdk\u002FSKILL.md",[],[24,25,84,85,86,87,88,89,90,91,92,93,94],"sync","teams","sync teams samples to agents sdk","ci","synchronization","instructions","profile","language","sample","for","bounded",{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":31},"01M6PJCFNGCX555YERYQ459JFE","teams-sdk-to-agents-sdk-typescript-migration","Migrate a JavaScript or TypeScript application using the Microsoft Teams SDK App runtime to Microsoft 365 Agents SDK while preserving its Teams behaviors. Use for Teams SDK migrations, including automated sample synchronization; use the separate Bot Framework migration skill for botbuilder applications.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-js\u002Fskills\u002Fteams-sdk-to-agents-sdk-typescript-migration\u002FSKILL.md",[],[85,102,24,25,103,104,105,106,107,108,109,92,110,111,88,112,93,113,114,9],"typescript","agents sdk typescript","migration","teams sdk to agents sdk typescript migration","microsoft teams","applications","app","runtime","migrations","use","migrate","bot","javascript",{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":126,"publishedAt":31},"01M69B8QV24JVPXH25EH77X0SZ","teams-app-manifest","Create or audit a Microsoft Teams app manifest for an existing Microsoft 365 Agents SDK application by mapping declared intent and source-code evidence to released manifest capabilities. Use when manifest.json is missing, incomplete, or must be checked against implemented Teams features. Does not configure Microsoft Entra, Azure Bot, Developer Portal, or deployment unless separately requested.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-sdk-common\u002Fskills\u002Fteams-app-manifest\u002FSKILL.md",[121],{"categoryNo":122,"categoryName":123,"taxonomyType":124,"taxonomyTypeDesc":125},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[85,127,25,113,24,9,128,129],"teams app manifest","azure","deployment",{"skillNo":131,"name":132,"nameZh":6,"description":133,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":134,"categories":135,"keywords":136,"publishedAt":31},"01M69B8MN62NBY93YTJAQG2Y81","agents-sdk-provision","Use when provisioning Azure resources for a Microsoft Agents SDK application — including creating an Azure Bot Service resource, setting up Entra app registrations, configuring identity credentials (UserManagedIdentity, FederatedCredentials, or ClientSecret), adding a Teams channel, running Bicep deployments for SSO, or setting up OAuth user sign-in connections via az CLI. Trigger even if the user doesn't say \"provision\" — use on requests like \"set up my bot on Azure\", \"deploy my bot\", \"configure Azure for my bot\", or \"get Teams SSO working.\" Applies to all languages (dotnet, Node.js, Python).","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-sdk-common\u002Fskills\u002Fagents-sdk-provision\u002FSKILL.md",[],[24,25,137,113,138,139,9,26,140,141,128,85],"agents sdk provision","cli","python","identity","deploy",{"skillNo":143,"name":144,"nameZh":6,"description":145,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":146,"categories":147,"keywords":148,"publishedAt":31},"01M69B8HFZ45NQGWQQD483TWPB","agents-sdk-to-prod","Assess, create, harden, deploy, or review production readiness of Python Microsoft 365 Agents SDK agents and their direct hosting\u002Foperations files. Use only for Agents SDK scenarios, not unrelated application hardening.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-python\u002Fskills\u002Fagents-sdk-to-prod\u002FSKILL.md",[],[149,25,24,9,139,150,141],"agents sdk to prod","review",{"skillNo":152,"name":153,"nameZh":6,"description":154,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":155,"categories":156,"keywords":163,"publishedAt":31},"01M69B8ENJGC9NPQBZAYAN4706","agents-sdk-python-otel","Use when adding, configuring, validating, or troubleshooting OpenTelemetry observability for a Microsoft 365 Agents SDK application in Python. Trigger when the user mentions OpenTelemetry, OTel, telemetry, traces, metrics, logs, OTLP, Aspire Dashboard, Application Insights, Azure Monitor, distributed tracing, custom tracers or meters, span sampling, or observing microsoft_agents SDK signals.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-python\u002Fskills\u002Fagents-sdk-python-otel\u002FSKILL.md",[157,160],{"categoryNo":158,"categoryName":159,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000013","分析与可视化",{"categoryNo":161,"categoryName":162,"taxonomyType":124,"taxonomyTypeDesc":125},"01JBSEEDCAT000000000000033","数据分析师",[24,139,164,25,165,166,128,167,9,168,169,170,171],"otel","agents sdk python otel","aspire","telemetry","dashboard","distributed","aspire dashboard","monitor"]