retrace-sdk 0.14.0

Record, replay, fork & share AI agent executions

retrace-sdk

The execution replay engine for AI agents. Record every LLM call, tool invocation, and error your AI agent makes. Replay step-by-step. Fork from any point. Share interactive traces via URL.

Install

pip install retrace-sdk

Requires Python 3.10+.

Quick Start

import retrace

retrace.configure(api_key="rt_...")  # Get your key at retraceai.tech/settings

@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

run_agent("What is quantum computing?")

Auto-Instrumentation

Retrace automatically captures LLM calls from all major providers:

# OpenAI — captured automatically
# Anthropic — captured automatically
# Google Gemini — captured automatically

No extra setup needed. Install the provider SDK alongside retrace-sdk and calls are captured.

Features

• Record — One decorator captures every LLM call, tool call, and error
• Replay — Step through executions with play/pause/speed controls
• Fork — Branch from any step, modify input, watch a new path diverge
• Share — Publish traces as shareable "tapes" with interactive playback
• Retrace AI — Built-in evaluations, memory extraction, and semantic search

Resumable Execution (Cascade Replay)

Mark a function as resumable to enable full cascade replay from the dashboard:

@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 modified input — all subsequent LLM calls diverge.

Error Handling

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

Enforcement (Circuit Breakers)

Hard ceilings that stop a runaway agent before the next call. Local limits are enforced offline (zero network); server_enforcement=True also consults centrally-managed server policies.

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 server policies
)

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

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

Tag spans with an agent id/role so the dashboard can draw the agent topology and run inter-agent detectors (ping-pong, reasoning–action mismatch, task derailment):

import retrace

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

Golden Cassettes (CI Regression Gates)

Record a run as a golden cassette and gate on it offline in CI with retrace ci replay:

from retrace import write_golden_cassette

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

Sampling

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

Changelog

0.13.0

• Multi-agent context — retrace.agent(id, role=...) context manager tags spans for topology + inter-agent detectors

• Golden cassettes — write_golden_cassette(path, recorder=...) records a run as a CI regression fixture

• Pre-call enforcement gate — local step/token/USD-per-run ceilings enforced offline; RetraceEnforcementError raised instead of silently skipping the call

• Sessions — session_id parameter in TraceRecorder to group multi-turn conversations

• Multi-Agent — agent_id field on Span for cross-agent tracing

• Guardrail support — SDK respects HALT commands from server-side guardrail policies

0.2.2

• Version sync with TypeScript SDK

0.6.0

• Token ID capture — Span dataclass now supports token_ids and logprobs fields for speculative decoding during replay
• Serialization — to_dict() includes token_ids/logprobs when present

0.2.1

• Offline buffer — stores up to 1000 messages when WebSocket disconnects, flushes on reconnect
• Dedicated listener thread — receives server 'resume' commands without needing active sends
• Cascade replay — resumable=True registers function for SDK-level re-execution
• Fixed — duplicate except block in transport, proper close() cleanup

0.2.0

• Typed errors (RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError)
• Trace sampling via sample_rate config
• Auto-instrumentation for OpenAI, Anthropic, Gemini
• WebSocket transport with auto-reconnect

Links

• Documentation
• GitHub
• PyPI