Installation

Quickstart — your first trace in under 5 minutes

This mirrors the in-app checklist on your dashboard. Four steps:

1. Create an API key. In the dashboard, open Settings → API Keys → create a key. It starts with rt_live_ and is shown once — copy it now.

2. Install the SDK.

pip install retrace-sdk

3. Set your API key as an environment variable (the SDK reads it automatically — no key in source):

export RETRACE_API_KEY=rt_live_...

4. Record, then run your agent — the trace appears on your dashboard live (the onboarding card flips from "Waiting for your first trace…" to "received" the moment it lands):

import retrace

@retrace.record(name="my-agent")
def run(prompt):
    # your agent code
    ...

run("hello")

No agent yet? Run retrace init && python retrace_quickstart.py to scaffold an intentionally-broken agent and watch Retrace catch your first failure in seconds.

A complete example

A realistic agent — record an LLM call end to end:

import retrace

retrace.configure(api_key="rt_live_...")

@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

Python SDK

pip install retrace-sdk

Requires Python 3.10 or later. The SDK has minimal dependencies:

• websocket-client - For real-time streaming
• requests - For HTTP fallback transport

Optional provider interceptors (auto-detected):

• openai - Auto-captures OpenAI chat completions
• anthropic - Auto-captures Anthropic messages
• google-genai - Auto-captures Gemini generate calls

# Install with specific provider support
pip install retrace-sdk openai          # OpenAI
pip install retrace-sdk anthropic       # Anthropic
pip install retrace-sdk google-genai    # Gemini

TypeScript SDK

npm install retrace-sdk

Requires Node.js 20 or later. ESM-only package.

Optional provider interceptors (auto-detected if installed):

• openai - Auto-captures OpenAI chat completions
• @anthropic-ai/sdk - Auto-captures Anthropic messages
• @google/genai - Auto-captures Gemini generate calls

Environment Variables

[!NOTE] Get your API key from the Settings page in the dashboard.

Verify Installation

import retrace

retrace.configure(api_key="rt_live_...")

@retrace.record(name="test")
def hello():
    return "world"

hello()  # Check your dashboard
print("Retrace is working!")

Programmatic Configuration

You can also configure the SDK programmatically instead of using environment variables:

import retrace

retrace.configure(
    api_key="rt_live_...",
    base_url="http://localhost:3001",  # For local development
    project_id="my-project-id",
)