Vantage documentation

Agent recipes

Copyable patterns for agents operating Vantage. Prefer these observation/action/re-observation loops over long brittle action chains.

Navigate and click by meaning

vant agent tabs
vant agent open https://example.com 1
vant agent call page.wait '{"tab_id":1,"selector":"body","timeout_ms":5000}'
vant agent snapshot 1
# resolve the desired element from role/name
vant agent click @e2_4 1
vant agent snapshot 1

Fill and submit a form

vant agent snapshot 1
vant agent fill @e5_2 'agent@example.com' 1
vant agent fill @e5_3 'example value' 1
vant agent click @e5_4 1
vant agent call page.wait '{"tab_id":1,"text":"Saved","timeout_ms":10000}'

After any mutation that invalidates refs, resnapshot before continuing.

Call a JSON API

vant agent fetch https://api.example.com/v1/items '{
  "method":"POST",
  "headers":{"Authorization":"Bearer REDACTED","Content-Type":"application/json"},
  "body":"{\"name\":\"created by agent\"}"
}'

Inspect status/ok. HTTP errors are results, transport errors are fetch_error. See API fetch.

Read API then update page

# 1. net.fetch API data
# 2. parse returned body
# 3. snapshot the target page
# 4. fill/click using semantic refs
# 5. wait for confirmation
# 6. snapshot again to verify

Debug a frontend

vant agent call page.diagnostics.clear '{"tab_id":1}'
vant agent call browser.reload '{"tab_id":1}'
vant agent call page.wait '{"tab_id":1,"selector":"body","timeout_ms":10000}'
vant agent call page.diagnostics '{"tab_id":1}'
vant agent call page.native_diagnostics '{"tab_id":1}'
vant agent snapshot 1

Recover from a stale ref

page.interact => {ok:false,error:"stale_or_missing"}
# do not invent @e refs
vant agent snapshot 1
# resolve target again by role/name
vant agent click NEW_REF 1

Recover from a missing tab

RPC => not_found
vant agent tabs
# identify the intended live tab; do not assume IDs were reused

Multi-tab work

vant agent call browser.tabs '{}'
vant agent call browser.tab.new '{"window_id":1,"uri":"https://example.org"}'
vant agent call browser.tab.select '{"tab_id":2}'
vant agent call page.snapshot '{"tab_id":2}'

Always carry explicit tab_id through multi-tab workflows.

Use JavaScript only when useful

vant agent js 'Array.from(document.querySelectorAll("article")).map(x=>x.innerText)'

For routine controls, semantic operations are easier to recover and audit. For direct HTTP, use net.fetch. JavaScript is the page-level escape hatch.

Safe retry rule

GET/read operation failed before response?     retry may be reasonable
POST/PATCH/DELETE timed out?                   inspect first
click "Purchase" timed out?                   inspect resulting state first
stale semantic ref?                           resnapshot, then decide