DebugAgent 0.2.3

.NET Debug Agent

An AI-powered runtime debugging agent that embeds directly into your ASP.NET Core application. Add one package reference, configure an LLM key, and chat with your live app at /agent to inspect DI services, configuration, health checks, logs, EF Core, cache, endpoints, memory, GC, and much more.

Quick Start

1. Add the agent to your project

<Project Sdk="Microsoft.NET.Sdk.Web">
  <ItemGroup>
    <ProjectReference Include="path/to/DebugAgent.csproj" />
  </ItemGroup>
</Project>

2. Register and map the agent

// Program.cs
using DebugAgents;

var builder = WebApplication.CreateBuilder(args);

// One line to register services
builder.Services.AddDebugAgent();

var app = builder.Build();

// One line to map endpoints
app.MapDebugAgent();

app.Run();

3. Set your LLM API key

# OpenAI
export OPENAI_API_KEY="sk-..."

# Or any OpenAI-compatible endpoint
export DEBUG_AGENT__LLM__API_KEY="your-key"
export DEBUG_AGENT__LLM__BASE_URL="https://api.openai.com/v1"
export DEBUG_AGENT__LLM__MODEL="gpt-4o"

4. Run and chat

dotnet run
# Open http://localhost:5000/agent

Inspectors & Tools (50+ tools across 10 inspectors)

DI Container (ServiceCollectionInspector)

Inspect the Microsoft.Extensions.DependencyInjection container — the heart of every ASP.NET Core app.

Configuration (ConfigurationInspector)

Inspect Microsoft.Extensions.Configuration — the unified config system (appsettings.json, env vars, CLI, etc.).

HTTP Endpoints (EndpointInspector)

Inspect ASP.NET Core endpoint routing — all registered routes from controllers and minimal APIs.

Health Checks (HealthCheckInspector)

Run and inspect Microsoft.Extensions.Diagnostics.HealthChecks.

Logging (LoggingInspector)

Query recent application logs captured by the built-in in-memory ring buffer (500 entries).

EF Core (EfCoreInspector)

Inspect Entity Framework Core DbContext registrations, entities, providers, and migrations. Uses reflection — no hard EF Core dependency.

Memory Cache (CacheInspector)

Inspect IMemoryCache contents via reflection.

Background Services (BackgroundServiceInspector)

Inspect IHostedService / BackgroundService implementations.

.NET Runtime (RuntimeInspector)

Inspect CLR runtime: memory, GC, thread pool, and process info.

HTTP Requests (HttpInspector)

Track HTTP requests passing through the middleware pipeline.

Configuration

{
  "DebugAgent": {
    "Enabled": true,
    "BasePath": "/agent",
    "Llm": {
      "Provider": "openai",
      "Model": "gpt-4o",
      "ApiKey": "",
      "BaseUrl": "https://api.openai.com/v1"
    }
  }
}

Or via environment variables:

DEBUG_AGENT__ENABLED=true
DEBUG_AGENT__BASE_PATH=/agent
DEBUG_AGENT__LLM__API_KEY=sk-...
DEBUG_AGENT__LLM__MODEL=gpt-4o

Demo Application

The demo/ directory contains a complete Order Management API that exercises every inspector:

• EF Core + SQLite — OrderDbContext with entity configuration and auto-seeded data
• DI Container — Services registered with all three lifetimes (Singleton, Scoped, Transient)
• Health Checks — Custom DatabaseHealthCheck + self-check
• IMemoryCache — Order caching with TTL and invalidation
• BackgroundService — OrderCleanupService for stale order cleanup
• FluentValidation — Input validation for order creation
• HttpClient Factory — Named client for external API calls
• Logging — Structured logging across multiple categories
• Configuration — appsettings.json with typed AppSettings binding

Run the demo

cd demo
export OPENAI_API_KEY="sk-..."
dotnet run

Then open http://localhost:5000/agent and try asking:

• "List all registered services"
• "Show me recent logs"
• "What's the health status?"
• "What endpoints are available?"
• "Show me EF Core DbContext info"
• "What's in the memory cache?"

Demo API Endpoints

Architecture

DebugAgent/
├── AgentContext.cs          # Static IServiceProvider holder
├── Config.cs                # AgentConfig + LLMConfig
├── DebugEngine.cs           # LLM orchestration with tool calling
├── LLMClient.cs             # OpenAI-compatible HTTP client
├── ToolRegistry.cs          # [DebugTool] auto-discovery + schema gen
├── ChatPage.cs              # Embedded chat UI (single HTML page)
├── LogCapture.cs            # In-memory log ring buffer (500 entries)
├── Middleware.cs            # AddDebugAgent() + MapDebugAgent() extensions
└── Inspectors/
    ├── RuntimeInspector.cs          # Memory, GC, thread pool
    ├── HttpInspector.cs             # HTTP request tracking
    ├── ServiceCollectionInspector.cs # DI container
    ├── ConfigurationInspector.cs    # IConfiguration
    ├── EndpointInspector.cs         # Route endpoints
    ├── HealthCheckInspector.cs      # Health checks
    ├── LoggingInspector.cs          # Log capture and search
    ├── EfCoreInspector.cs           # EF Core DbContext
    ├── CacheInspector.cs            # IMemoryCache
    └── BackgroundServiceInspector.cs # IHostedService

How It Works

1. AddDebugAgent() captures the DI service collection snapshot and registers DebugEngine, InMemoryLoggerProvider, and AgentConfig

2. MapDebugAgent() initializes AgentContext with the WebApplication and maps two endpoints:

   • GET /agent — Chat UI
   • POST /agent/api/chat — SSE streaming chat

3. ToolRegistry auto-discovers all [DebugTool] methods via reflection at startup

4. DebugEngine uses function calling to let the LLM invoke tools, gather data, and explain findings

License

MIT