retrace-sdk

Python

Record every LLM call, tool invocation, and error your agent makes. Replay it step-by-step like a video. Fork from any point, change the input, and watch the whole agent re-execute down a new path. Share any run as an interactive, public link.

Quick Start · How It Works · Recipes · Enforcement · Docs

Install

pip install retrace-sdk

Requires Python 3.10+.

Quick Start

import retrace

retrace.configure(api_key="rt_...")  # get a key in the dashboard

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

run_agent("What changed in vector databases this year?")

That's it. The run appears in the dashboard as an interactive timeline you can scrub, replay, and fork.

How It Works

The SDK is a thin capture layer. It wraps your function, auto-instruments provider calls, and streams spans to Retrace over a resilient transport — never blocking or crashing your agent.

flowchart LR
    subgraph yourproc["Your process"]
        fn["@record"] --> cap["auto-captured spans<br/>(LLM · tool · error)"]
        cap --> buf["offline buffer<br/>(bounded, flush on reconnect)"]
    end

    buf == "WebSocket (primary)" ==> api["Retrace"]
    buf -. "HTTP fallback" .-> api
    api == "resume: re-execute from fork point" ==> fn

    classDef p fill:#0f3d2e,stroke:#10b981,color:#d1fae5;
    class api p;

Capture — provider calls (OpenAI, Anthropic, Gemini) are intercepted automatically; you can also emit manual spans.
Transport — spans stream over a WebSocket; if it drops, the SDK falls back to HTTP and replays a bounded offline buffer on reconnect, so nothing is lost. A flush-on-exit hook captures runs that end abruptly.
Resumable — with resumable=True, a dedicated listener handles a resume command and re-executes your function from a fork point with modified input, powering cascade replay from the dashboard.
Safe by default — failures in the SDK never raise into your agent; typed errors surface real problems explicitly.

Auto-Instrumentation

LLM calls from major providers are captured with no extra code — just install the provider SDK alongside retrace-sdk:

Provider	Captured automatically
OpenAI	chat completions
Anthropic	messages
Google Gemini	generate content

Capabilities

Capability	What it does
Record	One `@record` decorator captures the full execution tree.
Cascade replay	`resumable=True` lets a dashboard fork re-execute the whole function from any step.
Enforcement	Local budget/step/loop ceilings stop a runaway agent before the next call.
Multi-agent	Tag spans with an agent id/role for topology + inter-agent detectors.
Golden cassettes	Record a run as a CI regression fixture and gate on it offline.
Sampling	Record a fraction of traffic in production.
Sessions	Group multi-turn conversations under one session.

Usage Recipes

Configure

import retrace

retrace.configure(
    api_key="rt_...",                  # or RETRACE_API_KEY
    base_url="https://api.retraceai.tech",
    project_id="...",                  # or RETRACE_PROJECT_ID
)

Set RETRACE_ENABLED=false to disable recording without changing code.

Resumable execution (cascade replay)

@retrace.record(name="my-agent", resumable=True)
def run_agent(prompt: str):
    plan = call_planner(prompt)
    result = call_executor(plan)
    return summarize(result)

When you fork at any span in the dashboard, the SDK re-executes the entire function with the modified input — not just one call. Every downstream step that depends on the change diverges.

Enforcement (circuit breakers)

import retrace
from retrace import RetraceEnforcementError

retrace.configure(
    api_key="rt_...",
    max_steps_per_run=50,
    max_usd_per_run=2.0,
    server_enforcement=True,  # optional: also consult centrally-managed server policies
)

try:
    run_agent("...")
except RetraceEnforcementError as e:
    print(e.verdict, e.reason)  # e.g. "block", "Local USD ceiling reached: ..."

Local ceilings are enforced offline (zero network). Precedence: explicit arg > env var (RETRACE_MAX_STEPS_PER_RUN, RETRACE_MAX_TOKENS_PER_RUN, RETRACE_MAX_USD_PER_RUN, RETRACE_SERVER_ENFORCEMENT) > unset. If the server check is unreachable, local limits still apply.

Multi-agent context

import retrace

with retrace.agent("planner", role="planner"):
    plan = call_planner(prompt)
with retrace.agent("executor", role="executor"):
    result = call_executor(plan)

Tags spans so the dashboard can draw the agent topology and run inter-agent detectors (ping-pong, reasoning–action mismatch, task derailment).

Golden cassettes (CI regression gates)

from retrace import write_golden_cassette

write_golden_cassette("golden.json", recorder=rec)

Gate on it offline in CI with retrace ci replay.

Sampling

retrace.configure(api_key="rt_...", sample_rate=0.1)  # record 10% of traces

Error handling

from retrace import (
    RetraceError,
    RetraceAuthError,
    RetraceCreditsExhaustedError,
    RetraceRateLimitError,
    RetraceEnforcementError,
)

Typed errors for auth failures, credit exhaustion, rate limiting, and enforcement blocks. Transient transport problems never crash your agent.

License

MIT

Metadata

Release files for retrace-sdk 0.16.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for retrace-sdk 0.16.22
File	Size	Uploaded
retrace_sdk-0.16.22.tar.gz	191.7 kB	Oct 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for retrace-sdk 0.16.22
File	Interpreter	ABI	Platform	Reset
retrace_sdk-0.16.22-py3-none-any.whl 69.8 kB Oct 1, 2026	Python 3	none	any	Details

Total release size: 261.6 kB

Release files / retrace_sdk-0.16.22.tar.gz

Download URL	retrace_sdk-0.16.22.tar.gz
Size	191.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`4963878cb771b80d33d0a474295b8840bbd195340c787e97cb30c7005c6770b7`
BLAKE2b-256 checksum How to use checksums	`2b26c8911b121081c66aacdb9e42b1599f221b9ee8dfebb535e5797c87ad8635`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`

Release files / retrace_sdk-0.16.22-py3-none-any.whl

Download URL	retrace_sdk-0.16.22-py3-none-any.whl
Size	69.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3546de012bf506b05823f6f341da82d4df5434485c477d2fc4c08130b7416d69`
BLAKE2b-256 checksum How to use checksums	`6122443de63456567ea444c1468838f37fe58fb92cdc12b8882dc631069482aa`
Upload date	Oct 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`