Vantage documentation

Agent use

Operational guide for software agents controlling Vantage. Discover first, choose the narrowest primitive, preserve runtime IDs and generation-scoped refs, and recover from explicit errors instead of guessing.

Command map

status, version, capabilities

Start here. Protocol 1 is stable but additive, so discovery is authoritative.

vant agent status
vant agent version
vant agent capabilities
vant agent call describe '{}'
vant agent call describe '{"name":"page.interact"}'
vant agent call describe '{"name":"net.fetch"}'

tabs + open

Tab/window IDs live only as long as their object and are never rebound after closure. Navigation is asynchronous; use state-based waits.

vant agent tabs
vant agent open https://example.com 1
vant agent call page.wait '{"tab_id":1,"text":"Example Domain","timeout_ms":5000}'

snapshot, click, fill

Refs such as @e8_2 are generation-scoped, not durable selectors. Normal loop: snapshot → choose ref → interact → wait → snapshot. On stale_or_missing, observe again; never invent a ref.

vant agent snapshot 1
vant agent click @e8_2 1
vant agent snapshot 1
vant agent fill @e9_4 'agent@example.com' 1

fetch

Application-side HTTP: no page CORS and no implicit browser cookies. Supply API authorization explicitly.

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

js

Use for exceptional DOM computation/page-origin behavior; prefer semantic primitives for routine operation.

vant agent js 'document.title' 1
vant agent js 'JSON.stringify({href:location.href,lang:document.documentElement.lang})' 1

call

Every non-convenience method remains reachable through the generic RPC client.

vant agent call page.inspect '{"tab_id":1}'
vant agent call page.diagnostics '{"tab_id":1}'
vant agent call events.since '{"after":0}'

Preferred abstraction order

API/HTTP resource          -> net.fetch
Browser/tab lifecycle      -> browser.*
Routine DOM operation      -> page.snapshot + page.interact
Wait for observable state  -> page.wait
Read content/metadata      -> page.inspect
Rendered evidence          -> page.screenshot
Debug page behavior        -> page.diagnostics
Exceptional DOM logic      -> page.javascript
WebKit properties/state    -> webkit.*
Async lifecycle changes    -> events.*

Error recovery

Deep reference