Retrace

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.

Links

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.16.17)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for yashbogam from gravatar.com yashbogam

Credits

Author: Yash Bogam

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

anthropic dev gemini openai

Tags

agent ai anthropic gemini llm observability openai replay tracing

Classifiers

Report project as malware

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.16.tar.gz (151.1 kB view details)

Uploaded Source

Built Distribution

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

retrace_sdk-0.16.16-py3-none-any.whl (64.4 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: retrace_sdk-0.16.16.tar.gz
  • Upload date:
  • Size: 151.1 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.16.tar.gz
Algorithm Hash digest
SHA256 c046d96c829071e67e9473f920ef8c0fa6c87d6662f30da65093c5fdfa2cf0f3
MD5 56540696ac8aed6317a43c7a3cb51431
BLAKE2b-256 03059734303e56e3c53e45d4da6fafab0caa7b69a9db21ba79c90047f18ae5e2

See more details on using hashes here.

File details

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

File metadata

  • Download URL: retrace_sdk-0.16.16-py3-none-any.whl
  • Upload date:
  • Size: 64.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.16-py3-none-any.whl
Algorithm Hash digest
SHA256 894181d86fd7cbabdc1a3507e513ef435e63a0de92330ed74d276f81d0ade51c
MD5 31ef3f50c7b8f036f7c174d420fd6624
BLAKE2b-256 0943277677f09f78dc8bffe0fa34a1ddea03ef764b200baab379ef81681a2a23

See more details on using hashes here.

Release history Release notifications | RSS feed

0.16.17

2 files

This release

0.16.16 This release

2 files

0.16.15

2 files

0.16.14

2 files

0.16.13

2 files

0.16.12

2 files

0.16.11

2 files

0.16.10

2 files

0.16.9

2 files

0.16.8

2 files

0.16.7

2 files

0.16.6

2 files

0.16.5

2 files

0.16.3

2 files

0.16.2

2 files

0.16.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.0

2 files

0.13.3

2 files

0.13.2

2 files

0.13.1

2 files

0.13.0

2 files

0.11.7

2 files

0.11.6

2 files

0.11.5

2 files

0.11.4

2 files

0.11.3

2 files

0.11.1

2 files

0.11.0

2 files

0.10.0

2 files

0.9.0

2 files

0.6.0

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.4.0

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page