agenttrace-sdk 0.3.1

Time-Travel Debugging for AI Agents

AgentTrace - Time-Travel Debugging for AI Agents 🚀

The Industry's First Time-Travel Debugger for LLM Agents + AutoFix Engine

AgentTrace enables you to record, replay, and debug AI agent executions with full determinism. Jump to any point in time, edit the past, and see what would have happened. Our AutoFix Engine (AFE) automatically detects failures, classifies root causes, generates fixes, validates them in sandboxes, and can even auto-apply solutions.

🚀 Quick Start

# Install
pip install agenttrace

# Record a trace
agenttrace record my_agent.py

# List traces
agenttrace list

# Replay a trace
agenttrace replay <trace-id>

# Jump to specific step
agenttrace replay <trace-id> --step 42

✨ Features

⏱️ Time-Travel Debugging

• Record agent executions with full state capture
• Replay deterministically (same random numbers, same API responses)
• Jump to any step using keyframe snapshots
• Resume execution from any saved step (state hydration + runtime restore)
• Edit the past (fork a branch, tweak payloads, continue execution)

� AutoFix Engine (AFE)

• Automatic Failure Detection - Detects errors in traces automatically
• Root Cause Analysis - Classifies failures (rate limits, API errors, missing context, etc.)
• Multi-Strategy Fix Generation - Code patches, config changes, prompt improvements, retry policies
• Sandbox Validation - Tests fixes in isolated environments before applying
• Policy-Based Ranking - Prioritizes fixes by confidence, risk, and success rate
• Auto-Apply - High-confidence fixes can be applied automatically
• LLM-Powered - Uses Groq for intelligent code generation and analysis

�🛡️ Safety Sandbox

• Virtual File System - File writes are isolated during replay
• VCR Pattern - API calls are cached (no costs during debugging)
• Deterministic Replay - Random numbers, time, and API calls are frozen

☁️ Full SaaS Platform

• Multi-User Auth - Email magic link login with organization isolation
• Cloud Storage - Traces stored in Supabase Storage with CDN delivery
• Worker Fleet - Python workers for distributed trace processing
• Real-Time Dashboard - AFE monitoring, trace timeline, multiverse branching
• Email Notifications - Brevo integration for failure alerts and fix notifications

🤖 Framework Support

• OpenAI API
• Groq API
• LangChain (coming soon)
• AutoGen (coming soon)

📖 Usage

Basic Recording

# my_agent.py
from groq import Groq

client = Groq()
response = client.chat.completions.create(
    model="llama3-8b-8192",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

agenttrace record my_agent.py
# Output: ✅ Trace recorded: abc123-def456-...

Replay Mode

export AGENTTRACE_MODE=REPLAY
export AGENTTRACE_ID=abc123-def456-...
python my_agent.py
# Runs with cached API responses (free!)

Resuming from a Saved Step

# Jump directly to step 25 and resume from there
agenttrace replay abc123-def456-... --step 25
python my_agent.py  # execution restarts with the recorded locals/globals

Branching & Editing History

# Create a branch at a specific step (requires a snapshot/keyframe there)
agenttrace branch create abc123-def456-... --step 42 --name patch-output

# Override a recorded event payload (e.g., change an LLM response)
agenttrace branch edit abc123-def456-...__patch-output --event 42 --payload '{"content":"Rewritten response"}'

# Replay from that branch and continue deterministically
agenttrace replay abc123-def456-... --branch abc123-def456-...__patch-output
python my_agent.py  # starts from the forked state with your edits applied

AI-Powered Auto-Fix

# Auto-fix errors using Groq AI
agenttrace fix <trace-id>

# Fix a specific step
agenttrace fix <trace-id> --step 42

# Use your own API key
agenttrace fix <trace-id> --api-key your_groq_key

# Override Groq model (or set GROQ_MODEL env var)
agenttrace fix <trace-id> --model llama-3.1-8b-instant

# Use heuristic suggestions instead of AI
agenttrace fix <trace-id> --no-ai

Setup:

1. Copy .env.example to .env
2. Add your Groq API key: GROQ_API_KEY=your_key_here
3. (Optional) Set GROQ_MODEL=llama-3.1-8b-instant (see https://console.groq.com/docs/models for options)
4. Get your key from: https://console.groq.com/

The AI fixer analyzes error traces, extracts code context, and generates actual code patches with explanations.

Automatic State Capture

AgentTrace automatically captures:

• Local variables at keyframe intervals
• Global state
• Function call stack
• API request/response pairs
• Random number sequences
• Time/DateTime values

🚀 Production Deployment

1️⃣ Supabase Setup

# Run all migrations
cd supabase
supabase db push

# Or manually run SQL files:
# - supabase_fix_afe_constraint.sql (AFE type constraint)
# - supabase_fix_afe_status_constraint.sql (AFE status constraint)
# - supabase_add_notifications.sql (Brevo integration)

2️⃣ Environment Configuration

Copy frontend/.env.local.example to frontend/.env.local and configure:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Groq (for AFE)
GROQ_API_KEY=your_groq_api_key

# Brevo (for notifications)
BREVO_API_KEY=your_brevo_api_key
BREVO_SENDER_EMAIL=[e-mail]
BREVO_SENDER_NAME="AgentTrace"

3️⃣ Frontend Deployment

cd frontend
npm install
npm run build
npm start

Or deploy to Vercel:

vercel --prod

4️⃣ Worker Deployment

cd worker
pip install -r requirements.txt
python main.py

For production, use process managers:

# Using PM2
pm2 start main.py --name agenttrace-worker --interpreter python

# Using systemd (create /etc/systemd/system/agenttrace-worker.service)
# Or containerize with Docker

5️⃣ Brevo IP Whitelisting

Add your worker's IP address to Brevo's authorized IPs:

1. Go to https://app.brevo.com/security/authorised_ips
2. Add your server IP
3. Restart worker

Architecture Overview

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Next.js    │────▶│  Supabase    │◀────│   Python    │
│  Frontend   │     │  (Auth/DB/   │     │   Workers   │
│             │     │   Storage)   │     │             │
└─────────────┘     └──────────────┘     └─────────────┘
      │                    │                     │
      │                    ├─────────────────────┤
      │                    │   Polling Jobs      │
      │                    │   Processing Traces │
      │                    │   Running AFE       │
      └────────────────────┴─────────────────────┘

🧪 Tests

Pytest (Tracer + CLI)

pytest tests/e2e

Next.js API Routes

cd frontend
npm install   # first run
npm run test:api

UI Automation

cd frontend
npx playwright test   # Run UI branch flow tests

🏗️ Architecture

AgentTrace uses a Hybrid Keyframe Architecture:

• Delta Log: Lightweight event log (API calls, random numbers)
• Keyframes: Full memory snapshots every N steps (default: 10)
• Fast Seek: Load nearest keyframe + replay deltas = instant jump to any step

🔒 Security

• PII Scrubbing: Automatic detection and redaction (coming soon)
• Secrets Detection: API keys are automatically masked
• Sandbox Isolation: Replay can't affect production systems

☁️ Supabase Backend (Optional)

AgentTrace now supports a hosted Supabase backend for team collaboration:

• Multi-user auth — Email magic link login with org isolation
• Cloud storage — Traces and snapshots stored in Supabase Storage
• Job queue — Replay jobs queued in Postgres for worker processing
• Row-level security — All data scoped by organization

Setup: See supabase/README.md for instructions. You can connect to a real Supabase project directly — no Docker required!

📊 Recent Improvements

✅ December 2024 - Stability & Production Readiness

Bug Fixes:

• Fixed AFE database constraints to support all candidate types
• Fixed script upload for Fork, Simulate, and Replay operations
• Fixed worker organization selection for multi-tenant support
• Fixed Supabase import issues in AFE stats API
• Fixed GitHub secret detection by excluding API keys from commits

Features:

• Added AutoFix Engine link to sidebar navigation
• Created comprehensive stress testing suite (5 concurrent jobs)
• Added utility scripts for debugging and verification
• Implemented reset_traces.py for clean database resets
• Added migration verification scripts

Infrastructure:

• Configured Brevo email notifications for failures and fixes
• Set up proper .gitignore for security (excludes .env files and local traces)
• Established GitHub repository with clean commit history
• Created deployment documentation and setup guides

📊 Roadmap

• Core time-travel engine
• VCR pattern for LLM APIs
• Virtual File System
• Automatic state capture
• CLI tool
• Web UI (Timeline visualizer)
• AutoFix Engine (RCA + multi-strategy fixes)
• Cloud storage & sharing (Supabase backend)
• Python worker for remote replay
• Email notifications (Brevo)
• Stress testing & production stability
• LangChain integration
• CLI login & token auth
• Auto-apply policies with approval workflows

🤝 Contributing

This is a rapidly evolving project. Contributions welcome!

📄 License

MIT License

🙏 Acknowledgments

Built on research from:

• Temporal (Durable Execution)
• CRIU (Checkpoint/Restore)
• cloudpickle (State Serialization)
• pyfakefs (Virtual File System)

---

Made with ❤️ for the AI Agent community