ACI 206 — DEBUG SUITE

When your agents fail, xDebug tells you why

Developer tools for debugging AI agent interactions. Capture, trace, and analyze execution flow in AI agent systems with error explanation, performance profiling, message flow tracing, and session debugging.

Error Diagnosis Performance Profiling Message Tracing Session Replay

THE PROBLEM

Agent developers spend 60% of their time debugging opaque errors

AI agents fail in production with cryptic errors. Multi-agent workflows hide bottlenecks. Message flows span multiple services. Execution context disappears across async operations.

Traditional debugging tools were not built for AI agent systems. Logs are scattered across services. Stack traces point to framework internals, not your code. Performance bottlenecks hide in distributed workflows. Error messages expose implementation details without explaining root causes.

COMMON SCENARIO

Production agent fails with "SIGNATURE_INVALID" at 3 AM. No context. No stack trace pointing to the actual problem. You spend hours tracing through async operations, multiple agents, and distributed message flows to find a simple timestamp drift issue.

THE SOLUTION

Error explainer. Profiler. Message tracer. CLI tools.

xDebug provides developer tools specifically designed for AI agent systems built with the Private.Me SDK. Convert cryptic errors into actionable fixes. Identify bottlenecks in multi-agent workflows. Visualize agent-to-agent communication. Capture full execution context across async operations.

Debug Capabilities

0.02ms

Event Capture

<1%

Profiler Overhead

CAPABILITIES

5 Debug Capabilities

DIAGNOSIS

Error Explainer

Convert cryptic errors into actionable fixes with error codes, human-readable descriptions, and suggested remediation steps.

PERFORMANCE

Performance Profiler

Identify bottlenecks in multi-agent workflows with duration tracking, event capture, and slowness detection.

TRACING

Message Flow Tracer

Visualize agent-to-agent communication with message tracking, latency measurement, and failure analysis.

SESSION

Session Debugger

Capture full execution context across async operations with session recording, event logging, and replay capability.

CALL GRAPH BUILDER

Map function call hierarchies for complex flows. Visualize nested agent operations, trace execution paths, and identify circular dependencies.

QUICK START

3-Step Integration

1. Install Package

BASH

npm install @private.me/xdebug

2. Error Explainer (Basic)

TYPESCRIPT

import { explainError } from '@private.me/xdebug';

try {
  await agent.send({ to, payload });
} catch (error) {
  const explanation = await explainError(error);
  console.error(explanation.message);
  console.log('Suggested fixes:', explanation.remediation);
}

3. Session Profiler (Advanced)

TYPESCRIPT

import { Profiler } from '@private.me/xdebug';

const profiler = new Profiler({ sessionId: 'debug-001' });
profiler.start();

await agent.send({ to, payload });

const report = profiler.stop();
console.log(`Total duration: ${report.duration}ms`);
console.log(`Events captured: ${report.events.length}`);

MESSAGE FLOW TRACER

Attach the tracer to your agents and all messages are automatically tracked. No manual instrumentation required.

See It In Action

Live Debug Tracing

$ xdebug trace --session abc123

      ✓ Agent initialized: did:key:z6MkrP...
    
      ✓ Message sent → payments-service (12ms)
    
      ✗ ERROR: SIGNATURE_INVALID
    
      → Timestamp drift detected: +35 seconds
    
      → Fix: Sync system clock or increase tolerance window

Performance Profiling

AVG LATENCY

12ms

ERROR RATE

0.3%

TOTAL CALLS

1,247

DEVELOPER TOOLS

CLI Tools

Live watch mode with real-time metrics for your codebase. Track agent.call() patterns, error rates, latency, and recent errors automatically.

Dev Command - Live Watch Mode

BASH

# Watch current directory
xdebug dev

# Watch specific directory
xdebug dev --path ./src

# Enable verbose logging
xdebug dev --verbose

# Custom polling interval
xdebug dev --interval 500

Metrics Displayed

Total agent.call() count across all files
Error count (calls within try/catch blocks)
Error rate percentage
Average latency (extracted from timing patterns)
Recent errors with timestamps and file locations

AUTOMATIC RELOAD

File watching with automatic reload. Changes to your codebase update the dashboard in real-time without restarting the dev server.

USE CASES

Real-World Scenarios

Production Error Diagnosis

Production agent fails with cryptic error. Use explainError() to convert the error into actionable debug information with error codes, human-readable descriptions, and suggested remediation steps.

TYPESCRIPT

import { explainError, ErrorDetail } from '@private.me/xdebug';

try {
  await agent.send({ to: 'did:key:z6Mk...', payload: sensitiveData });
} catch (error) {
  const detail: ErrorDetail = await explainError(error, {
    includeContext: true,
    suggestRemediation: true
  });

  // Log for ops team
  logger.error({
    code: detail.code,
    type: detail.type,
    message: detail.message,
    remediation: detail.remediation,
    timestamp: detail.timestamp
  });
}

Performance Optimization

Multi-agent workflow running slowly. Use the Profiler to capture performance metrics, identify bottlenecks, and analyze slow operations.

TYPESCRIPT

const profiler = new Profiler({
  context: {
    sessionId: crypto.randomUUID(),
    agentId: agent.did,
    environment: 'production'
  }
});

profiler.start();
await processLargeDataset(agent, dataset);
const report = profiler.stop();

// Identify slow operations
const slowEvents = report.events.filter(e => e.duration > 1000);
console.log('Bottlenecks:', slowEvents);

Multi-Agent Communication Debugging

Distributed workflow with multiple agents. Use MessageTracer to track agent-to-agent communication, analyze message flows, and identify failed messages.

TYPESCRIPT

import { MessageTracer } from '@private.me/xdebug';

const tracer = new MessageTracer();

// Attach to all agents in system
tracer.attach(coordinatorAgent);
tracer.attach(workerAgent1);
tracer.attach(workerAgent2);

// Run distributed workflow
await coordinatorAgent.send({ to: workerAgent1.did, payload: task1 });
await coordinatorAgent.send({ to: workerAgent2.did, payload: task2 });

// Analyze communication patterns
const flows = tracer.getFlows();
const failedMessages = flows.filter(f => f.status === 'failed');
const avgLatency = flows.reduce((sum, f) => sum + (f.latency || 0), 0) / flows.length;

console.log(`Failed: ${failedMessages.length}/${flows.length}`);

Session Replay

Agent execution fails intermittently. Use session recording to capture full execution context and export for later analysis.

TYPESCRIPT

import { DebugSession, exportSession } from '@private.me/xdebug';

const profiler = new Profiler({ sessionId: 'incident-20260427' });
profiler.start();

try {
  await runComplexWorkflow(agent);
} catch (error) {
  const session = profiler.getSession();

  // Export for later analysis
  await exportSession(session, {
    format: 'json',
    includeStackTraces: true,
    includeContext: true,
    path: './debug-sessions/incident-20260427.json'
  });
}

API REFERENCE

Core APIs

explainError(error, options?): Promise<ErrorDetail>

Convert errors into actionable debug information. Returns error code, human-readable message, error type category, stack trace, timestamp, and suggested remediation steps.

class Profiler

Capture performance metrics and execution events. Methods: start(), stop(), getSession(), addEvent(). Use for performance profiling and bottleneck identification.

class MessageTracer

Track agent-to-agent communication. Methods: attach(agent), detach(agent), getFlows(filter?), clear(). Automatically captures message flows with latency tracking.

exportSession(session, config): Promise<void>

Export debug sessions for analysis. Supports JSON, JSONL, CSV, HTML formats. Options for stack traces, context metadata, payloads, and filtering.

Types

TYPESCRIPT

interface ErrorDetail {
  code: string;              // Error code (e.g., SIGNATURE_INVALID)
  message: string;           // Human-readable description
  type: string;              // Category (auth, network, crypto, validation)
  stack?: string;           // Stack trace if available
  timestamp: string;        // When error occurred
  remediation: string[];     // Suggested fix steps
}

interface DebugEvent {
  id: string;
  timestamp: string;
  level: DebugLevel;
  category: string;
  message: string;
  data?: Record<string, unknown>;
  stack?: string;
  agentId?: string;
  sessionId?: string;
}

interface DebugSession {
  id: string;
  context: DebugContext;
  startedAt: string;
  endedAt?: string;
  events: DebugEvent[];
  status: 'active' | 'completed' | 'failed' | 'timeout';
  duration?: number;
}

INTEGRATION

Framework Integration

xDebug integrates with popular AI agent frameworks. Works with LangChain, AutoGPT, CrewAI, and any system built with the Private.Me SDK.

LangChain Integration

Wrap LangChain agents with xDebug profiling and error explanation. Automatically capture execution events and convert errors.

AutoGPT Integration

Attach MessageTracer to AutoGPT agents for message flow visualization. Track communication between autonomous agents.

CrewAI Integration

Use the Profiler to identify bottlenecks in CrewAI multi-agent workflows. Export sessions for team debugging.

PRIVATE.ME SDK

Built specifically for agents created with @private.me/xlink. Error codes, message formats, and tracing hooks are SDK-native for zero-friction integration.

TROUBLESHOOTING

Common Issues

Issue: "Cannot attach tracer to agent"

Cause: Agent instance not compatible with tracer.

FIX

// Ensure agent is from @private.me/xlink
import { Agent } from '@private.me/xlink';
const agent = await Agent.quickstart();
tracer.attach(agent); // Now works

Issue: "Session export too large"

Cause: Too many events or large payloads.

FIX

// Apply filters before export
await exportSession(session, {
  format: 'json',
  filter: {
    level: 'error', // Only errors
    timeRange: { start: '2026-04-27T10:00:00Z', end: '2026-04-27T11:00:00Z' }
  },
  includePayloads: false // Exclude payloads
});

Issue: "High memory usage during profiling"

Cause: Long-running sessions accumulating events.

FIX

// Stop profiler periodically and export
setInterval(() => {
  const report = profiler.stop();
  exportSession(report, { format: 'jsonl', path: './debug.jsonl' });
  profiler.start(); // Resume profiling
}, 60000); // Every 60 seconds

PRODUCTION GUIDELINES

Enable only for specific sessions. Set includePayloads: false for exports. Implement log retention policies (auto-delete after 7 days). Restrict access to debug endpoints.

GET STARTED

Free for All Developers

xDebug is a free developer tool. No credit card required, no trial period, no subscription. Install and start debugging immediately.

OPEN TO ALL

xDebug is part of the Private.Me platform's commitment to developer tools. Use it in personal projects, commercial applications, or enterprise environments without cost.

pnpm add @private.me/xdebug