Python SDK

pip install retrace-sdk

import retrace

retrace.configure(
    api_key="rt_live_...",
    base_url="https://api.retraceai.tech",
    project_id="my-project",
)

@retrace.record(name="research-agent")
def research(topic: str) -> str:
    response = client.chat.completions.create(
        model="gpt-5.5",
        messages=[{"role": "user", "content": f"Research {topic}"}]
    )
    return response.choices[0].message.content

with retrace.record(name="agent", input={"prompt": "hello"}) as t:
    result = agent.run("hello")
    t.output = result

with retrace.record(name="pipeline") as t:
    t.metadata = {"environment": "staging", "version": "1.2.0"}
    result = run_pipeline()
    t.output = result

with retrace.record(name="agent") as t:
    span = t._recorder.start_span(
        name="web_search",
        span_type=retrace.SpanType.TOOL_CALL,
        input={"query": "quantum computing"}
    )
    results = search("quantum computing")
    t._recorder.end_span(span.id, output=results)

from retrace.interceptors.openai import install_openai_interceptor
install_openai_interceptor()

from retrace.interceptors.anthropic import install_anthropic_interceptor
install_anthropic_interceptor()

from retrace.interceptors.gemini import install_gemini_interceptor
install_gemini_interceptor()

retrace.configure(api_key="rt_live_...", transport="http")

import os
os.environ["RETRACE_ENABLED"] = "false"

@retrace.record(name="my-agent", resumable=True)
def run_agent(prompt, context):
    # Each LLM call becomes a checkpoint
    plan = call_planner(prompt)
    result = call_executor(plan)
    return result

retrace.configure(
    api_key="rt_live_...",
    sample_rate=0.5,  # Record 50% of traces
)

RETRACE_SAMPLE_RATE=0.1  # Record 10% of traces

retrace.configure(
    api_key="rt_live_...",
    sample_rate=0.5,
    sample_seed="my-stable-seed",  # Same seed + function name = same decision
)

RETRACE_SAMPLE_SEED=my-stable-seed

from retrace.traceparent import set_trace_context, inject_traceparent, parse_traceparent

# Set active context inside a traced function
set_trace_context(trace_id, span_id)

# Inject into outgoing requests
headers = inject_traceparent({"Content-Type": "application/json"})
# headers now includes: {"traceparent": "00-{trace_id}-{span_id}-01", ...}

requests.get("https://downstream.com/api", headers=headers)

# Parse incoming traceparent
result = parse_traceparent(request.headers["traceparent"])
# (trace_id, parent_id, sampled)

# Streaming is intercepted transparently
stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,  # ← SDK wraps the generator, emits span on completion
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
# Span emitted here with full output, tokens, and cost

with client.messages.stream(model="claude-sonnet-4", ...) as stream:
    for text in stream.text_stream:
        print(text, end="")
# Span captured automatically

@retrace.record(name="my-agent")
def run(prompt: str):
    response = client.chat.completions.create(
        model="gpt-5.5",
        messages=[{"role": "user", "content": prompt}],
        logprobs=True,  # Enables token ID capture
    )
    return response.choices[0].message.content