Browser observations and actions

Use browser_observe and browser_act when an action must refer to the page state you inspected. Both are MCP tools provided by cdp.

Call browser_observe with an empty object to observe the selected frame (the root by default), or pass {"frame_id":"<frame ID>"} for an exact frame in the active target. An explicit frame never falls back to its parent and does not change frame selection. The tool returns a state_id, target_id, document identity, URL, and accessibility tree. Interactive elements in the tree have refs such as @1. Copy the returned identifiers into your action:

{
  "state_id": "<returned state_id>",
  "target_id": "<returned target_id>",
  "action": "click",
  "ref": "@1",
  "expect": {"selector": "#count", "text": "1"}
}

The ref must come from that observation. For typing, use "action": "type" and supply a nonempty text. To navigate the observed frame, use "action": "navigate" and an absolute url; omit ref. timeout_ms defaults to 30000 and accepts values from 1 through 60000; zero selects the default.

A successful observation replaces the previous state. An action consumes its matching state before validation or dispatch, so the same handle cannot be retried after a failed attempt. Unknown state IDs do not consume the current state. Invalid timeout values are rejected before state lookup.

The action checks the exact target context, frame, loader and document node. It also checks that the referenced node is connected to that document. A same-URL reload, detached node, or changed active target requires another observation. A detached node is never replaced by another node with the same name or role.

Before input, the tool activates the target page. Before clicking, it scrolls the node into view and checks that its click point reaches that node or one of its descendants. An overlay covering that point is rejected. Before typing, it checks that focus remains on the observed node, including focus within a shadow tree.

The result separates three questions:

Page activation, scrolling and focusing are action-related side effects. A failure after one of these commands begins is conservatively dispatched_unknown. completed describes browser acknowledgement, not completion of the user’s broader task. If capture fails after acknowledged input, execution remains completed and no fresh_state is returned. Inspect the target before considering another action; a missing observation is not permission to click again.

Navigation waits, within the same timeout, for the acknowledged frame and loader’s DOMContentLoaded event. A same-document navigation needs no new-loader wait. HTTP error pages are valid observations. A readiness or capture failure after navigation acknowledgement leaves execution completed; a lost acknowledgement is dispatched_unknown. A download is reported in error_text and does not imply a new document. Navigation is never automatically retried.

When capture succeeds, use fresh_state for the next action. expect compares the exact textContent of a single CSS match in the captured document, once, without waiting for an eventual value. Missing or multiple matches are unmet; an evaluation error is unknown. It does not compare input values. error_text explains validation, execution, capture, or postcondition failures.

The pair serializes its own requests and publishes complete observations. Page scripts, other tools and users can still change the page between validation and input. This is not a page transaction, and cancellation cannot undo input already sent. An observation records document identity; it does not freeze the DOM or guarantee that an unchanged node still has the same business meaning.

The pair supports clicks, typing and navigation in the active target’s root or same-process frames. Cross-process frames require their own active target. Screenshot coordinate mapping is not yet part of this pair. The pair requires the CDP Accessibility domain; it reports an observation error when that domain is unavailable.