Vantage documentation

Agent WebKit and page reference

Use semantic operations first; use arbitrary JavaScript and WebKit introspection when the semantic layer cannot express the task. All page operations target an explicit live Vantage tab.

Snapshot then act

vant agent call page.snapshot '{"tab_id":1}'
# => {generation:3,url:...,title:...,elements:[{ref:"@e3_1",role:"link",name:"Docs",...}]}

vant agent call page.interact '{"tab_id":1,"ref":"@e3_1","action":"click"}'

Snapshots inventory up to 500 interactive candidates including links, buttons, inputs, textareas, selects, summaries, roles, contenteditable and tabindex targets. Names are derived from accessible/title/text/value/placeholder signals and bounded for compact trajectories.

Interaction actions

click | focus | fill | type | clear | select | check | uncheck | scroll | key

vant agent call page.interact '{"tab_id":1,"ref":"@e4_2","action":"fill","value":"agent@example.com"}'
vant agent call page.interact '{"tab_id":1,"ref":"@e4_3","action":"key","value":"Enter"}'

A target can be supplied by semantic ref or CSS selector. Prefer refs after a snapshot. A hidden/disabled/stale target is explicit rather than silently forced.

Waits

vant agent call page.wait '{"tab_id":1,"text":"Complete","timeout_ms":5000}'
vant agent call page.wait '{"tab_id":1,"selector":"main.ready","timeout_ms":10000}'
vant agent call page.wait '{"tab_id":1,"ref":"@e7_4","timeout_ms":3000}'

Wait timeout is bounded to 30 seconds. Prefer state-based waits to arbitrary sleeps.

Inspection

vant agent call page.inspect '{"tab_id":1,"kind":"text"}'
vant agent call page.inspect '{"tab_id":1,"kind":"html"}'
vant agent call page.inspect '{"tab_id":1,"kind":"selection"}'
vant agent call page.inspect '{"tab_id":1,"kind":"metadata"}'

Use full HTML only when needed; semantic snapshots are usually much smaller and more task-oriented.

Arbitrary JavaScript

vant agent js 'document.title'
vant agent js '({url:location.href,count:document.links.length})'
vant agent js --file script.js
cat script.js | vant agent js -

JavaScript executes in page context and follows normal WebKit origin/security rules. It does not grant the page a reverse bridge into Vantage.

API requests

Do not use page JavaScript just to call a public API unless page-origin semantics are required. Prefer net.fetch, which accepts method, headers and body directly and avoids page CORS.

WebKit introspection

vant agent call webkit.webview '{"tab_id":1}'
vant agent call webkit.settings '{"tab_id":1}'
vant agent call webkit.network '{"tab_id":1}'
vant agent call webkit.setting.set '{"tab_id":1,"name":"enable-javascript","value":true}'

Property surfaces reflect the installed WebKitGTK build. Discover and validate rather than assuming a property exists across versions.

Screenshot

vant agent call page.screenshot '{"tab_id":1,"path":"/tmp/page.png"}'

Use screenshots when visual state matters; do not substitute screenshots for semantic state when the task is text/DOM based.