Skip to main content
Agent Preference shows which products agents choose and why. When an agent passes on your product, it gives a reason: an objection. An optimization tests whether a change to the pages agents read during research answers that objection. Gauge reruns the same preference sessions with your edits in place and analyzes the reruns. Each original objection comes back resolved or returned, and new ones show as introduced. Nothing deploys. The result is a diff and a summary that you apply through your usual review process. To fix problems agents hit while they use your product, see Improve agent experience.

​
What you can change

Agents decide from the pages they read while they research. An optimization can edit any page a session fetched, or add a new one: Each page is a page:<url> file in the optimization’s tree. Anything not in the tree reruns as the session had it. You can also change a Skill (skill:<name>) if the sessions staged one.

​
Choose what to improve

A finding is one reason in one session. An issue is the same finding across many sessions. The web app lists issues as themes on the Findings tab of Agent Preference. Start with the objections that cost you the most sessions. Each objection shows where agents went instead. Read the findings and their evidence before you name a cause. An agent that chose a competitor because it never found your pricing page needs a different fix than one that read the page and found no free tier. Check what the agents actually read. If they never reached your site, an edit to your pages cannot change the result. You can test an edit to a third-party page, such as a comparison article, as a what-if. You cannot ship that change.

​
Start an optimization

Click Optimize in any of these places:
  • A theme on the Findings tab of Agent Preference. The optimization reruns up to 12 of the theme’s most recent sessions.
  • A finding on a run page. The optimization reruns that session.
  • The Optimizations page, under Start a new optimization. Choose a theme on the Objections tab.
Starting an optimization launches nothing and uses no credits.

​
Work with Ask Gauge

The optimization opens in an Ask Gauge chat. Tell it what to focus on or which sessions to skip, or reply “start”. Ask Gauge works in stages and ends each turn with one question about the next step:
  1. Diagnose and edit. It reads the objections and the pages the agents fetched before they chose. It says which pages carried the decision and which you own, then edits copies of them.
  2. Rerun. It asks before every launch, even in auto mode. Reruns use credits like any run.
  3. Read. Gauge wakes the chat as reruns finish. Ask Gauge compares the findings and updates its notes.
  4. Finish. It records the result.
Reply “yes” to approve the step it names, or type a reply to steer it. The panel beside the chat has three tabs:
  • Changes shows each changed page with its diff against the original.
  • Coding Sessions lists the reruns. Open one to see where it read your change.
  • Agent scratchpad holds the diagnosis, each edit and why, and what each rerun showed.

​
Run the loop from the CLI

These CLI commands use hosted Gauge. The CLI uses the local backend by default, so set hosted once after you sign in, or add --hosted to each command. See Choose a backend.
Find objections and their findings:
Create an optimization and read its authoring guidance:
To start from one finding, pass --finding <finding-id> --run <run-id>; gauge run insight <run-id> shows finding IDs and the agent’s product choices. To start from a goal with no source sessions, pass --goal "<text>". See which pages the agent read and searched for before it chose:

​
Edit the tree

Copy each page into the tree before you edit it, so the diff shows only your change. Gauge copies the version the session read, or the live page if no session read it:
edits.json is a list of {"find": "...", "replace": "..."} on the page’s exact source. Copy the find text from file read --query. Each find must match once, and all edits apply or none do. The output shows how much of the page you kept. For a new page or a full rewrite, write the complete body. For example, to add an llms.txt:
Read a page before you change it, keep its purpose, and source every new fact. A claim your product does not support can win the rerun and still mislead real agents. To drop a page from the tree, use file rm <optimization-id> <key>. Keep your diagnosis, plan, and each launch’s result in the optimization’s notes:

​
Rerun and compare

A launch reruns each source session with the same prompt, scenario, agent, model, and settings, plus your tree. It lists the changed pages; check that every edit you meant to test is there. Rerun only the sessions your edits address. Pass --yes only for a launch that is already approved. watch waits until every rerun finishes and is analyzed. It then shows each source objection as resolved or returned, and new findings as introduced. To read a launch again, use gauge optimizations launches <optimization-id> <launch-id>. Before you credit an edit, run gauge run web <rerun-id> to confirm the rerun read the changed page. Then check what the rerun chose with gauge run insight <rerun-id>. An objection can resolve while the agent still picks a competitor for another reason. Agents choose differently from run to run, so do not trust one rerun. Edit and launch again in the same optimization until the objection resolves.

​
Finish

result.json is {summary, changed, resolved, returned, introduced}: a PR-style summary, the changed tree keys, and the findings in each group as {runId, label}. After you finish, the tree can no longer change. For a coding agent, gauge instructions issues and gauge instructions optimization describe the full workflow.

​
Ship the change

In the web app, click Copy for agent. It copies the changes and evidence as a prompt for your coding agent, which applies them where your site’s files live. Review and publish the change through your usual process. After you publish, run the preference prompt again against the live site. Agent Preference results vary between runs, so compare enough sessions across the agents and models you care about.