Skip to main content

Act

See how to use act() to perform browser actions

​
Method Signatures

  • TypeScript
// String instruction only
await stagehand.act(instruction: string): Promise<ActResult>

// Action only - Deterministic (no LLM)
await stagehand.act(action: Action): Promise<ActResult>

// String instruction with options
await stagehand.act(instruction: string, options: ActOptions): Promise<ActResult>
Action Interface:
interface Action {
  selector: string;
  description: string;
  method: string;
  arguments: string[];
}
ActOptions Interface:
interface ActOptions {
  model?: ModelConfiguration;
  variables?: Record<string, string>;
  timeout?: number;
  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
}

// ModelConfiguration can be either a string or an object
type ModelConfiguration =
  | string  // Format: "provider/model" (e.g., "openai/gpt-4o", "anthropic/claude-3-5-sonnet-20241022")
  | {
      modelName: string;  // The model name
      apiKey?: string;    // Optional: API key override
      baseURL?: string;   // Optional: Base URL override
      // Additional provider-specific options
    }

​
Parameters

​
instruction | action
string | Action
required
  • Instruction: Natural language description of the action to perform. Use %variableName% syntax to reference variables.
  • Action: A deterministic action to perform:
​
model
ModelConfiguration
Configure the AI model to use for this action. Can be either:
  • A string in the format "provider/model" (e.g., openai/gpt-5, google/gemini-2.5-flash)
  • An object with detailed configuration
​
variables
Record<string, string>
Key-value pairs for variable substitution using %variableName% syntax in your instruction. Variables are not shared with LLM providers, making them ideal for sensitive data like passwords and API keys.Example:
await stagehand.act("type %password% into the password field", {
  variables: { password: process.env.USER_PASSWORD }
});
​
timeout
number
Maximum time in milliseconds to wait for the action to complete. Default varies by configuration.
​
page
PlaywrightPage | PuppeteerPage | PatchrightPage | Page
Optional: Specify which page to perform the action on. Supports multiple browser automation libraries:
  • Playwright: Native Playwright Page objects
  • Puppeteer: Puppeteer Page objects
  • Patchright: Patchright Page objects
  • Stagehand Page: Stagehand’s wrapped Page object
If not specified, defaults to the current “active” page in your Stagehand instance.

​
Returns Promise<ActResult>

​
success
boolean
required
Whether the action completed successfully
​
message
string
required
Human-readable message describing the result
​
actionDescription
string
required
Instruction that was used to perform the action
​
actions
Action[]
Array of actions that were executed
Example Response: 
{
  "success": true,
  "message": "Action completed successfully",
  "actionDescription": "Clicked the submit button",
  "actions": [
    {
      "selector": "/html/body/form/button[1]",
      "description": "Submit button at bottom of form",
      "method": "click",
      "arguments": []
    }
  ]
}

​
Built-in Support

Iframe and Shadow DOM interactions are supported out of the box. Stagehand automatically handles iframe traversal and shadow DOM elements without requiring additional configuration or flags.

​
Code Examples

  • Basic Usage
  • Variables
  • Custom Model
  • Multi-Page
  • Caching
import { Stagehand } from "@browserbasehq/stagehand";

// Initialize with Browserbase (API key and project ID from environment variables)
// Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID in your environment
const stagehand = new Stagehand({ env: "BROWSERBASE" });
await stagehand.init();
const page = stagehand.context.pages()[0];

await page.goto("https://example.com");

// Simple action
await stagehand.act("click the login button");

​
Error Types

The following errors may be thrown by the act() method:
  • StagehandError - Base class for all Stagehand-specific errors
  • StagehandElementNotFoundError - Target element could not be located using the provided selector(s)
  • StagehandClickError - Failed to click on the target element
  • StagehandEvalError - Error occurred while evaluating JavaScript in the page context
  • StagehandDomProcessError - Error occurred while processing the DOM
  • StagehandIframeError - Unable to resolve iframe for the target element
  • ContentFrameNotFoundError - Unable to obtain content frame for the selector
  • XPathResolutionError - XPath does not resolve in the current page or frames
  • StagehandShadowRootMissingError - No shadow root present on the resolved host element
  • LLMResponseError - Error in LLM response processing
  • MissingLLMConfigurationError - No LLM API key or client configured
  • UnsupportedModelError - The specified model is not supported for this operation
  • InvalidAISDKModelFormatError - Model string does not follow the required provider/model format