---
title: "Python SDK — Retrace"
description: "The Retrace Python SDK: record any agent with one @record decorator, auto-capture model and tool calls, enable cascade replay, tag multi-agent work, and enforce per-run ceilings."
canonical: "https://retraceai.tech/developers/sdk-python"
last-updated: 2026-08-26
format: text/markdown
---

# Python SDK

Add observability, fork & replay, and runtime safety to any Python agent with one decorator and a small, dependency-light package (Python 3.10+).

## What it does

- **One decorator** — Decorate your agent function with @retrace.record and the whole run is captured — there's no manual instrumentation to write.
- **Automatic capture** — Calls to the major model providers are recorded for you, including prompts, responses, token usage, and cost.
- **Replay-ready** — Mark a run resumable=True to unlock cascade fork & replay from the dashboard later.
- **Multi-agent tagging** — Scope spans to an agent with retrace.agent(id, role=...) so multi-agent runs build a topology graph.
- **Safe by default** — Privacy redaction is on, an offline buffer flushes on reconnect, and typed errors — auth, credits, rate-limit, enforcement — never crash your agent.
- **Built-in enforcement & cassettes** — Local per-run ceilings raise a typed RetraceEnforcementError instead of overspending, and write_golden_cassette records a run as a CI fixture.

## Examples

Install from PyPI.

```shell
pip install retrace-sdk
```

Configure once, then record any function with a decorator.

```agent.py
import retrace

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

@retrace.record(name="support-agent", resumable=True)
def run_agent(prompt: str) -> str:
    return agent.invoke(prompt)
```

Tag each agent's work to build the topology graph.

```multi_agent.py
with retrace.agent("researcher", role="research"):
    findings = research_agent.run(task)

with retrace.agent("writer", role="writer", parent="researcher"):
    draft = writer_agent.run(findings)
```


## Related

- HTML page: https://retraceai.tech/developers/sdk-python
- Documentation: https://docs.retraceai.tech
- OpenAPI specification: https://retraceai.tech/openapi.json
- Authentication for agents: https://retraceai.tech/auth.md