> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ambral.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# Introduction

> Ambral helps you pick the best model for each of your agents, by cost, quality, or latency, measured on your own production traffic.

Ambral helps you pick the best model for each of your agents, by cost, quality, or latency, measured on your own
production traffic.

You can get started by changing fewer than ten lines of code in your existing codebase, and start measuring other
models against your production tasks.

## How it works

**1. Connect**

Point the OpenAI or Anthropic client your agent already uses at Ambral: a base URL, an Ambral key, and a few
request settings that name the task and the session. Your prompts, your tools and the calls your code makes
stay as they are. Requests are answered by the model you choose.

**2. Record**

Each session your agent runs is recorded as a **trace**: every model call it made, with its tool calls,
tokens and latency.

**3. Evaluate**

You build evals from the recorded sessions that matter, and say what a good reply looks like. Ambral replays
those sessions to each candidate model and scores its replies beside the ones production gave. The results
show the sessions where a model falls short, and what each model would cost to serve.

**4. Switch**

When a candidate holds up, you promote it. Ambral serves it within about a minute, your agent's code doesn't
change, and the same command takes you back. Nothing switches until you say so.

Checking a new model usually means building a test set by hand and hoping it resembles real traffic, so the
model an agent started on tends to stay. With Ambral the test set is your traffic. When the evals show a model
holds up, you switch to it with one command and no change to your agent's code.

After a switch or a prompt change, the same evals run on your newest traffic show whether quality still holds.

## Two kinds of eval

A **replay run** scores candidates on your recorded sessions, one reply at a time. It needs no environment, no
tools and no test suite, so it is where to start. An **offline run** is your own eval suite's: the suite runs
whole sessions on a candidate and reports the scores to Ambral.

Replay runs show where to look. Offline runs check whole sessions before a candidate serves your users. Most
agents should have both.

## How you use it

You drive Ambral with the `ambral` CLI, and most people let their coding agent do it. The CLI installs a skill
into your project that teaches Claude Code, Codex, Cursor and other agents how to connect your app, build evals
from its recorded sessions, run them and read the results.

## Where to go next

> [card] [Quickstart](https://docs.ambral.ai/quickstart.md)
>
> Install the skill, ask your agent to connect your app, and see your first trace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.