When your agents fail, xDebug tells you why

AI Agent Debugging Tools

xDebug reduces debugging time by up to 60% for AI agent systems built on the private.me platform. It eliminates cryptic error codes with actionable fix suggestions, simplifies performance analysis with sub-millisecond profiling, and protects session context for reproducing intermittent failures.

Designed for developers building multi-agent applications with @private.me/xbind, xDebug saves you hours of log-tracing by capturing execution context across async operations, converting framework errors into human-readable explanations, and identifying bottlenecks in real time — all with less than 1% overhead in production.

Agent developers spend 60% of their time debugging opaque errors — a 60% reduction in debug time is possible

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.

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.

5 Debug Capabilities

3-Step Integration

1. Install Package

npm install @private.me/xdebug

2. Error Explainer (Basic)

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

try {
  await agent.send({ to, payload });
} catch (error) {
  const explanation = explainError(error);
  console.log('Why:', explanation.why);
  console.log('Fix:', explanation.how.join('; '));
  console.log(formatExplanation(explanation));
}

3. Performance Profiler (Advanced)

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

const profiler = new Profiler();

profiler.start('agent-send');
await agent.send({ to, payload });
profiler.end('agent-send');

const report = profiler.getReport();
report.measurements.forEach(m =>
  console.log(`${m.label}: mean=${m.mean.toFixed(1)}ms p95=${m.p95.toFixed(1)}ms`)
);

Live Debug Tracing

Performance Profiling

CLI Tools

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

Dev Command - Live Watch Mode

# 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.send() 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

How xDebug Works

xDebug uses a lightweight event-capture architecture that hooks into the private.me SDK at the transport, envelope, and agent layers without modifying application code.

The architecture consists of three layers: (1) Event Capture Layer — hooks into xBind transport, envelope creation, and agent lifecycle events with 0.02ms per-event overhead; (2) Analysis Engine — processes captured events through the Error Explainer, Profiler, and Session Debugger modules to produce structured diagnostics; (3) Output Layer — renders results to CLI, JSON exports, or session files for team collaboration.

All captured data stays local by default. No telemetry is sent externally. Session files can be shared with teammates for collaborative debugging, and all exports are stripped of sensitive cryptographic material before serialization.

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.

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

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

  // Log for ops team
  logger.error({
    why: explanation.why,
    fix: explanation.how,
    docs: explanation.docs
  });

  // Pretty-print for developer
  console.log(formatExplanation(explanation));
}

Performance Optimization

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

const profiler = new Profiler();

profiler.start('dataset-processing');
await processLargeDataset(agent, dataset);
profiler.end('dataset-processing');

const report = profiler.getReport();

// Identify slow operations by percentile
report.measurements.forEach(m => {
  if (m.p95 > 1000) console.warn(`Bottleneck: ${m.label} p95=${m.p95}ms`);
});

Multi-Agent Communication Debugging

Distributed workflow with multiple agents. Use the Debugger to trace agent-to-agent communication, capture message flows, and identify failures.

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

const dbg = new Debugger({ enabled: true, minLevel: 'debug' });
dbg.startSession({ sessionId: 'multi-agent-001', agentId: 'coordinator' });

// Trace distributed workflow — log each dispatch as a debug event
dbg.info('send', 'Dispatching to worker-1', { target: 'worker-1', task: 'task1' });
await dispatch('worker-1', task1);

dbg.info('send', 'Dispatching to worker-2', { target: 'worker-2', task: 'task2' });
await dispatch('worker-2', task2);

// Analyze captured events
const errors = dbg.getEvents({ level: 'error' });
console.log(`Errors: ${errors.length}`);
dbg.endSession();

Session Replay

Agent execution fails intermittently. Use the Debugger to capture full execution context and export sessions for later analysis.

import { Debugger } from '@private.me/xdebug';
import { writeFileSync } from 'node:fs';

const dbg = new Debugger({ enabled: true, minLevel: 'debug' });
dbg.startSession({ sessionId: 'incident-20260427', agentId: 'main' });

try {
  await runComplexWorkflow(agent);
} catch (error) {
  dbg.error('workflow', error.message, error);

  // Export for later analysis
  const json = dbg.export({ format: 'json' });
  writeFileSync('./debug-sessions/incident-20260427.json', json);
}
dbg.endSession();

Core APIs

Types

interface ErrorExplanation {
  what: string;             // What happened (plain English)
  why: string;              // Root cause analysis
  how: string[];            // Actionable fix steps
  examples: CodeExample[];  // Code examples showing the fix
  docs: string[];           // Documentation links
  code: string;             // Error code for reference
}

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;
}

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

Use the Debugger to trace AutoGPT agent communication. Capture events across autonomous agent workflows and export session logs.

CrewAI Integration

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

Common Issues

Issue: "Timer already running"

Cause: Calling profiler.start(label) when a timer with that label is already active.

// Check before starting
if (!profiler.isActive('my-timer')) {
  profiler.start('my-timer');
}

Issue: "Session export too large"

Cause: Too many events accumulated in the debugger.

// Filter events before export
const errors = dbg.getEvents({ level: 'error' });
console.log('Error count:', errors.length);

// Export then clear to free memory
const json = dbg.export({ format: 'json' });
dbg.clear();

Issue: "High memory usage during profiling"

Cause: Long-running sessions accumulating events.

// Periodically export and clear
setInterval(() => {
  const json = dbg.export({ format: 'jsonl' });
  appendFileSync('./debug.jsonl', json);
  dbg.clear(); // Free memory
}, 60000); // Every 60 seconds

Secure by Design

xDebug is built with the same security principles as the private.me platform. Debug data never leaves your machine unless you explicitly export it.

All session captures are stored locally and encrypted at rest. Exported session files automatically redact private keys, HMAC secrets, and XorIDA share data before serialization. The profiler operates in a read-only mode — it observes execution without modifying agent state or intercepting live messages. In production environments, xDebug can be configured to capture only error events, minimizing the attack surface while maintaining diagnostic capability.

Free for All Developers

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

pnpm add @private.me/xdebug