Relai Developer Docs

Overview

Relai captures AI agent failures at the exact moment they occur, preserving the complete execution environment as a portable replay bundle. Those bundles become deterministic test cases that run in CI, blocking merges when a proposed fix does not pass replay verification.

How it works

The Relai flow has three stages:

1. Capture: Wrap your agent execution with relai.capture(). When a failure occurs, Relai snapshots the full tool call trace, model context, and environment state into a .rli bundle file.
2. Replay: Run relai verify --bundle <file> against your proposed fix. Relai re-executes the captured failure in an isolated environment seeded from the bundle, producing a deterministic pass or fail verdict.
3. Block or merge: The replay verdict posts back to your GitHub or GitLab pull request as a status check. A FAIL status blocks the merge until the fix is verified.

Installation

Install the Relai SDK with pip:

pip install relai-sdk

Authenticate with your API key:

relai auth --key rli_live_xxxx

Basic usage

Wrap your agent entrypoint with the capture context manager. You can use the synchronous or async form depending on your agent framework:

import relai

async def run_invoice_agent(payload: dict):
    async with relai.capture(agent_id="invoice-extractor") as ctx:
        result = await agent.run(payload)
        return result

When a failure occurs within the capture() context, Relai automatically saves a .rli bundle to your configured output path and posts a failure event to the Relai dashboard.

Next steps

• Follow the Quickstart guide to instrument a real agent in under 10 minutes.
• Read the full API reference for all capture configuration options.
• Set up CI integration to automate replay verification on every pull request.