Act

See how to use act() to perform browser actions

​
Method Signatures

// String instruction
await page.act(instruction: string): Promise<ActResult>

// With ActOptions
await page.act(options: ActOptions): Promise<ActResult>

// Execute observed action
await page.act(observeResult: ObserveResult): Promise<ActResult>
ActOptions Interface:
interface ActOptions {
  action: string;
  modelName?: AvailableModel;
  modelClientOptions?: ClientOptions;
  variables?: Record<string, string>;
  domSettleTimeoutMs?: number;
  timeoutMs?: number;
  iframes?: boolean;
}

​
Parameters

​
action
string
required
Natural language description of the action to perform.
​
variables
Record<string, string>
Key-value pairs for variable substitution using %variable% syntax. Prevents sensitive data from appearing in logs.
​
modelName
AvailableModel
Override the default LLM model for this action.
​
modelClientOptions
ClientOptions
Model-specific configuration options.Options: temperature, maxTokens, apiKey
​
domSettleTimeoutMs
number
Maximum time to wait for DOM to stabilize before attempting action.Default: 30000
​
timeoutMs
number
Maximum time to wait for the action to complete.
​
iframes
boolean
Set to true if target element is within an iframe.Default: false
​
observeResult
ObserveResult
Previously observed action to execute directly (enables self-healing).

​
Returns Promise<ActResult>

​
success
boolean
required
Whether the action was completed successfully.
​
message
string
required
Details about the action’s execution.
​
action
string
required
The action that was performed.
Response
{
  success: true,
  message: 'Action [scrollTo] performed successfully on selector: /html[1]',
  action: 'Scrollable area of the page where user can navigate to the pricing section or other parts of the page'
}

​
Error Types

  • TimeoutError - Action exceeded timeout limits
  • ElementNotFoundError - Target element could not be located
  • ActionFailedError - Action could not be completed
  • StagehandError - General Stagehand-specific errors