Act

Ask Stagehand to perform one browser action in an active browser Runtime. Give it a natural-language instruction such as clicking a button, filling a form, or selecting an option. Stagehand chooses the concrete browser actions needed to complete the instruction.

Run an action

The Runtime must be active. If you do not pass pageId, Stagehand uses the Runtime’s active page. Pass pageId when the Runtime has more than one page or when the action must target a specific page.

1
const runtime = await bctrl.runtimes.create({
2
  name: "checkout-job",
3
});
4
5
const page = await bctrl.tools.call("browser.pages.open", {
6
  url: "https://example.com/checkout",
7
}, { runtimeId: runtime.id });
8
9
const result = await bctrl.tools.call("stagehand.act", {
10
  pageId: page.id,
11
  instruction: "Click the Continue button and wait for the next page to load.",
12
}, { runtimeId: runtime.id });
13
14
if (!result.success) {
15
  throw new Error(result.message);
16
}
17
18
console.log(result.actionDescription);
19
console.log(result.actions);
20
21
await bctrl.runtimes.stop(runtime.id);

instruction must be between 1 and 20,000 characters. timeoutMs can be up to 120000 milliseconds. Use the browser page Tools to open, list, or activate pages before calling Stagehand.

Request parameters

Response

Each StagehandAction contains:

Run asynchronously

Use an asynchronous ToolCall when the action may take time or should be tracked independently:

1
const call = await bctrl.tools.start("stagehand.act", {
2
  pageId: page.id,
3
  instruction: "Complete the shipping form using the saved customer details.",
4
  timeoutMs: 120000,
5
}, { runtimeId: runtime.id });
6
7
const result = await bctrl.toolCalls.result(call.id, {
8
  waitSeconds: 120,
9
});
10
11
console.log(result.success, result.message);

Use bctrl.toolCalls.get(call.id) to inspect progress or bctrl.toolCalls.cancel(call.id) to cancel an active call.

Next

• Stagehand observe — find actionable elements first
• Stagehand extract — read structured data from a page
• Tools — understand Tools, Toolsets, and ToolCalls
• Runtimes — configure the browser Runtime