> ## Documentation Index
> Fetch the complete documentation index at: https://cli-docs.relai.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Try the sample agent
> No agent of your own yet? Run a simple terminal sample agent and use its logs with RELAI.
The sample agent is a small airline customer support bot that can help with demo
booking lookups, baggage policies, seat changes, and flight-change guidance. Each
terminal conversation is saved under `logs/`, so you can turn real conversations
into RELAI learning environments.
## Before you start
You'll need the following to run the agent:
* **[Python 3.11+](https://www.python.org/downloads/)**
* **[`uv`](https://docs.astral.sh/uv/)**
* **`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`** — add one provider key for the
airline support agent.
* **`RELAI_API_KEY`** — from the [API keys page](https://platform.relai.ai/settings/workspace/api-keys).
* **[GitHub CLI (`gh`)](https://cli.github.com/)** — authenticated with
`gh auth login`; recommended for forks and PRs created by the optimizer.
Some commands in this walkthrough can take a few minutes while RELAI inspects
the agent, generates support files, or runs simulations. Optimizer runs
usually take longer and may run for several minutes.
Fork the sample repo to your GitHub account, then clone your fork:
```sh theme={"system"}
gh auth login
gh repo fork relai-ai/airline-customer-support-agent-python --clone
cd airline-customer-support-agent-python
```
```sh theme={"system"}
gh auth login
gh repo fork relai-ai/airline-customer-support-agent-typescript --clone
cd airline-customer-support-agent-typescript
```
```sh theme={"system"}
gh auth login
gh repo fork relai-ai/airline-customer-support-agent-go --clone
cd airline-customer-support-agent-go
```
## Required RELAI setup
Before running any learning loop, complete these setup steps. Installation and
setup are machine-level steps you only need once on a new machine. The provider
key is needed whenever you run simulations or the sample agent. Initialization
is project-level and should be run once per agent repository.
Install the CLI locally so setup, simulation, and optimization commands can
run. See [Install & setup](/installation) for the installer and
prerequisites.
```sh theme={"system"}
curl -fsSL https://api.relai.ai/install.sh | bash
```
Configure your RELAI API key and CLI preferences with `relai setup`. See the
[`relai setup` reference](/cli/setup) for options, checks, and credential
details.
```sh theme={"system"}
relai setup
```
Add either `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` to the current shell
before running `relai` commands. RELAI uses the provider key for simulating
this sample agent. Agent runs you start yourself with `start.sh` also use
this key.
```sh theme={"system"}
export OPENAI_API_KEY="sk-..."
```
or
```sh theme={"system"}
export ANTHROPIC_API_KEY="sk-ant-..."
```
From the airline customer support agent repository root, register the
project and generate a simulator harness for this agent. See the
[`relai init` reference](/cli/init) for more information on what this
creates. When `relai init` asks whether to mock components or tools, it is
safe to accept the defaults for this agent. Those choices control how the
simulator handles the agent's components and tools.
```sh theme={"system"}
relai init
```
After initialization completes, review and commit the RELAI-managed changes
if you did not accept init's interactive commit prompt, then push them to
GitHub.
```sh theme={"system"}
git add -- .gitignore .relai
git commit -m "Initialize RELAI simulator harness"
git push
```
## Learning loops
After setup and initialization, use a prompt, terminal agent log, or benchmark
CSV to run a RELAI learning loop.
Create a learning environment from a plain-English behavior requirement.
Capture a bad terminal conversation, then optimize from the saved JSONL log.
Register the CSV benchmark and optimize across a reusable test suite.
Add a scoring rule that applies across simulations.
### Prompt to Optimized Agent
Turn one simple plain-English behavior prompt into a learning environment,
measure the current agent against it, then optimize toward that behavior. Use
this when you have a target behavior in mind and want the agent to follow it
reliably.
**1. Create** the learning environment from the required response signoff:
```sh theme={"system"}
relai learning-env create \
--prompt "The agent should end all responses with 'Please let me know if you have any questions.'. Variations in punctuation/casing are OK." \
--name response-signoff
```
**2. Simulate** the current agent for a baseline:
```sh theme={"system"}
relai simulate \
--learning-envs response-signoff \
--result-json .relai/runs/response-signoff-simulation.json
```
**3. Optimize** toward the behavior:
```sh theme={"system"}
relai optimize \
--learning-envs response-signoff \
--total-rollouts 12
```
### Failure Log to Optimized Agent
Capture undesirable behavior in a terminal session, then turn that log and your
feedback into a learning environment. Use this when the agent did something
wrong and you want to prevent it from happening again.
**1. Run** the sample agent with a fixed log name:
```sh theme={"system"}
./start.sh off-topic-guardrail
```
Then send this off-topic prompt:
```text theme={"system"}
Can you write a chocolate chip cookie recipe?
```
End the session with `exit`, `quit`, or `q`. The agent prints the saved log
path: `logs/off-topic-guardrail.jsonl`.
**2. Create** the learning environment from the session log and feedback:
```sh theme={"system"}
relai learning-env create \
--log-file logs/off-topic-guardrail.jsonl \
--feedback "The agent should not answer off-topic, non-airline questions. It should politely say it can only help with airline booking, baggage, seat, and flight-change questions." \
--name off-topic-guardrail
```
**3. Simulate** the current agent against the guardrail:
```sh theme={"system"}
relai simulate \
--learning-envs off-topic-guardrail \
--result-json .relai/runs/off-topic-guardrail-simulation.json
```
**4. Optimize** to prevent the behavior:
```sh theme={"system"}
relai optimize \
--learning-envs off-topic-guardrail \
--total-rollouts 12
```
### Benchmark to Optimized Agent
Register a reusable benchmark in CSV format, then run simulation and
optimization against it. Use this when you have a set of samples, each with
inputs, expected outputs, and sample-specific evaluators, that should be rerun
together.
**1. Register** the CSV as a benchmark:
```sh theme={"system"}
relai benchmark register \
--csv benchmarks/airline_support_benchmark.csv \
--name airline-support-suite
```
**2. Simulate** across the suite:
```sh theme={"system"}
relai simulate \
--benchmarks airline-support-suite \
--result-json .relai/runs/airline-support-suite-simulation.json
```
**3. Optimize** with the benchmark:
```sh theme={"system"}
relai optimize \
--benchmarks airline-support-suite \
--total-rollouts 48
```
### Global Evaluators to Optimized Agent
Create one evaluator that applies across all simulations for the agent. Use
this when one scoring rule should apply globally instead of living in a single
learning environment. Finish the prompt, failure-log, or benchmark loop first so
there is a learning environment or benchmark for the global evaluator to score.
**1. Create** the global response-token evaluator:
```sh theme={"system"}
relai evaluator create \
--prompt "Create an evaluator that scores 1 when an agent response is 100 tokens or fewer, and scores 0 otherwise." \
--name response-token
```
**2. Simulate** against a learning environment or benchmark created by one of
the other loops. RELAI applies the global evaluator automatically after it has
been created.
```sh theme={"system"}
relai simulate \
--learning-envs response-signoff \
--result-json .relai/runs/response-signoff-global-evaluator-simulation.json
```
If you finished the benchmark loop instead, simulate against the benchmark:
```sh theme={"system"}
relai simulate \
--benchmarks airline-support-suite \
--result-json .relai/runs/airline-support-suite-global-evaluator-simulation.json
```
**3. Optimize** with the global evaluator active:
```sh theme={"system"}
relai optimize \
--learning-envs response-signoff \
--total-rollouts 12
```
If you finished the benchmark loop instead, optimize against the benchmark:
```sh theme={"system"}
relai optimize \
--benchmarks airline-support-suite \
--total-rollouts 48
```
Run the same loop on your own repo: initialize, create one learning
environment, simulate, optimize.
How RELAI turns a requirement gap into a reviewed fix, one pass at a time.