pip install mcp-agent-trace

from src.trace_engine import AgentTracer

# Start a trace session
tracer = AgentTracer()
tracer.start_trace(session_id="debug-auth-bug")

# Log events as the agent runs
tracer.log_event("tool_call", {"tool": "read_file", "path": "auth.py"})
tracer.log_event("tool_result", {"tool": "read_file", "tokens": 1200})
tracer.log_event("decision", {"chosen": "patch", "reason": "found bug on line 42"})
tracer.log_event("error", {"error": "patch failed", "retry": True})

# Get metrics
metrics = tracer.get_metrics()
print(f"Tokens: {metrics['total_tokens']:,}")
print(f"Tools:  {metrics['tool_calls']} calls")
print(f"Loops:  {metrics['loops_detected']}")

# Export for analysis
tracer.export_trace("debug-session.json")

model_call     — LLM API call (tokens, model, latency)
tool_call      — Agent invoking a tool
tool_result    — Tool response (size, duration)
decision       — Agent chose between options
error          — Exception or failure
milestone      — Task progress marker
user_input     — User message received
agent_response — Agent message sent

{
  "mcpServers": {
    "agent-trace": {
      "command": "python3",
      "args": ["-m", "src.server"]
    }
  }
}

=== TRACE: debug-auth-bug (8 events) ===
  [10:15:03] MODEL: claude-sonnet in=4200 out=180 ($0.0153)
  [10:15:04] CALL:  read_file({'path': 'auth.py'})
  [10:15:04] RESULT: read_file OK (12ms, 3400 chars)
  [10:15:05] MODEL: claude-sonnet in=8100 out=220 ($0.0273)
  [10:15:06] CALL:  patch({'path': 'auth.py', ...})
  [10:15:06] RESULT: patch OK (5ms, 150 chars)

=== SUMMARY ===
  Tokens: 12,300 in + 400 out
  Cost:   $0.0426
  Tools:  2 unique, 2 calls

python -m pytest tests/ -v  # 28 tests, all passing