Replay on Traza Cloud

A replay serves a recorded run’s model answers back to your agent through its own SDK. The engine’s replay guide explains tapes, matching, streaming and diffs; this page is the Traza Cloud path.

From the console

Open the project’s Replay tab and pick a recent run. The console creates the replay and shows the environment lines for the OpenAI and Anthropic SDKs, pointing at api.trazadb.com, and a Python snippet. Use any read or full key of the project.

From the API

curl -s https://api.trazadb.com/v1/replays \
  -H "Authorization: Bearer $TRAZA_API_KEY" \
  -d '{"run": "sess-42", "mode": "strict"}'

The response’s base_urls are paths; prefix them with https://api.trazadb.com:

export OPENAI_BASE_URL=https://api.trazadb.com/v1/replays/$REPLAY_ID/openai/v1
export OPENAI_API_KEY=$TRAZA_API_KEY

export ANTHROPIC_BASE_URL=https://api.trazadb.com/v1/replays/$REPLAY_ID/anthropic
export ANTHROPIC_API_KEY=$TRAZA_API_KEY

The Anthropic SDK sends its key as x-api-key; the gateway accepts that header on replay routes. Then run your agent unchanged.

from openai import OpenAI
import os

client = OpenAI(
    base_url=f"https://api.trazadb.com/v1/replays/{os.environ['REPLAY_ID']}/openai/v1",
    api_key=os.environ["TRAZA_API_KEY"],
)

GET /v1/replays/{id} reports how many model steps were served, how many remain, and the first divergence if there was one.

Strict or loose

Strict (the default) refuses a request whose messages differ from the recorded step with 409 and "type": "replay_divergence", naming the step, and does not consume it. Both SDKs are told not to retry. Use it to catch the first point where a change to your agent changed what it asked.

Loose serves the steps in order whatever is asked and records whether each call matched. Use it for recordings that cannot be compared exactly.

Tools

A replay answers model calls only. Tools your agent calls run for real. To use a recorded tool result instead, have your tool dispatcher ask the replay:

curl -s https://api.trazadb.com/v1/replays/$REPLAY_ID/tools/next \
  -H "Authorization: Bearer $TRAZA_API_KEY" -d '{"tool": "search_orders"}'

Limits

A replay lives in the cell’s memory for one hour. Each project may hold up to 64 live replays and 64 MiB of them at once, and the cell, which other projects share, holds at most 1,024 replays and 512 MiB in all; past either, creating one answers 429 with Retry-After. Only chat completions and messages are replayed: the OpenAI Responses API, embeddings and legacy completions answer 400. Deleting data with an erasure withdraws any replay holding it. The full list is in the engine guide’s limits.

Diff two runs

curl -s "https://api.trazadb.com/v1/diff?a=sess-42&b=sess-43" \
  -H "Authorization: Bearer $TRAZA_API_KEY" | jq .first_divergence

The answer names the first step where the runs parted and whether the difference was the input, the decision, the configuration or the structure.

Fork a run

A fork is a replay told where the recording stops being the truth: serve a different tool result or model answer at a step (edits), and let the agent go on live after a step (live_after). A read key is enough.

curl -s https://api.trazadb.com/v1/replays -H "Authorization: Bearer $TRAZA_API_KEY" \
  -d '{"run": "weather-7",
       "edits": [{"step": 1, "tool_result": {"forecast": "sun", "celsius": 24}}],
       "live_after": 1}'

Past the live point, every model call and tools/next answers 409 replay_live: the harness’s signal to send that call, and every later one, to the real provider. The engine’s Python and TypeScript clients switch for you and tag the forked run with its parent and cut, so GET /v1/forks?run=weather-7 lists each fork with how it ended and what it cost. A live point alone is a rewind: replay a long run’s beginning for free, then continue live. The engine’s Fork & Rewind guide covers the clients, tape tests and golden runs.