browser_observe
Agent-native page observation. Returns the compacted OwlMark render (text-only structural view of the page), a handle table of interactive elements with stable tokens, page metadata, and a token estimate. Pass a handle token (e.g. 'b3') or 'pm:N' to browser_click/browser_type. Requires the context to be created with render_mode 'agent' or 'both'. ~20-100x fewer tokens than a screenshot for AI agent page understanding.
When to use browser_observe
Use browser_observe when you need to render a page as a compact, handle-addressable view built for AI agents. It is part of Owl Browser's Agent Rendering toolset and runs inside a self-hosted, source-level stealth engine, so every call inherits the same undetectable browser fingerprint as the rest of your automation — no separate anti-detect setup required.
Usage Example
Parameters
Required
context_idstringrequiredThe unique identifier of the browser context (e.g., 'ctx_000001'). The context must have been created with render_mode 'agent' or 'both'
Optional
detailenumminnormalfulloutlineCompaction aggressiveness. 'min': collapse boilerplate/dedup hardest. 'normal' (default). 'full': expand everything except offscreen-far buckets. 'outline': tight headings-only crop (doc header + heading outline, no body): 5-10x cheaper for reach-and-read tasks on long references
regionstringFilter to a specific page region: 'main', 'nav', 'header', 'footer', 'sidebar', 'article', 'form', 'dialog'. Empty = whole page
max_tokensintegerSoft token budget (0 = none). The salience scorer honors per-region guarantees so a budget never drops the only actionable control in a region
deltabooleanOpt IN to delta-observes (default false = always full). When true, re-observing the same tab while nothing changed returns a compact @delta block (a pure speedup, losslessly reconstructable from the prior full snapshot + the delta) instead of a full render+handle table. Only enable if the consumer maintains a delta reconstructor; the default full render is the byte-stable contract every standard consumer expects
full_refreshbooleanForce a FULL snapshot even when delta=true (back-compat opt-out of the delta channel). Has no effect when delta is false, since full is already the default
Response
Returns a JSON object with the operation result.
{
"success": true,
"result": <value>
}Frequently Asked Questions
What does browser_observe do?
Agent-native page observation. Returns the compacted OwlMark render (text-only structural view of the page), a handle table of interactive elements with stable tokens, page metadata, and a token estimate. Pass a handle token (e.g. 'b3') or 'pm:N' to browser_click/browser_type. Requires the context to be created with render_mode 'agent' or 'both'. ~20-100x fewer tokens than a screenshot for AI agent page understanding. It belongs to Owl Browser's Agent Rendering category and is available through the REST API, the Python SDK (browser.observe()), the Node.js SDK, and the MCP server.
What parameters does browser_observe accept?
browser_observe accepts 1 required parameter (context_id) and 5 optional parameters. All parameters are sent as JSON in a POST request to /api/execute/browser_observe.
Is browser_observe detectable by anti-bot systems like Cloudflare or DataDome?
No. browser_observe executes inside Owl Browser's Chromium engine, which applies fingerprint spoofing at the C++ source level rather than through JavaScript patches. Every tool call shares the same consistent, human-like fingerprint, so anti-bot systems such as Cloudflare, DataDome, and Akamai see an ordinary browser.
Related Tools
browser_expandRe-serialize one collapsed region, dedup template, or handle at higher detail. Use after browser_observe when a region was folded for the token budget. Requires render_mode 'agent' or 'both'.
browser_read_nodeRead the raw accessible name, value, description, and attributes for one handle, uncompacted. Use after browser_observe to inspect a single element in full. Requires render_mode 'agent' or 'both'.
browser_create_contextCreate a new isolated browser context with its own cookies, storage, and optional proxy configuration. Each context acts as an independent browser session. Use this to create multiple isolated browsing sessions, configure proxy/Tor connections, load browser profiles with saved fingerprints, and enable/disable LLM features. Returns a context_id to use with other browser tools.
browser_navigateNavigate the browser to a specified URL. This is a non-blocking operation that starts navigation and returns immediately. Use browser_wait_for_network_idle or browser_wait_for_selector to wait for the page to fully load. Supports HTTP, HTTPS, file, and data URLs. When wait_until is set (load, networkidle, fullscroll, domcontentloaded) and the page declares WebMCP tools, the response includes a webmcp_tools array containing the full tool definitions (name, description, inputSchema). Use browser_webmcp_call_tool to execute any of these tools directly.
browser_clickClick on an element using CSS selector, XY coordinates, or natural language description. Supports semantic element finding using AI - describe what you want to click (e.g., 'login button', 'search icon') and the system will locate the right element. Simulates a real mouse click with proper event dispatch. Optionally hold the mouse button for press-and-hold interactions using hold_ms.
browser_typeType text into an input field with human-like keystroke simulation. Target the field using CSS selector, coordinates, or natural language (e.g., 'email field'). When selector is omitted, types into the currently focused element. Note: Does NOT clear existing content - use browser_clear_input first if you need to replace text rather than append.