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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

retrace_sdk-0.16.9.tar.gz (149.8 kB view details)

Uploaded Jul 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

retrace_sdk-0.16.9-py3-none-any.whl (63.4 kB view details)

Uploaded Jul 4, 2026 Python 3

File details

Details for the file retrace_sdk-0.16.9.tar.gz.

File metadata

Download URL: retrace_sdk-0.16.9.tar.gz
Upload date: Jul 4, 2026
Size: 149.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for retrace_sdk-0.16.9.tar.gz
Algorithm	Hash digest
SHA256	`b98d9481e33c47ce7708f676b839ad70db9155bf7a903a180f6df7cd874bb1e9`
MD5	`339119806f41e5d9ceba5ba8821d043d`
BLAKE2b-256	`8d6ccc1c79d0c003151b08752413f11257ab6e78fe30d43edd76e7b0122829a0`

See more details on using hashes here.

File details

Details for the file retrace_sdk-0.16.9-py3-none-any.whl.

File metadata

Download URL: retrace_sdk-0.16.9-py3-none-any.whl
Upload date: Jul 4, 2026
Size: 63.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for retrace_sdk-0.16.9-py3-none-any.whl
Algorithm	Hash digest
SHA256	`eef288ff37e5dafcae8c0dfe50e62c62df9c767884f2b99a473fda9c14e734dd`
MD5	`4244a9af71e6c9c243bfa2c68d56aa76`
BLAKE2b-256	`a746fe8180ced443cd84dcb9a3b2a444d79a29a5075a768718619de1a35ba45f`