Skip to main content

Act

See how to use act() to perform browser actions

​
Method Signatures

// 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, VariableValue>;
  timeout?: number;
  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
  serverCache?: boolean;
}

// VariableValue can be a simple primitive or a rich object:
type VariableValue =
  | string
  | number
  | boolean
  | { value: string | number | boolean; description?: string };

// ModelConfiguration can be either a string or an object
type ModelConfiguration =
  | string  // Format: "provider/model" (e.g., "openai/gpt-4o", "anthropic/claude-sonnet-4-6")
  | {
      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, VariableValue>
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.Values can be simple primitives (string, number, boolean) or rich objects with an optional description ({ value, description? }).Example:
// Simple values
await stagehand.act("type %password% into the password field", {
  variables: { password: process.env.USER_PASSWORD }
});

// Rich values with descriptions
await stagehand.act("type %password% into the password field", {
  variables: {
    password: {
      value: process.env.USER_PASSWORD,
      description: "The user's login 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.
​
serverCache
boolean
Override the instance-level serverCache setting for this request. When true, enables server-side caching. When false, disables it.
Only applies when env is "BROWSERBASE". Has no effect in local environments.
Defaults to the value set on the Stagehand constructor (which itself defaults to true).

​
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
​
cacheStatus
"HIT" | "MISS"
Indicates whether the result was served from the server-side cache. Only present when running with env: "BROWSERBASE" and server-side caching is enabled.
  • "HIT" - Result was served from cache; no LLM tokens were consumed
  • "MISS" - Result was computed fresh and cached for future calls
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

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