Tagline: "Git blame for agent decisions."
AgentDecision is a lightweight Python library that captures, structures, and visualizes every decision an AI agent makes during execution. Add a single @trace decorator to your agent functions, and AgentDecision logs inputs, outputs, timing, and context for every step — then generates a human-readable decision tree viewable in a local web dashboard or exported as markdown.
When you wonder "why did my agent do that?", AgentDecision shows you exactly what happened and why.
AI agents make sequences of autonomous decisions that no one can explain after the fact. When a coding agent deletes the wrong file or a research agent ignores the best source, your debugging options are limited:
| Approach | Why It Fails |
|---|---|
print() debugging |
Unstructured. Lost after session ends |
| JSON log files | Takes 30 minutes to manually trace a 15-step session |
| LangSmith / Langfuse | Heavy integration, cloud-dependent, not designed for per-decision explainability |
| Re-run the agent | Non-deterministic. Might not reproduce the bug |
| Nothing | The default. Blind debugging |
AgentDecision fixes this. Install, decorate, run, open dashboard.
pip install agentdecisionDecorate your agent functions:
from agentdecision import trace
@trace(agent_name="research_agent")
def search_web(query: str) -> list:
# agent logic here
return results
@trace(agent_name="research_agent")
def summarize(paper: dict) -> str:
# agent logic here
return summaryRun your agent, then view the decision tree:
# Install the dashboard (optional, Flask-based)
pip install agentdecision[dashboard]
# Start the dashboard
agentdecision dashboard
# Opens at http://localhost:3333┌──────────────────────────────────────────────┐
│ User's Agent Code │
│ │
│ @trace(agent_name="research") │
│ def search_web(query): │
│ return results │
│ │
│ @trace(agent_name="research") │
│ def summarize(paper): │
│ return summary │
└──────────────────┬───────────────────────────┘
│ @trace captures:
│ - input arguments
│ - return value
│ - timestamp, duration
│ - exceptions
│ - call stack depth
▼
┌──────────────────────────────────────────────┐
│ AgentDecision Store │
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ sessions.db │ │ Async Writer │ │
│ │ (SQLite) │◄─│ (queue + │ │
│ │ │ │ batch flush) │ │
│ └───────┬────────┘ └────────────────┘ │
└──────────┼───────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ AgentDecision Dashboard │
│ │
│ CLI: agentdecision dashboard │
│ Serves at http://localhost:3333 │
│ │
│ Session List → Decision Timeline → Detail │
└──────────────────────────────────────────────┘
@tracedecorator — wraps any sync or async function, captures execution context with zero code changes. Usesfunctools.wrapsto preserve function metadata.- SQLite store — persists sessions and decisions to
~/.agentdecision/sessions.db. Writes are non-blocking (threaded queue with batch flush). - Web dashboard — local Flask app with a vanilla JS SPA. Browse sessions, inspect decision timelines, click any node for full input/output context.
- Markdown exporter — share decision logs in GitHub issues, PRs, or documents.
- Function name, module, agent name
- Input arguments (serialized, truncated at 10K chars)
- Return value (serialized, truncated at 10K chars)
- Start/end timestamps and duration (ms)
- Exception tracebacks (if raised)
- Call stack depth (for nested traces)
- Estimated token counts
from agentdecision import trace
@trace(agent_name="my_agent")
def my_step(context: str) -> str:
return call_llm(context)@trace(agent_name="researcher")
async def fetch_papers(query: str) -> list:
results = await search_api(query)
return results# Option 1: Environment variable
import os
os.environ["AGENTDECISION_ENABLED"] = "false"
# Option 2: Decorator argument
@trace(agent_name="my_agent", enabled=False)
def expensive_step(data: dict) -> dict:
return process(data)# Only trace up to 3 levels of nested calls
@trace(agent_name="my_agent", max_depth=3)
def outer(data):
return inner(data)from agentdecision import export_markdown
markdown = export_markdown("session-uuid-here")
print(markdown)Or via CLI:
agentdecision export <session-id>agentdecision listusage: agentdecision [-h] {list,dashboard,export} ...
positional arguments:
list List traced sessions
dashboard Start web dashboard (requires Flask)
export Export session as markdown
options:
-h, --help Show this help message
The web dashboard has three views:
- Sessions list — browse past traced sessions with agent name, date, duration, and status
- Decision timeline — vertical timeline of decisions. Each node shows function name, duration, and status
- Decision detail — click any node to see full input, output, metrics, and error details
Start it with:
agentdecision dashboard
# Opens at http://localhost:3333agentdecision/
├── pyproject.toml
├── README.md
├── LICENSE
├── agentdecision/
│ ├── __init__.py # Public API
│ ├── decorator.py # @trace decorator (sync + async)
│ ├── store.py # SQLite storage with async writer
│ ├── models.py # Session & Decision dataclasses
│ ├── exporter.py # Markdown export
│ ├── cli.py # CLI entry point
│ └── dashboard/
│ ├── server.py # Flask server
│ └── static/ # Vanilla JS SPA
│ ├── index.html
│ ├── app.js
│ └── styles.css
└── tests/
├── test_decorator.py
└── test_store.py
| Parameter | Default | Description |
|---|---|---|
agent_name |
"default" |
Name for the agent being traced |
enabled |
True |
Enable/disable tracing. Can also be set via AGENTDECISION_ENABLED env var |
truncation_limit |
10000 |
Max characters for serialized input/output previews |
max_depth |
None (unlimited) |
Maximum nested trace depth |
AGENTDECISION_ENABLED— set tofalse,0, ornoto disable all tracing globally
AgentDecision stores data in ~/.agentdecision/sessions.db (SQLite). The database is auto-capped at 100MB — oldest sessions are evicted when the limit is exceeded. All data stays local. No telemetry, no cloud sync. Delete the file to wipe all data.
# Core only (zero external dependencies)
pip install agentdecision
# With web dashboard
pip install agentdecision[dashboard]
# With development tools
pip install agentdecision[dev]Phase 1 (MVP) — Complete:
-
@tracedecorator (sync + async) - SQLite store with async writer
- Session tracking and decision tree model
- Web dashboard (session list, timeline, detail)
- Markdown export
- CLI with list, dashboard, export commands
Phase 2 (Planned):
- Decision reasoning extraction (optional LLM call on completion)
- Session filtering and search
- Auto-open dashboard after traced session
- LangChain/CrewAI integration adapters
- Decision diff/comparison between sessions
MIT