Use when troubleshooting an agent built with the Microsoft Agents SDK (Microsoft.Agents.Hosting.AspNetCore and related packages) in C# / .NET. Trigger on any of these symptoms: build or C# compile errors, crashes on startup, 401 or auth errors on incoming requests, the bot not responding to messages, appsettings.json configuration problems, Azure AD credential failures (AADSTS errors), port conflicts, or the agent not connecting in Teams or the Agents Playground. Use even if the user doesn't mention the SDK by name — trigger on symptoms like "my bot won't start", "getting 401s", or "bot isn't responding."
Use when troubleshooting an agent built with the Microsoft Agents SDK (Microsoft.Agents.Hosting.AspNetCore and related packages) in C# / .NET. Trigger on any of these symptoms: build or C# compile errors, crashes on startup, 401 or auth errors on incoming requests, the bot not responding to messages, appsettings.json configuration problems, Azure AD credential failures (AADSTS errors), port conflicts, or the agent not connecting in Teams or the Agents Playground. Use even if the user doesn't mention the SDK by name — trigger on symptoms like "my bot won't start", "getting 401s", or "bot isn't responding."
Debugging Agents Built with Microsoft Agents SDK (.NET)
Overview
Most agent failures fall into one of three categories: the code doesn't build or start, the configuration is wrong, or the agent isn't reachable. Work through this checklist in order — each step confirms a prerequisite for the next.
Checklist
You MUST create a task for each of these items and complete them in order:
Make sure the code builds successfully.
Make sure the application starts and runs without crashing.
Make sure the application opens a port and listens for incoming requests.
Validate the appsettings.json configuration.
Validate the bot's credentials against Azure AD.
Use the Agents Playground to test the agent end-to-end locally.
1. Build the code
dotnet build
Expected: exits with code 0, no errors. Fix any C# compile errors before continuing.
Agent is running, auth is active — this is correct for a configured agent
200
Agent is running with auth disabled (TokenValidation:Enabled = false) — correct for local dev
000 or connection refused
Agent is not running, wrong port, or crashed on startup
4. Validate appsettings.json configuration
Configuration mistakes are the most common source of failures. Check each area below.
4a. Confirm the file is being loaded
ASP.NET Core auto-loads appsettings.json and appsettings.{Environment}.json. Check that:
The file exists in the project root
It has "Copy to Output Directory": "PreserveNewest" in .csproj or is at the content root
ASPNETCORE_ENVIRONMENT is set correctly (Development for local dev)
4b. Check the Connections section structure
The SDK requires a specific JSON structure. Common mistakes:
// WRONG — flat format (this is Node.js env var style, not appsettings){"ClientId":"...","ClientSecret":"...","TenantId":"..."}// CORRECT{"Connections":{"ServiceConnection":{"Settings":{"AuthType":"ClientSecret","AuthorityEndpoint":"https://login.microsoftonline.com/<tenantId>","ClientId":"<appId>","ClientSecret":"<secret>","Scopes":["https://api.botframework.com/.default"]}}}}
4c. Check ConnectionsMap
If ConnectionsMap is present, it must be a JSON array with proper structure:
// WRONG — object instead of array"ConnectionsMap":{"ServiceUrl":"*","Connection":"ServiceConnection"}// CORRECT — array"ConnectionsMap":[{"ServiceUrl":"*","Connection":"ServiceConnection"}]
If omitted, the SDK defaults to mapping * to the first connection.
If the playground connects but messages don't get responses, the agent is running but a message handler may be missing. Add a fallback handler to confirm:
Using MapAgentEndpoints (compat) with AgentApplication
Switch to MapAgentApplicationEndpoints
MapAgentEndpoints 404
Using MapAgentApplicationEndpoints with ActivityHandler
Switch to MapAgentEndpoints
InvalidOperationException: No agent registered
Missing builder.AddAgent<T>()
Add builder.AddAgent<MyAgent>()
401 on every request
TokenValidation:Enabled is true with no/wrong credentials
Set to false for local dev, or fix credentials
System.Text.Json.JsonException on card deserialization
Wrong JSON structure in card content
Validate card JSON separately
OAuth sign-in card appears but token exchange fails
Wrong AzureBotOAuthConnectionName
Verify the connection name matches Azure Bot resource OAuth settings
Streaming chunks not appearing
Missing EndStreamAsync call
Always call await ctx.StreamingResponse.EndStreamAsync(ct) in a finally block
Validate an OAuth connection name
OAuth connection names can only be tested end-to-end through a real sign-in flow:
Azure Portal → Your Bot Resource → Settings → OAuth Connection Settings → [your connection] → Test Connection
This confirms the connection name matches, the OAuth app has the right scopes, and the redirect URI (https://token.botframework.com/.auth/web/redirect) is registered on the app registration.
Contributing
If 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.
