act()

Complete API reference for the act() method

Act

See how to use act() to perform browser actions

Method Signatures

TypeScript

// 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;
}

Python

# String instruction
await page.act(instruction: str) -> ActResult

# With parameters
await page.act(
    instruction: str,
    variables: Dict[str, str] = None,
    dom_settle_timeout_ms: int = None,
    timeout_ms: int = None,
    model_name: AvailableModel = None,
    model_client_options: Dict = None,
    iframes: bool = None,
) -> ActResult

# Execute observed action
await page.act(observe_result: ObserveResult) -> ActResult

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