---
title: "TypeScript SDK — Retrace"
description: "The Retrace TypeScript SDK: wrap any async agent with trace(), auto-capture model and tool calls, enable cascade replay, tag agents with withAgent, and enforce per-run ceilings."
canonical: "https://retraceai.tech/developers/sdk-typescript"
last-updated: 2026-08-26
format: text/markdown
---

# TypeScript SDK

Wrap any async agent function to capture the full run, enable fork & replay, tag multi-agent work, and enforce per-run ceilings — ESM and fully typed.

## What it does

- **Wrap a function** — Pass your async agent to trace() and the entire run is recorded — your code stays exactly the same.
- **Automatic capture** — Calls to the major model providers are instrumented for you with prompts, responses, tokens, and cost.
- **Replay-ready** — Set resumable: true to unlock cascade fork & replay later.
- **Multi-agent tagging** — withAgent({ id, role }) scopes spans to an agent across async work — even with concurrent agents in one process.
- **Safe by default** — Privacy redaction, an offline buffer with automatic transport fallback, and typed errors that never crash your agent.
- **Built-in enforcement & cassettes** — Local per-run ceilings raise a typed RetraceEnforcementError, and writeGoldenCassette records a run as a CI fixture.

## Examples

Install from npm (ESM).

```shell
npm i retrace-sdk
```

Configure once, then wrap any async function.

```agent.ts
import { configure, trace } from "retrace-sdk";

configure({ apiKey: "rt_..." });

const runAgent = trace(
  async (prompt: string) => agent.invoke(prompt),
  { name: "support-agent", resumable: true },
);
```

withAgent scopes spans to an agent.

```multi_agent.ts
import { withAgent } from "retrace-sdk";

withAgent({ id: "planner", role: "Planner" }, () => {
  return planAgent.run(task);
});
```


## Related

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