agent_debugger is a trace-first debugger for AI agents.
Instead of trying to understand an agent run from logs alone, it records the run as structured events. That gives you a timeline, a tree of parent and child actions, replay inputs, live streaming, and later analysis over the same captured run.
Today the repo is strongest at the local debugger loop:
- run the API
- instrument an agent with the SDK
- inspect sessions, events, checkpoints, and replay data
The main things you can inspect are:
- agent start and end
- decisions and reasoning
- LLM requests and responses
- tool calls and results
- errors
- checkpoints
- safety and policy events
This project is useful if you want to:
- understand why an agent chose a tool or answer
- inspect the sequence of model calls and tool calls
- debug failures with more structure than raw logs
- build replay, evaluation, or safety workflows on top of captured traces
TraceContextfor explicit tracing- decorators for lightweight instrumentation
- framework adapters for PydanticAI and LangChain
- FastAPI routes for sessions, traces, analysis, replay, and streaming
- a React frontend that reads the normalized backend trace bundle
The local path is the clearest supported workflow today.
Cloud-oriented configuration, auth, tenant isolation, and privacy work exist in the repo, but are not yet production-ready The docs in this folder try to separate:
- what works end to end now
- what exists but is still partial
- what is still planned
- Integration: how to instrument your code
- Progress: what is done and what is still partial
- How It Works: the runtime path from SDK to UI
- Architecture: the major layers and modules