# Agent setup

Source: https://webagent-docs-staging.lookover.ai/qa-testing/agent-setup

> A snippet to paste into AGENTS.md or CLAUDE.md so your agent runs webagent smoke tests the right way and reports clearly.

Your agent can see webagent's tools after you [connect it](/qa-testing), but it does not know how you want to test. A short instruction file fixes that. It tells the agent which tool to pick, how to wait for a result, what to do with a `localhost` app, and what a good report contains.

## Where to put it [#where-to-put-it]

| Agent | File |
|---|---|
| Codex CLI | `AGENTS.md` in your project root. Codex also reads `~/.codex/AGENTS.md` for every project. |
| Claude Code | `CLAUDE.md` in your project root. Claude Code also reads `~/.claude/CLAUDE.md` for every project. |

Use the same text for both. The snippet calls the server `lookover-webagent`, the name used in the connect pages. If you chose another name, change it.

## The snippet [#the-snippet]

````markdown
## Smoke testing with webagent

Use the `lookover-webagent` MCP tools to test web apps in a cloud browser.
Do not use a local browser for this.

### Pick the tool
- To test a page or a flow (load, log in, sign up, check out, submit a form):
  `smoke_test`. Give it `url`, the plain-language `steps`, and what must be true
  afterwards: `expectText` (text that must be on the page), `expectUrl` (text the
  address must contain) and `expectNoText` (text that must not be on the page).
  One call opens a recorded browser, runs the test and returns a report.
- To explore, or to do something open-ended: `run_task` with a goal in plain
  language. It checks nothing: `ok` only means the agent says it is done.
- Only to read a page: `scrape` or `screenshot`.
- Always give `smoke_test` an `expectText`, `expectUrl` or `expectNoText`. Without
  one it only checks that the page loads, the links work and the console is clean.

### Waiting
- `smoke_test` waits up to 60 seconds. If the verdict is `running`, call `get_report`
  with the `id` from the result until the verdict is `pass`, `fail` or `error`.
- A `run_task` that is not done in about 90 seconds answers with `status: running`,
  a `sessionId` and a `taskId`. That is normal. Call `get_report` with the `taskId`
  until it has finished. Then call `stop_session` for a session you left open.
- To keep one browser over several `run_task` calls, give the first one `startUrl`
  and `keepOpen: true`, and pass the same `sessionId` to the next ones (without
  `startUrl`). Call `stop_session` at the end.

### Apps on localhost
The cloud browser cannot open `localhost` or private addresses. If the app is on
localhost, start a tunnel in the shell first:
`cloudflared tunnel --url http://localhost:<port>`.
Read the `https://...trycloudflare.com` address it prints and use that as `url`.
Stop the tunnel when the test ends. Tell me that the app is open to the internet
while the tunnel runs.

### Test data and secrets
- Log in only with the test account I give you. Never use a real person's account.
- Never put API keys, tokens or real passwords in a goal, a step or the report.
  Goals and steps are stored with the run.
- Only test sites I own or may test. If a page shows a CAPTCHA, stop and report it.
  Do not try to get past it.

### Read the result
- Read `verdict` in the report, not only `isError`. `fail` means the test ran and
  found a problem. `error` means the test could not run. A failed test is a normal
  result, not a tool error.
- For a `run_task` report, `pass` only means the agent says it is done. Say so.
- Console errors and failed network calls come from a log that is saved when the
  session ends. If the report says the log is not available, call `get_report` again
  after a few seconds before you say there were no errors.

### Report
Finish with a report that has:
1. Verdict: PASS, FAIL or COULD NOT TEST (the report's `pass`, `fail` or `error`).
   - FAIL: the app did something wrong, and you can say what and where.
   - COULD NOT TEST: the test did not run to a result (CAPTCHA, blocked address,
     cancelled run, an error from the tool). Do not call this a bug in the app.
2. The URL tested (`url`), and where the browser ended (`finalUrl`).
3. The `summary` of the report, then one line per failed step: its `title`, its
   `error` and its screenshot link.
4. Console errors and failed network calls: the first few, with their `text`,
   `method`, `url` and `status`. Give the totals from `counts`.
5. Findings (broken links, accessibility), worst first, with the `fix` line.
6. Evidence: the session id, the report link and the recording path. The links
   expire in minutes (`evidence.urlsExpireAt`), so say when the report was made.
   Do not claim to have seen anything the tool results do not show.
````

## What each rule is for [#what-each-rule-is-for]

- **`smoke_test` first.** One call gives a verdict from real checks and a report with the proof. A goal task checks nothing, so the snippet keeps it for exploring.
- **Expectations.** A smoke test that has no `expectText`, `expectUrl` or `expectNoText` only checks that the page loads and is clean. The text you expect is what makes a flow pass or fail.
- **Polling.** The MCP server answers in one reply and waits at most 90 seconds. A longer test keeps running, and `get_report` reads the result when it is ready. See [Tasks](/concepts/tasks).
- **One `sessionId` per task flow.** A browser that is closed loses its page, its cookies and its login. `run_task` closes a session it opened unless you pass `keepOpen`, so a multi-step task flow needs `keepOpen` on the first call and the same `sessionId` after it.
- **Tunnel.** A cloud browser cannot reach your machine. A tunnel gives the app a public address for as long as it runs. Anyone with the address can open your dev server while it is up, so use test data and close it after.
- **Verdicts.** `fail` means the app is wrong. `error` means the test could not run. The snippet asks the agent to say which. [Reading results](/qa-testing/reading-results) explains the report and lists every stop reason of a task.
- **Secrets.** The text of a goal or a step is stored with the task or skill run and can show up in reports. The agent has to type the test password into a goal, so use a throwaway test account whose password you can change afterwards.

## Tips [#tips]

- Keep the file short. If the agent skips a rule, move that rule to the top.
- Re-read the first report with care. If the agent calls a test a PASS without evidence, tighten the "Report" rules.