Skip to main content
Use an optimization to test whether a change to your docs or skills helps agents do better. Gauge runs the task with the change and compares the results. Each test is called a trial.
Optimizations is enabled per organization. Where available, use the measurement’s Improve section. Organizations still using the earlier workflow can create legacy content experiments. With Optimizations enabled, old experiments remain readable but cannot be authored or modified.

​
Plan a useful comparison

Start with completed results and a specific problem. For example, an agent repeatedly misuses an API because the setup page omits a required initialization step. In Improve, choose the page or skill you want to change from the available options. Make a change that helps developers use your product. Keep the task and pass criteria the same so you can tell whether the change helped. Choose one agent and model. Set how many rounds to try and how many times to run each trial. More runs give you more evidence, but cost more. Review the estimate before starting.

​
Start from the CLI

List available models, ask Gauge to identify problems in the eval, and estimate the cost of a small test:
Use a target from the model catalog in place of <harness:model>. To optimize preference, replace --eval <eval-id> with --preference <prompt-id>. Add --no-auto-adopt if you want to review changes before Gauge uses them in later trials:
Alternatively, --effort low|medium|high|xhigh selects a preset plan. Do not combine --effort with --samples or --rounds. Gauge sets aside the estimated credits when you start. Use --credit-cap to choose a different amount. Gauge stops launching trials when the budget runs out, but sessions already running can still cost more than estimated.

​
Review trials and adoption

Read the proposed change and compare the results. Open the sessions to see why the score changed. Repeat important tests: one better run does not prove that the change will help every time. When a finished trial is marked BETTER, you can adopt it:
Adopt means Gauge uses the change as the starting point for later trials. CLI starts do this automatically unless you add --no-auto-adopt. Your original eval settings and published site stay unchanged.

​
Pause, cancel, and ship

Pause lets current sessions finish and stops new ones from starting. Cancel stops the optimization, ends its running sessions, and returns credits it set aside but did not use. An optimization can also stop at its round limit, target score, budget, repeated lack of improvement, or an error. Review the final change and publish it through your usual content or code workflow. For a docs rewrite, gauge optimizations change <optimization-id> <trial-id> --body prints the page body. A shipping marker in Gauge records your action; it is not a deployment. After publishing, run the task again against your live docs or skill. Try other relevant tasks and models too, to check that the change helps beyond this one eval.