agents-sdk-dotnet-debugging

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:

1. Make sure the code builds successfully.
2. Make sure the application starts and runs without crashing.
3. Make sure the application opens a port and listens for incoming requests.
4. Validate the appsettings.json configuration.
5. Validate the bot's credentials against Azure AD.
6. 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.

Common build errors:

• Missing package — dotnet add package Microsoft.Agents.Hosting.AspNetCore
• Namespace not found — wrong using statement; see the agents-sdk-dotnet skill for correct namespaces
• Target framework mismatch — Agents SDK requires .NET 8+; check <TargetFramework> in .csproj

2. Start the application

Run with detailed logging:

dotnet run

Or with verbose logging:

dotnet run --verbosity detailed

To enable debug-level SDK logging, add to appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "Microsoft.Agents": "Debug",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Watch for crash output. Common startup errors:

• Unable to resolve service for type 'IStorage' — missing builder.Services.AddSingleton<IStorage, MemoryStorage>() in Program.cs
• AddAgentAspNetAuthentication missing — add builder.Services.AddAgentAspNetAuthentication(builder.Configuration)
• Port already in use — another process is on the port; check with netstat -ano | findstr :3978 (Windows) or lsof -i :3978 (macOS/Linux)
• InvalidOperationException on startup — check appsettings.json structure, especially Connections and ConnectionsMap