llms.txt
# 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" });
```
## When to use Retrace
Use Retrace when an agent needs to:
- debug a multi-step production failure and identify the first divergent span;
- reproduce a recorded run before changing prompts, tools, models, or orchestration;
- fork from one recorded step and cascade-replay the downstream execution;
- verify whether a proposed fix improved, regressed, or did not change behavior;
- stop loops, excessive 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; or
- publish a scrubbed execution as an interactive tape for review.
Agents should use the Python or TypeScript SDK to record code they execute, the REST API or CLI for automation, OpenTelemetry for language-neutral ingestion, and the hosted MCP server when they need native tools for trace search, memory, replay, or tape access. Mutation tools that replay or publish data require explicit user confirmation.
## Developer Discovery
- [Developer Resources](https://retraceai.tech/developers): Index of Retrace developer interfaces
- [Developer Resources (Markdown)](https://retraceai.tech/developers.md): Same index, machine-readable
- [OpenAPI 3.1](https://retraceai.tech/openapi.json): Typed REST API specification
- [Authentication](https://retraceai.tech/developers/authentication): API keys and bearer tokens
- [Authentication for agents](https://retraceai.tech/auth.md): How an agent registers, claims, uses, and revokes a credential
- [Sign in with AgentID](https://auth.retraceai.tech/sign-in/agentid): AI agents with an AgentMail inbox sign up and sign in as themselves
- [Webhooks](https://retraceai.tech/developers/webhooks): Outbound event delivery (eval-rule webhooks)
- [MCP Server](https://retraceai.tech/developers/mcp-server): Streamable HTTP setup and tools
- [MCP AI Catalog](https://retraceai.tech/.well-known/ai-catalog.json): Machine-readable MCP discovery
- [CLI](https://retraceai.tech/developers/cli): Official Homebrew and binary installation
- [Full documentation as Markdown](https://retraceai.tech/llms-full.txt): All documentation pages
- [Public repository](https://github.com/Retraceai-tech/retrace-sdk): AGENTS.md, plugin.json, mcp.json, and skills/ for AI coding agents
## Agent Discovery
Machine-readable entry points, all at predictable URLs:
- [/index.md](https://retraceai.tech/index.md): Markdown twin of the site root. Every content page has one — append `.md` to any URL (e.g. /pricing.md, /features/record.md, /developers/sdk-python.md).
- [/pricing.md](https://retraceai.tech/pricing.md): Plans, quotas, and feature gates as comparable markdown tables
- [/auth.md](https://retraceai.tech/auth.md): Credential walkthrough following the auth.md agent-registration profile
- [/skills.md](https://retraceai.tech/skills.md): Capabilities with transport, entry point, and required scopes
- [/.well-known/agent-skills/index.json](https://retraceai.tech/.well-known/agent-skills/index.json): Agent Skills index
- [/.well-known/agent-card.json](https://retraceai.tech/.well-known/agent-card.json): A2A agent card
- [/.well-known/ai-catalog.json](https://retraceai.tech/.well-known/ai-catalog.json): Agentic resource catalog (ARD) with trust manifests
- [/.well-known/api-catalog](https://retraceai.tech/.well-known/api-catalog): API catalog (RFC 9727 linkset)
- [/.well-known/mcp](https://retraceai.tech/.well-known/mcp): MCP discovery for both the product and documentation servers
- [/.well-known/mcp/server-card.json](https://retraceai.tech/.well-known/mcp/server-card.json): Product MCP server card with its tool inventory
- [/.well-known/mcp/docs-server-card.json](https://retraceai.tech/.well-known/mcp/docs-server-card.json): Documentation MCP server card
- [/.well-known/oauth-protected-resource](https://api.retraceai.tech/.well-known/oauth-protected-resource): Protected resource metadata (RFC 9728)
- [/.well-known/oauth-authorization-server](https://auth.retraceai.tech/.well-known/oauth-authorization-server): Authorization server metadata (RFC 8414) with the agent_auth block
- [/.well-known/http-message-signatures-directory](https://retraceai.tech/.well-known/http-message-signatures-directory): Web Bot Auth Ed25519 key directory (RFC 9421)
- [/.well-known/ucp](https://retraceai.tech/.well-known/ucp): Universal Commerce Protocol profile (catalog and quote; checkout requires a human)
- [/ask](https://retraceai.tech/ask): NLWeb natural-language query endpoint, with SSE streaming via `prefer: streaming`
- [/schemamap.xml](https://retraceai.tech/schemamap.xml): NLWeb Schema Map of structured-data feeds
- [/feed.jsonl](https://retraceai.tech/feed.jsonl): Whole site as JSON Lines, one markdown document per line
- [/api/llms.txt](https://retraceai.tech/api/llms.txt): REST API context only
- [/developers/llms.txt](https://retraceai.tech/developers/llms.txt): SDK, CLI, MCP, and webhook context only
Agents may also request markdown from any page with `Accept: text/markdown`, or get a structured
capability manifest from the homepage with `?mode=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, 10 fork replays/mo
- Starter ($29/mo, $290/yr): 10,000 traces/mo, 30-day retention, 100 fork replays/mo, cassette VCR replay
- Pro ($99/mo, $990/yr): 50,000 traces/mo, 90-day retention, unlimited fork replays, cassette VCR replay, semantic search
- Teams ($399/mo, $3,990/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** — official Homebrew cask (`brew install --cask retraceai-tech/tap/retrace-cli`) and signed binaries; commands include `retrace auth login`, `retrace traces list`, and `retrace eval gate`
- **MCP Server** — 10 runtime-discovered tools for trace inspection, semantic search, memory, replay, evaluation updates, and tape publishing over Streamable HTTP
- **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/Retraceai-tech/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
