404 lines
9.9 KiB
Markdown
404 lines
9.9 KiB
Markdown
# 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!**
|