---

The Problem

You build an AI agent. It calls an LLM, uses tools, chains prompts together. Then it hallucinates, loops infinitely, or silently drops context — and you have no idea where it went wrong.

Every other observability tool requires accounts, API keys, cloud dashboards, and framework-specific setup. You just want to see what happened.

The Solution

import agenttrace.auto  # ← That's it. One line.

# ... your existing agent code runs normally ...
# When it finishes, a local dashboard opens automatically at localhost:8000

AgentTrace intercepts every LLM call, tool execution, and unhandled crash — then serves a beautiful local timeline you can replay step-by-step.

---

✨ Features

🪄 True Zero-Config

Add import agenttrace.auto to the top of your script. No API keys, no accounts, no cloud. Works with OpenAI, Groq, LangChain, and CrewAI out of the box.

🧠 Smart Auto-Judge

AgentTrace doesn't just show you what happened — it tells you what went wrong:

Evaluation	How It Works	Cost
🔁 Loop Detection	Flags 3+ identical consecutive tool calls	Free (pure Python)
💰 Cost Anomaly	Flags steps using >2x average tokens	Free (pure Python)
⏱️ Latency Regression	Flags steps >3x slower than average	Free (pure Python)
🔧 Tool Misuse	Detects wrong arguments or failed tool calls	LLM-powered (optional)
📝 Instruction Drift	Detects when LLM ignores the system prompt	LLM-powered (optional)

LLM-powered checks require a free Groq API key. Install with pip install "agenttrace-ai[judge]".

▶️ Trace Replay

Press Play and watch your agent's execution animate step-by-step — like a video recording of its thought process. Drag the scrubber to jump to any moment. Flagged steps pulse red.

💥 Crash Detection

If your agent throws an unhandled exception, AgentTrace catches it and logs the full traceback as a trace step — so you never lose debugging data.

🔌 Framework Support

Framework	Status	Setup Required
OpenAI SDK	✅ Native	pip install "agenttrace-ai[openai]"
Groq SDK	✅ Native	pip install "agenttrace-ai[openai]"
LangChain	✅ Adapter	None (auto-detected)
CrewAI	✅ Adapter	None (auto-detected)

---

🚀 Quickstart

Install

# Core (works with LangChain out of the box)
pip install agenttrace-ai

# With OpenAI/Groq support
pip install "agenttrace-ai[openai]"

# With everything (OpenAI + Auto-Judge + LangChain)
pip install "agenttrace-ai[all]"

Basic Usage (OpenAI / Groq)

import agenttrace.auto  # ← Add this one line
import openai

client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What is the capital of France?"}]
)
print(response.choices[0].message.content)
# Dashboard opens automatically at http://localhost:8000 when your script finishes

LangChain (Zero-Config)

import agenttrace.auto  # ← Same one line
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4")
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    ("human", "{input}")
])

chain = prompt | llm
result = chain.invoke({"input": "Explain quantum computing"})
# All LLM calls automatically appear in the AgentTrace dashboard

Custom Tool Tracking

from agenttrace import track_tool, track_agent

@track_tool
def search_database(query: str) -> str:
    return db.search(query)

@track_agent
def my_agent(task: str) -> str:
    data = search_database(task)
    return llm.complete(f"Answer based on: {data}")

---

🏗️ Architecture

Your Agent Script
       │
       ▼
  import agenttrace.auto
       │
       ├─── OpenTelemetry TracerProvider
       │         │
       │         ├── OpenAI Instrumentor (optional)
       │         ├── LangChain Callback Adapter
       │         └── CrewAI Callback Adapter
       │         │
       │         ▼
       │    AgentTraceExporter → SQLite (.agenttrace.db)
       │
       ├─── sys.excepthook → Crash capture
       │
       └─── atexit → FastAPI Server (localhost:8000)
                         │
                         ├── /api/traces
                         ├── /api/trace/{id}
                         └── React Dashboard (Vite + Tailwind)

Key Design Decisions

• OpenTelemetry for instrumentation (industry standard, not fragile monkey-patching)
• SQLite with WAL mode for zero-config persistence that survives crashes
• contextvars for thread-safe multi-agent isolation
• Pre-compiled React UI bundled inside the Python package

---

📁 Project Structure

agenttrace/
├── auto.py              # Zero-config entry point (import this)
├── exporter.py          # OTel SpanExporter → SQLite
├── judge.py             # Smart Auto-Judge engine (5 eval types)
├── models.py            # Pydantic data models
├── storage.py           # SQLite with WAL mode
├── server.py            # FastAPI dashboard server
├── decorators.py        # @track_tool, @track_agent
├── utils.py             # Payload truncation
├── integrations/
│   ├── langchain.py     # LangChain callback adapter
│   └── crewai.py        # CrewAI callback adapter
└── static/              # Pre-compiled React dashboard

---

⚙️ Configuration

Environment Variable	Default	Description
GROQ_API_KEY	—	Required for LLM-powered judge evaluations
AGENTTRACE_DB_PATH	.agenttrace.db	Custom database file path
AGENTTRACE_FULL_PAYLOAD	0	Set to 1 to disable payload truncation
AGENTTRACE_MAX_CONTENT	500	Max characters before truncation

---

🤝 Contributing

We welcome contributions! Here's how to set up the dev environment:

git clone https://github.com/CURSED-ME/AgentTrace.git
cd AgentTrace
pip install -e ".[all]"

# Frontend development
cd ui
npm install
npm run dev    # Dev server with hot reload
npm run build  # Compile to agenttrace/static/

See .env.example for required environment variables.

---

📄 License

MIT License — see LICENSE for details.

---