Metadata-Version: 2.4
Name: mcp-agent-trace
Version: 1.0.0
Summary: Agent tracing: step-by-step execution traces for AI agent debugging
Author: aaameobius-crypto
License: MIT
Project-URL: Homepage, https://github.com/aaameobius-crypto/darkbot-ai-templates
Project-URL: Repository, https://github.com/aaameobius-crypto/darkbot-ai-templates
Keywords: mcp,ai,agent,harness,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

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

## Inspiration

- [AgentDoG](https://arxiv.org/abs/2601.18491) — Diagnostic guardrails
- [Azure SRE Agent observability](https://techcommunity.microsoft.com/blog/appsonazureblog/how-we-build-azure-sre-agent-with-agentic-workflows/4508753) — 35k incidents traced
- [LangChain middleware](https://blog.langchain.com/how-middleware-lets-you-customize-your-agent-harness/) — Agent loop hooks
- [The Design Space of Today's AI Agent Systems](https://arxiv.org/abs/2604.14228) — 27-event-type hook pipeline

## License

MIT — aaameobius-crypto
