Recording Traces

The @record Decorator

The simplest way to record an agent execution. Wrap any function and Retrace captures every LLM call, tool invocation, and error automatically.

import retrace

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

@retrace.record(name="research-agent")
def research(topic: str) -> str:
    response = ai.models.generateContent(
        model="gemini-3.1-pro-preview",
        messages=[{"role": "user", "content": f"Research {topic}"}]
    )
    return response.choices[0].message.content

result = research("quantum computing 2026")

Context Manager

For more control over the trace lifecycle:

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

Manual Spans

Add custom spans for non-LLM operations like tool calls, database queries, or API requests:

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

What Gets Captured

[!TIP] Spans can be nested. Set parent_id when creating manual spans to build a tree structure.

[!WARNING] Input and output are stored as-is. Avoid passing sensitive PII (passwords, tokens) in LLM messages if you share tapes publicly.