AgentTracer

AgentTracer is a local-first visual debugger for AI agents — trace your LLM runs, inspect spans step-by-step, and understand agent behavior during development.

Why AgentTracer?

Existing observability tools (Langfuse, LangSmith) are built for production monitoring: dashboards, metrics, team collaboration. They’re heavy, require external services, and aren’t optimized for rapid local iteration.

AgentTracer is different:

Local-first — SQLite database, no external services, works entirely offline
Developer-focused — built for understanding agents during development, not monitoring in prod
Step-by-step — interactive tree view of every span, tool call, prompt, and response
Minimal setup — start backend, run traced agent, open UI
Python SDK — simple @trace_agent_run decorator or with Tracer() context manager

Architecture

1
┌─────────────────────────────────────────────┐
2
│              Your Agent Code                 │
3
│         (Python / LangChain / etc.)          │
4
└─────────────────────┬───────────────────────┘
5
                      │ @trace_agent_run
6
                      ▼
7
┌─────────────────────────────────────────────┐
8
│            AgentTracer SDK                    │
9
│  @trace_agent_run │ Tracer │ HTTPExporter    │
10
└─────────────────────┬───────────────────────┘
11
                      │ HTTP POST /api/v1/ingest/events
12
                      ▼
13
┌─────────────────────────────────────────────┐
14
│          AgentTracer Backend                  │
15
│         FastAPI + SQLite                      │
16
│  POST /ingest/events │ GET /runs │ GET /tree  │
17
└─────────────────────┬───────────────────────┘
18
                      │ REST API
19
                      ▼
20
┌─────────────────────────────────────────────┐
21
│          AgentTracer Frontend                 │
22
│      React + TypeScript + Vite                │
23
│  RunList │ TraceTree │ DetailsPanel           │
24
└─────────────────────────────────────────────┘

Quick Start

Prerequisites

Python 3.12+ (backend) / 3.10+ (SDK)
Node.js 18+ (frontend)
uv (Python) — curl -LsSf https://astral.sh/uv/install.sh | sh

1. Start Backend

1
cd AgentTracer/backend
2
uv sync
3
uv run uvicorn agent_tracer.main:app --port 8000

API docs at http://localhost:8000/docs

2. Trace Your Agent (SDK)

1
cd AgentTracer/sdk
2
uv sync

1
from agent_trace_sdk import trace_agent_run
2

3
@trace_agent_run(name="my_agent")
4
def my_agent_function(user_input: str) -> str:
5
    result = f"Processed: {user_input}"
6
    return result
7

8
my_agent_function("What is the weather?")

Run: uv run python my_script.py

3. View Traces in UI

1
cd AgentTracer/frontend
2
npm install
3
npm run dev

Open http://localhost:3000 — see traced runs in sidebar, click to explore trace tree.

SDK Usage

Decorator (simplest)

1
from agent_trace_sdk import trace_agent_run
2

3
@trace_agent_run(name="research_agent")
4
def research(query: str) -> str:
5
    return run_agent(query)
6

7
research("What is Python?")

Context Manager (more control)

1
from agent_trace_sdk import Tracer
2

3
with Tracer(name="my_agent") as span:
4
    span.set_attribute("model", "gpt-4")
5
    span.set_attribute("temperature", 0.7)
6
    result = agent.run(user_input)
7
    span.add_event("output", {"result": result})

What Gets Collected

Spans — each unit of work with start/end timestamps
Span types — agent_run, step, tool_call, llm_call
Attributes — key-value pairs on spans
Events — custom events like input, output, error
Parent-child relationships — nested spans form a tree

API Endpoints

Method	Path	Description
`POST`	`/api/v1/ingest/events`	Accept trace events from SDK
`GET`	`/api/v1/runs`	List runs (paginated)
`GET`	`/api/v1/runs/{id}`	Get run details
`GET`	`/api/v1/runs/{id}/tree`	Get trace tree
`GET`	`/api/v1/health`	Health check

Project Structure

1
AgentTracer/
2
├── backend/             # FastAPI + SQLite (Python)
3
│   ├── pyproject.toml
4
│   └── src/agent_tracer/
5
│       └── main.py      # Single-file backend
6
├── sdk/                 # Python tracing library
7
│   ├── pyproject.toml
8
│   └── src/agent_trace_sdk/
9
│       ├── tracer.py    # Main tracer
10
│       ├── span.py      # Span dataclass
11
│       ├── exporter.py  # HTTP + Console exporters
12
│       ├── decorators.py # @trace_agent_run
13
│       └── domain/      # Data contracts
14
└── frontend/            # React + TypeScript UI
15
    ├── package.json
16
    ├── vite.config.ts
17
    └── src/
18
        ├── App.tsx
19
        └── components/  # RunList, TraceTree, DetailsPanel

Roadmap

Batch span processor with retry logic
@trace_span decorator for sub-steps
ContextVar-based automatic parent-child tracking
Framework integrations (LangChain, LlamaIndex, OpenAI SDK)
Enhanced visualization: timeline view, filtering, search
Run comparison (side-by-side diff)
Docker setup with docker-compose
PostgreSQL backend for larger deployments