DebugAgent 0.5.1

.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.

Version Support

Multi-targets net8.0;net9.0;net10.0. Uses C# 12 features (primary constructors, raw string literals). RollForward: LatestMajor ensures compatibility with future versions.

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 (70 tools across 24 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.

Security (SecurityInspector)

Inspect authentication, authorization policies, and CORS configuration.

Error Tracking (ErrorTrackingInspector)

Track and analyze recent application errors and exception statistics.

Locks & Concurrency (LockInspector)

Diagnose thread pool starvation, lock contention, and async state issues.

Feature Flags (FeatureFlagInspector)

Inspect and evaluate feature flags at runtime.

Endpoint Testing (EndpointTestingInspector)

Test endpoints directly from within the running application.

Metrics (MetricsInspector)

Inspect system-level metrics, custom counters, and event counters.

File Handles (FileHandleInspector)

Monitor open file handles and handle limits.

Outbound HTTP (OutboundHttpInspector)

Track outbound HTTP calls made by the application.

Redis (RedisInspector)

Inspect Redis connection info and connection pool statistics.

WebSockets (WebSocketInspector)

Monitor active WebSocket connections and statistics.

CPU Profiler (CpuProfilerInspector) (v0.7.0)

Profile CPU usage and identify hot paths in managed code.

Memory Leak Detector (MemoryLeakInspector) (v0.7.0)

Detect memory leaks via GC heap snapshots and object graph analysis.

Deployment/Build Info (DeploymentInfoInspector) (v0.7.0)

Inspect build metadata, deployment environment, and .NET runtime version.

Snapshot & Diff (SnapshotDiffInspector) (v0.7.0)

Capture and compare runtime state snapshots to track changes over time.

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
    ├── SecurityInspector.cs          # Auth, authorization, CORS
    ├── ErrorTrackingInspector.cs     # Error tracking and stats
    ├── LockInspector.cs             # Locks, thread pool, async state
    ├── FeatureFlagInspector.cs      # Feature flags
    ├── EndpointTestingInspector.cs   # Endpoint testing
    ├── MetricsInspector.cs          # System metrics and counters
    ├── FileHandleInspector.cs       # File handle monitoring
    ├── OutboundHttpInspector.cs     # Outbound HTTP tracking
    ├── RedisInspector.cs            # Redis info and pool stats
    └── WebSocketInspector.cs        # WebSocket connections

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

Built With

This project was built using ggcode — an AI coding assistant for terminal-based development.

License

MIT