mcp-agent-trace 1.0.0

Agent tracing: step-by-step execution traces for AI agent debugging

MCP Agent Trace — Observability for AI Agent Loops

Record agent events, build trace trees, compute metrics, detect loops, and export traces. Zero dependencies, pure Python stdlib.

The Problem

Agent decisions are black boxes. No way to trace what happened, what tokens were spent on, where loops occurred. Debugging agent failures requires guessing.

The Solution

MCP Agent Trace records structured events throughout the agent loop, builds hierarchical trace trees, computes token/latency metrics, detects repeated action patterns, and exports full traces as JSON.

Tools (12)

Tool	What it does
start_trace	Begin a new trace session
end_trace	End session, compute summary metrics
log_event	Record a structured event (tool_call, decision, error, milestone)
get_trace	Get full trace tree for a session
get_metrics	Token usage, tool calls, latency, loop detection
detect_loops	Find repeated tool-call patterns
export_trace	Export as JSON for external analysis
list_sessions	List all trace sessions
get_timeline	Chronological event timeline
annotate	Add human annotation to an event
get_stats	Aggregate statistics across sessions
reset	Clear all sessions and traces

Tests

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

Inspiration

• AgentDoG — Diagnostic guardrails
• Azure SRE Agent observability — 35k incidents traced
• LangChain middleware — Agent loop hooks
• The Design Space of Today's AI Agent Systems — 27-event-type hook pipeline

License

MIT — aaameobius-crypto