relai optimize improves the agent against selected learning environments and registered benchmarks.
Select behavior
Optimization applies to one target at a time. In a multi-target repository,
pass
--agent-target {target} rather than applying the selected environments or
benchmarks across every agent.
Runtime
Optimization runs simulations, so configure required runtime values as
described in Environment variables.
Optimizer controls
Sizing a run
Every selected sample is evaluated at least once before RELAI’s scheduler starts prioritizing the weakest ones, so a large benchmark spends much of a small rollout budget on its first full pass. For quick iteration against a large suite, register a subsample — especially the cases you already know fail — and keep the full benchmark for occasional complete passes. When most samples are genuinely challenging, there is no good subsample: give the run a larger rollout budget and let it fix as much as the budget allows. Prefer a smaller--batch-size when single runs of your agent produce long
trajectories — long conversations, deep tool-call or reasoning chains — since
each optimizer turn has to reason over every trajectory in the batch. When
each simulation is short and fast, a larger batch size is more efficient.
Optimizer scope
Before optimization starts, interactive runs ask you to review the optimizer scope: the guardrails that define what kinds of changes RELAI may make to your agent. RELAI shows the current scope and lets you proceed or edit it. The confirmed scope is saved to.relai/optimizer-scope.json and reused by later
non-interactive runs.
The scope controls:
Allowed changes: choosePrompt/config onlywhen RELAI should stay limited to prompts, instructions, configuration values, and model settings. ChooseStructural changes allowedwhen RELAI may also change code, workflow structure, and tools.Model changes: choose whether RELAI may change the AI models currently used by the agent. By default, model changes are not allowed.Allowed models: when model changes are allowed, list the exact replacement model candidates RELAI may use. At least one model is required before RELAI can proceed with model changes enabled.API-key-backed tools: choose whether RELAI may add new tools or integrations that require external credentials or may incur cost. By default, these are not allowed.
.relai/optimizer-scope.json does not exist yet, run relai optimize
interactively once to confirm it.
Evaluation during optimization
You do not need to runrelai simulate before optimizing.
Each optimizer run evaluates the agent itself: the reserved 2/3 of
--total-rollouts pays for a “before” evaluation pass at the start and an
“after” pass that verifies the final changes. Earlier simulation results are
not reused.
Optimizer evaluations run through the simulator, so each rollout scores the
selected environment’s or benchmark’s own evaluators plus every
global evaluator whose
scope matches the simulation. When an evaluator already scores perfectly in
the “before” pass, there is nothing for the optimizer to fix for it, and the
agent is left unchanged in that respect.
Candidate changes are accepted only when the overall evaluation result
improves. RELAI weighs evaluators against each other — a large gain on one
with a slight regression on another can pass, while trading equal gains for
equal losses cannot — and reviews whether the change is sensible overall
rather than applying a purely numerical threshold. A candidate that causes a
regression is rejected, and the optimizer records the lesson and tries a
different approach. When no candidate survives, the run reports that it could
not improve the agent and finishes with no accepted changes and no PR.
Where optimization happens
relai optimize never edits your checkout directly. Each run prepares a
separate git worktree under ~/.relai/worktrees at your current HEAD, makes
and verifies candidate changes there, and commits accepted changes to a local
branch named relai/optimizer/{subject}-{timestamp} in your repository.
This is also why optimization requires a clean tracked tree: candidate
changes are made and evaluated relative to HEAD, and there would be no
reliable way to reconcile them with uncommitted local edits. Commit or stash
tracked changes before running it.
To review accepted changes locally:
~/.relai/worktrees, so git checkout relai/optimizer/{branch} in your main
checkout fails with “already checked out”. Inspect the files in the worktree
directly, or detach the branch first with
git worktree remove {worktree-path} and then check it out normally.
Pull requests
When GitHub CLI (gh) is available and
authenticated, relai optimize pushes the optimizer branch and opens a pull
request for accepted changes so they can be reviewed in GitHub.
With
--no-pr, accepted changes stay on the local optimizer branch; review
them with the commands above and merge or open a PR yourself.
Early stopping
Examples
What to expect
- optimizer progress and rollout results.
- generated or updated optimizer scope at
.relai/optimizer-scope.json. - accepted changes committed to a local
relai/optimizer/…branch. - optional PR output when GitHub CLI (
gh) is available and authenticated, unless--no-pris set.
--total-rollouts should be set high enough to leave sufficient optimization budget after the 1/3 split. A run needs at least 6 * batch-size total rollouts to start one optimizer turn. Larger values allow more optimization turns before the reserved final evaluation pass.
Common failures: missing simulator, dirty tracked files, missing runtime credentials, invalid rollout or batch-size limits, backend optimizer failure, or missing GitHub CLI (gh) for automatic PR flows.