# Retrace

> The execution replay engine for AI agents.

## What is Retrace?

Retrace records every LLM call, tool invocation, and error your AI agent makes. You can replay executions step-by-step like a video, fork from any point to try different paths, and share interactive "tapes" via URL.

Think Chrome DevTools meets Git Bisect, for AI agents.

## Core Features

- **Record** — One `@record` decorator captures every LLM call, tool call, and error
- **Replay** — Step through executions with play/pause/speed/timeline scrubber
- **Fork** — Branch from any step, modify input, watch a new path diverge
- **Share** — Publish traces as shareable "tapes" with OG images for social

## Supported Providers

- OpenAI (GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini) — auto-captured
- Anthropic (Claude Opus 4.7, Sonnet 4.6, Haiku 4.5) — auto-captured
- Google Gemini (Gemini 3 Pro, 3 Flash, 3.1 Flash, 2.5 Pro, 2.5 Flash) — auto-captured
- Any provider via OpenTelemetry or manual instrumentation

## AI Features (Retrace AI)

All AI-powered features (evaluations, fork replay, memory extraction, semantic search) are built-in and powered by Retrace AI. No external API keys required — authenticate with your Retrace API key only.

## SDKs

- Python: `pip install retrace-sdk` or `uv add retrace-sdk`
- TypeScript: `npm install retrace-sdk`

## Quick Start (Python)

```python
import retrace

retrace.configure(api_key="rt_...")

@retrace.record(name="my-agent")
def run_agent(prompt: str):
    response = client.chat.completions.create(
        model="gpt-5.5",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content
```

## Quick Start (TypeScript)

```typescript
import { configure, trace } from "retrace-sdk";

configure({ apiKey: "rt_..." });

const runAgent = trace(async (prompt: string) => {
  const response = await openai.chat.completions.create({
    model: "gpt-5.5",
    messages: [{ role: "user", content: prompt }],
  });
  return response.choices[0].message.content;
}, { name: "my-agent" });
```

## API

- [REST API](https://api.retraceai.tech): Base URL for traces, forks, evaluations, and guardrails
- [API Reference](https://retraceai.tech/developers/api-reference): Endpoints, authentication, and rate limits
- [OpenTelemetry ingest](https://docs.retraceai.tech): OTLP at POST /v1/traces; live span stream at wss://api.retraceai.tech/ws/v1/stream

## Pricing

- Free: 1,000 traces/mo, 10 tapes, 7-day retention, 3 guardrail policies (fork & replay not included — available as a $5/mo add-on granting 10 replays/mo)
- Pro ($79/mo, $790/yr): 50,000 traces/mo, 90-day retention, unlimited fork replays, cassette VCR replay, semantic search
- Teams ($349/mo, $3,490/yr): 500,000 traces/mo, 1-year retention, up to 10 users, team traces & collaboration, audit logs
- Enterprise (custom pricing): Unlimited traces, custom retention, SSO, audit logs, data residency

## New Features

- **Tape Gallery** — Explore public tapes at /explore (trending, newest, most liked)
- **Continuous Evals** — Auto-run evaluations on matching traces, webhook alerts on score drops
- **Team Collaboration** — Comment on spans, assign traces to teammates, notifications
- **Resumable Forks** — Re-execute agents from any checkpoint with modified inputs
- **Anomaly Detection** — Automatic cost/latency/error spike detection with severity levels
- **Root-Cause Analysis** — AI-powered failure explanation for failed traces
- **Cost Intelligence** — Per-feature cost breakdown, model efficiency comparison, optimization recommendations
- **Audit Log Export** — Bulk export audit trails as JSON or CSV for compliance
- **CLI** — `retrace auth login`, `retrace traces list`, `retrace eval gate` for CI/CD
- **MCP Server** — 6 tools for AI coding agents (list_traces, get_trace, search_spans, store_memory, recall_memories, get_tape)
- **Deep Fork Replay** — Context injection flows fork output into subsequent prompts, tool output mocking, batch sweeps with multiple variants, decision sensitivity scoring
- **Runtime Guardrails** — Cost budgets, loop detection, context overflow prevention, latency budgets, error rate monitoring with halt/alert/throttle actions
- **Sessions** — Group traces by session_id for multi-turn agent conversations, session-level cost/duration aggregates
- **Agent Graphs** — DAG visualization of execution flow with parent-child edges, multi-agent identification
- **Eval CI/CD Gate** — POST /evaluations/:id/gate returns pass/fail for deployment pipelines with regression detection
- **Fork Preferences (RLHF)** — Record preferred fork outcomes, export as DPO training pairs for model improvement
- **Multi-Agent Tracing** — agent_id on spans, cross-agent causal graphs, fork one agent and see ripple effects

## Links

- [Website](https://retraceai.tech): Product homepage
- [Documentation](https://docs.retraceai.tech): SDK, CLI, and API reference
- [Pricing](https://retraceai.tech/pricing): Plans from free to enterprise
- [GitHub](https://github.com/yash1511-bogam/retrace-sdk): Open-source SDKs
- [npm](https://www.npmjs.com/package/retrace-sdk): TypeScript/JavaScript SDK
- [PyPI](https://pypi.org/project/retrace-sdk/): Python SDK
- [CLI](https://cli.retraceai.tech): Command-line interface

## Contact

- [Contact sales & support](https://retraceai.tech/contact): Get in touch with the team
- [Email](mailto:hello@retraceai.tech): hello@retraceai.tech

## Optional

- [Blog](https://retraceai.tech/blog): Articles and engineering posts
- [Changelog](https://retraceai.tech/changelog): Release notes and updates
- [Explore Tapes](https://retraceai.tech/explore): Public, interactive shared agent runs
- [Privacy Policy](https://retraceai.tech/privacy): Data handling and privacy
- [Terms](https://retraceai.tech/terms): Terms of service