---
title: "Retrace — Execution Replay for AI Agents"
description: "Retrace records, replays, forks, and evaluates AI agent executions. Machine-readable overview of the product, its interfaces, and its pricing."
canonical: "https://retraceai.tech/"
last-updated: 2026-08-26
format: text/markdown
---

# Retrace — the execution replay engine for AI agents

Retrace records every model call, tool invocation, retrieval, and error in an AI agent run. Engineers replay a recorded execution step by step, fork from the exact span where behavior diverged, change the input or model, and cascade-replay the downstream path. A side-by-side diff and a prove-the-fix verdict show whether the change improved, regressed, or left the run unchanged.

## When to use Retrace

- Debug a multi-step agent failure and identify the first divergent span.
- Reproduce a production run before changing prompts, tools, models, or orchestration.
- Fork one recorded step and cascade-replay the rest of the execution.
- Verify whether a proposed fix improved, regressed, or changed nothing.
- Stop loops, runaway spend, latency overruns, or forbidden tool actions before the next call.
- Run behavioral evaluation gates in CI/CD.
- Search prior traces or persistent agent memories by meaning.
- Publish a scrubbed execution as an interactive, shareable tape.

## Start recording

```bash
pip install retrace-sdk    # Python
npm install retrace-sdk    # TypeScript
```

```python
import retrace

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

@retrace.record(name="research-agent", resumable=True)
def run_agent(prompt: str):
    plan = call_planner(prompt)
    results = call_tools(plan)
    return summarize(results)
```

Provider calls to OpenAI, Anthropic, and Gemini are auto-instrumented. `resumable=True` unlocks cascade fork replay.

## Capabilities

- **record-agent-run** (sdk) — Record an AI agent execution as a trace: every model call, tool call, retrieval, and error is captured as a span with its input, output, cost, and timing.
- **inspect-trace** (rest) — Read a recorded agent execution and walk its span tree to find the first step that failed, drifted, or produced an ungrounded answer.
- **search-spans** (rest) — Semantic search across recorded spans and agent memories to find prior occurrences of a behavior, prompt, or failure by meaning rather than exact text.
- **fork-and-replay** (rest, side-effecting) — Branch a recorded execution at one span with a modified input, then cascade-replay every downstream step so the whole agent re-executes along the new path.
- **prove-the-fix** (rest, side-effecting) — Re-run a failed execution after a change and return a verdict — improved, regressed, or unchanged — with the first divergent span.
- **evaluate-and-gate** (rest) — Score recorded executions against behavioral criteria and return a pass/fail gate decision for a CI/CD pipeline.
- **enforce-budget** (rest) — Ask before the next model or tool call whether it is allowed: returns allow, block, or hold based on cost budgets, loop detection, and latency ceilings.
- **agent-memory** (mcp) — Store and semantically recall persistent facts, preferences, corrections, and patterns extracted from prior agent runs.
- **publish-tape** (rest, side-effecting) — Publish a recorded execution as an interactive, shareable public URL so a human can replay it in a browser.
- **read-retrace-docs** (mcp) — Search and read the Retrace documentation, SDK guides, CLI reference, and OpenAPI specification over MCP, without credentials.

## Agent and developer interfaces

- Developer resources index: https://retraceai.tech/developers
- Documentation: https://docs.retraceai.tech
- OpenAPI 3.1 specification: https://retraceai.tech/openapi.json
- REST API base URL: https://api.retraceai.tech
- Authentication walkthrough for agents: https://retraceai.tech/auth.md
- Machine-readable pricing: https://retraceai.tech/pricing.md
- Agent skills index: https://retraceai.tech/.well-known/agent-skills/index.json
- A2A agent card: https://retraceai.tech/.well-known/agent-card.json
- MCP server (Streamable HTTP): https://api.retraceai.tech/mcp
- Documentation MCP server: https://api.retraceai.tech/mcp/docs
- MCP server card: https://retraceai.tech/.well-known/mcp/server-card.json
- Agentic resource catalog: https://retraceai.tech/.well-known/ai-catalog.json
- API catalog (RFC 9727): https://retraceai.tech/.well-known/api-catalog
- Natural-language query endpoint (NLWeb): https://retraceai.tech/ask
- LLM instructions: https://retraceai.tech/llms.txt
- Full documentation as one file: https://retraceai.tech/llms-full.txt
- Public repository with AGENTS.md, plugin.json, and skills: https://github.com/Retraceai-tech/retrace-sdk
- Sitemap: https://retraceai.tech/sitemap.xml

## Core workflow

1. Record an agent run with the SDK, WebSocket stream, REST API, or OTLP endpoint.
2. Inspect the trace timeline and find the first span that failed or drifted.
3. Fork at that span and change one input, prompt, tool result, or model.
4. Cascade-replay the downstream execution and diff it against the original.
5. Save the failure as a regression case and gate future changes in CI.

## Pricing summary

- **Free** ($0) — 1,000 traces/month, 7-day retention, 10 fork replays/month.
- **Starter** ($29) — 10,000 traces/month, 30-day retention, 100 fork replays/month.
- **Pro** ($99) — 50,000 traces/month, 90-day retention, unlimited fork replays/month.
- **Teams** ($399) — 500,000 traces/month, 365-day retention, unlimited fork replays/month.
- **Enterprise** ($2,000/mo billed annually) — unlimited traces/month, unlimited-day retention, unlimited fork replays/month.

Full machine-readable pricing: https://retraceai.tech/pricing.md

## Contact

Email hello@retraceai.tech for product, integration, or sales questions.