Marc Rejohn Castillano 5cb6561924 added ruflo

2026-04-09 19:01:53 +08:00

9.9 KiB

Raw Blame History

Single Agent Debug Streaming

Version: 1.0.0 Date: 2025-11-01 Status: ✅ Production Ready

🔍 Overview

Track a single agent's complete lifecycle with detailed visibility into every operation, decision, and state change.

Perfect for: Understanding agent behavior, debugging issues, performance tuning, learning how agents work.

✨ What You Get

Agent Lifecycle Tracking

Spawning → Initializing → Ready → Working → Idle → Shutting Down → Dead
Automatic phase transitions
Timestamp every change
Context for each phase

Task Execution Tracing

Task start/complete/fail
Individual step tracking
Duration measurement
Result capture
Error logging

Decision Logging

What decisions the agent makes
Available options
Selected choice
Reasoning
Confidence scores

Communication Tracking

Messages sent
Messages received
Target agents
Message types and sizes

Performance Metrics

Operation timing
Step duration
Task completion time
Average/min/max calculations
Automatic aggregation

Timeline Visualization

Chronological event log
Elapsed time markers
Complete agent history

🚀 Quick Start

Basic Usage

import { createAgentDebugStream, DebugLevel } from 'agentic-flow/federation/debug/agent-debug-stream';

// Create debug stream for your agent
const agentDebug = createAgentDebugStream({
  agentId: 'my-agent-001',
  tenantId: 'my-team',
  level: DebugLevel.VERBOSE,
  timeline: true,
});

// Track lifecycle
agentDebug.logInitialization({ type: 'researcher' });
agentDebug.logReady();

// Track task
agentDebug.startTask('task-001', 'Research AI safety');
agentDebug.logTaskStep('task-001', 0, 'web_search', { query: '...' });
agentDebug.completeTaskStep('task-001', 0, 200);
agentDebug.completeTask('task-001', { findings: [...] });

// Track decision
agentDebug.logDecision(
  'select_source',
  [{ name: 'arxiv', score: 0.95 }, { name: 'scholar', score: 0.87 }],
  { name: 'arxiv', score: 0.95 },
  'Highest relevance',
  0.95
);

// Track communication
agentDebug.logCommunication('send', 'other-agent', { type: 'data', payload: {...} });

// Print summary
agentDebug.printSummary();
agentDebug.printTimeline();

📊 Sample Output

Phase Transitions

[2025-11-01T14:00:00.000Z] BASIC  AGENT_LIFECYCLE phase_initializing
  Data: {
    "old_phase": "spawning",
    "new_phase": "initializing",
    "config": { "type": "researcher" }
  }

📍 Phase Change: spawning → initializing

Task Execution

[2025-11-01T14:00:01.000Z] VERBOS TASK task_start
  Data: {
    "taskId": "research-001",
    "description": "Research AI safety frameworks"
  }

[2025-11-01T14:00:01.050Z] VERBOS TASK_STEP web_search
  Data: {
    "taskId": "research-001",
    "step": 0,
    "query": "AI safety frameworks 2024"
  }

[2025-11-01T14:00:01.250Z] VERBOS TASK_STEP step_complete
  Data: {
    "taskId": "research-001",
    "step": 0,
    "duration": 200,
    "results_found": 15
  }

Decision Logging

[2025-11-01T14:00:02.000Z] VERBOS DECISION decision_made
  Data: {
    "context": "select_papers_to_analyze",
    "options_count": 3,
    "selected": { "title": "Paper A", "relevance": 0.95 },
    "reasoning": "Highest relevance score",
    "confidence": 0.95
  }

🤔 Decision Made: select_papers_to_analyze → {"title":"Paper A","relevance":0.95}

Agent Summary

============================================================
📊 Agent Summary: research-agent-001
============================================================

Uptime:          1.68s
Tasks Completed: 2
Tasks Failed:    0
Decisions Made:  1
Messages Sent:   1
Messages Recv:   1

Performance Metrics:
------------------------------------------------------------
  step_web_search                1x  avg: 200.0ms  min: 200.0ms  max: 200.0ms
  step_analyze_document          1x  avg: 300.0ms  min: 300.0ms  max: 300.0ms
  memory_store                   1x  avg: 15.0ms  min: 15.0ms  max: 15.0ms
  task_completion                2x  avg: 538.0ms  min: 151.0ms  max: 925.0ms

============================================================

Timeline View

============================================================
📅 Agent Timeline
============================================================

  +0.000s | phase_change         | {"from":"spawning","to":"initializing"}
  +0.100s | phase_change         | {"from":"initializing","to":"ready"}
  +0.200s | phase_change         | {"from":"ready","to":"working"}
  +0.250s | task_start           | {"taskId":"research-001"}
  +1.100s | task_complete        | {"taskId":"research-001","duration":925}
  +1.150s | phase_change         | {"from":"working","to":"idle"}

============================================================

🎯 Use Cases

1. Debug a Failing Agent

const debug = createAgentDebugStream({
  agentId: 'buggy-agent',
  level: DebugLevel.TRACE, // Maximum detail
  trackDecisions: true,
});

// When task fails, you'll see:
// - Exact phase when failure occurred
// - All decisions leading to failure
// - Complete stack of operations
// - Performance metrics showing slow operations

2. Understand Agent Behavior

const debug = createAgentDebugStream({
  agentId: 'learning-agent',
  timeline: true,
});

// After agent runs:
debug.printTimeline(); // See complete sequence of events

3. Performance Profiling

const debug = createAgentDebugStream({
  agentId: 'slow-agent',
  level: DebugLevel.DETAILED,
});

// Track every operation with timing
// Metrics show which operations are slow
debug.printSummary(); // See performance breakdown

4. Multi-Agent Coordination

// Track each agent individually
const agent1Debug = createAgentDebugStream({ agentId: 'agent-1' });
const agent2Debug = createAgentDebugStream({ agentId: 'agent-2' });
const agent3Debug = createAgentDebugStream({ agentId: 'agent-3' });

// See exactly how they interact
agent1Debug.logCommunication('send', 'agent-2', {...});
agent2Debug.logCommunication('receive', 'agent-1', {...});

🔧 Configuration

AgentDebugConfig Options

interface AgentDebugConfig {
  agentId: string;                    // Required: Agent identifier
  tenantId?: string;                   // Optional: Tenant ID
  level?: DebugLevel;                  // Verbosity level (default: VERBOSE)
  format?: 'human' | 'json' | 'compact' | 'timeline';
  output?: 'console' | 'file' | 'both';
  outputFile?: string;                 // File path for output
  colorize?: boolean;                  // Color-coded output (default: true)
  trackState?: boolean;                // Track state changes (default: true)
  trackDecisions?: boolean;            // Log decisions (default: false)
  trackCommunication?: boolean;        // Log messages (default: false)
  timeline?: boolean;                  // Build timeline (default: false)
}

Environment Variables

DEBUG_LEVEL=VERBOSE                 # Verbosity level
DEBUG_FORMAT=human                  # Output format
DEBUG_OUTPUT=console                # Output destination
DEBUG_TRACK_DECISIONS=true          # Enable decision tracking
DEBUG_TRACK_COMMUNICATION=true      # Enable communication tracking
DEBUG_TIMELINE=true                 # Enable timeline

📚 API Reference

AgentDebugStream Methods

Lifecycle

logAgentPhase(phase, data?) - Log phase change
logInitialization(config) - Log agent initialization
logReady(capabilities?) - Log agent ready
logShutdown(reason?) - Log shutdown

Tasks

startTask(taskId, description, data?) - Start tracking task
logTaskStep(taskId, step, operation, data?) - Log task step
completeTaskStep(taskId, step, duration, data?) - Complete step
completeTask(taskId, result?) - Complete task
failTask(taskId, error) - Mark task as failed

Decisions & Communication

logDecision(context, options, selected, reasoning?, confidence?) - Log decision
logCommunication(type, target, message) - Log send/receive
logMemoryOperation(operation, data, duration?) - Log memory ops
logThought(thought, context?) - Log reasoning

Reporting

printSummary() - Print agent summary
printTimeline() - Print chronological timeline
getState() - Get current state
getTasks() - Get task history
getDecisions() - Get decision history
getCommunications() - Get communication history

🎓 Best Practices

Development

# Maximum visibility
DEBUG_LEVEL=TRACE \\
DEBUG_TIMELINE=true \\
DEBUG_TRACK_DECISIONS=true \\
DEBUG_TRACK_COMMUNICATION=true \\
npm start

Debugging

// Enable all tracking
const debug = createAgentDebugStream({
  agentId: agent.id,
  level: DebugLevel.TRACE,
  trackDecisions: true,
  trackCommunication: true,
  timeline: true,
});

// Subscribe to events
debug.on('phase_change', (data) => {
  if (data.to === 'failed') {
    console.error('AGENT FAILED!', data);
  }
});

Production

# Minimal overhead
DEBUG_LEVEL=BASIC \\
DEBUG_FORMAT=json \\
DEBUG_OUTPUT=file \\
DEBUG_OUTPUT_FILE=/var/log/agent.log \\
npm start

✅ Summary

Single Agent Debug Streaming provides:

✅ Complete lifecycle tracking (spawn → shutdown) ✅ Task execution tracing with steps ✅ Decision logging with reasoning ✅ Communication tracking (send/receive) ✅ Memory operation logging ✅ Performance metrics (automatic) ✅ Timeline visualization ✅ Automatic summaries ✅ Event subscriptions ✅ Production-ready

Perfect for:

Debugging agent behavior
Understanding decision-making
Performance profiling
Learning how agents work
Multi-agent coordination debugging

Version: 1.0.0 Last Updated: 2025-11-01 Status: ✅ Production Ready

🔍 Track your agents with complete visibility!

9.9 KiB Raw Blame History

Single Agent Debug Streaming

🔍 Overview

✨ What You Get

Agent Lifecycle Tracking

Task Execution Tracing

Decision Logging

Communication Tracking

Performance Metrics

Timeline Visualization

🚀 Quick Start

Basic Usage

📊 Sample Output

Phase Transitions

Task Execution

Decision Logging

Agent Summary

Timeline View

🎯 Use Cases

1. Debug a Failing Agent

2. Understand Agent Behavior

3. Performance Profiling

4. Multi-Agent Coordination

🔧 Configuration

AgentDebugConfig Options

Environment Variables

📚 API Reference

AgentDebugStream Methods

Lifecycle

Tasks

Decisions & Communication

Reporting

🎓 Best Practices

Development

Debugging

Production

✅ Summary

9.9 KiB

Raw Blame History