observe() is used to get a list of actions that can be taken on the current page. It’s useful for adding context to your planning step, or if you unsure of what page you’re on.

const observations = await page.observe();

observe() returns an array of objects, each with an XPath selector and short description.

If you are looking for a specific element, you can also pass in an instruction to observe:

const observations = await page.observe({
  instruction: "Find the buttons on this page",
});

Observe can also return a suggested action for the candidate element by setting the returnAction option to true. Here is a sample ObserveResult:

  {
    "description": "A brief description of the component",
    "method": 'click',
    "arguments": [],
    "selector": 'xpath=/html/body[1]/div[1]/main[1]/button[1]'
  }

In Python, the ObserveResult is wrapped in a Pydantic model. You can use model_dump() to get the dict equivalent.

​
Arguments: ObserveOptions

​
instruction
string

Provides instructions for the observation. Defaults to “Find actions that can be performed on this page.”

​
returnAction
boolean

Returns an observe result object that contains a suggested action for the candidate element. The suggestion includes method, and arguments (if any). Defaults to true.

​
iframes
boolean

Set iframes: true if content from iframes should be included in the observation.

​
modelName
AvailableModel

Specifies the model to use

​
modelClientOptions
object

Configuration options for the model client

​
domSettleTimeoutMs
number

Timeout in milliseconds for waiting for the DOM to settle

​
Returns: Promise<ObserveResult[]>

Each ObserveResult object contains a selector and description.

​
selector
string
required

A string representing the element selector

​
description
string
required

A string describing the possible action

​
method
string

The method to call on the element

​
arguments
object

The arguments to pass to the method