Up and running in 10 minutes.

Prerequisites

• Python 3.9 or later
• A Relai account (free tier available)
• An existing AI agent using the OpenAI, Anthropic, or LiteLLM SDK

Step 1: Install the SDK

pip install relai-sdk

Step 2: Authenticate

Retrieve your API key from the Relai dashboard under Settings. Then run:

relai auth --key rli_live_YOUR_KEY_HERE

Your key is stored in ~/.relai/credentials. You can also pass it per-session via the RELAI_API_KEY environment variable.

Step 3: Instrument your agent

Wrap your agent's main execution block with the relai.capture() async context manager. When a failure occurs inside this block, Relai captures the full execution state.

import relai
import anthropic

client = anthropic.Anthropic()

async def run_agent(user_message: str):
    async with relai.capture(
        agent_id="my-agent",
        output_dir="./relai-bundles"
    ) as ctx:
        response = await client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": user_message}],
            tools=[{"name": "search_db", "description": "Search internal DB"}]
        )
        return response

Step 4: Trigger a failure and capture the bundle

Run your agent against input that causes the failure. Relai will automatically detect the failure, save the bundle, and display the output path:

python my_agent.py --input "process invoice INV-0042"

[relai] Failure detected at 14:22:31Z
[relai] Bundle saved: ./relai-bundles/my-agent-2026-07-14T14:22:31Z.rli
[relai] Dashboard: https://app.getrelai.org/failures/f_7xk2m

Step 5: Propose a fix and verify it

After making your fix, run the replay verifier against the bundle:

relai verify \
  --bundle ./relai-bundles/my-agent-2026-07-14T14:22:31Z.rli \
  --agent-path ./my_agent.py

[relai] Seeding replay environment from bundle...
[relai] Executing agent with captured context...
[relai] PASS  fix verified against replay
[relai] Replay time: 2.3s

A PASS result means your fix handles the exact conditions that caused the original failure. The result is also posted to the Relai dashboard and any linked pull requests.

Step 6: Add replay to CI

Add a Relai replay step to your GitHub Actions workflow:

- name: Relai replay verification
  uses: relai-hq/action@v1
  with:
    api-key: ${{ secrets.RELAI_API_KEY }}
    agent-path: ./my_agent.py
    bundle-dir: ./relai-bundles

This step will replay all bundles in the specified directory against your current code and post a status check to the pull request. The PR cannot merge while any replay returns FAIL.