agentic-flow 1.8.11 → 1.8.13

package/docs/federation/AGENT-DEBUG-STREAMING.md

@@ -0,0 +1,403 @@
+# 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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+const debug = createAgentDebugStream({
+  agentId: 'learning-agent',
+  timeline: true,
+});
+
+// After agent runs:
+debug.printTimeline(); // See complete sequence of events
+```
+
+### 3. Performance Profiling
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+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
+
+```bash
+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
+
+```bash
+# Maximum visibility
+DEBUG_LEVEL=TRACE \\
+DEBUG_TIMELINE=true \\
+DEBUG_TRACK_DECISIONS=true \\
+DEBUG_TRACK_COMMUNICATION=true \\
+npm start
+```
+
+### Debugging
+
+```typescript
+// 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
+
+```bash
+# 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!**