> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Act

> Ask Stagehand to perform one semantic browser action.

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.

```ts
const runtime = await bctrl.runtimes.create({
  name: "checkout-job",
});

const page = await bctrl.tools.call("browser.pages.open", {
  url: "https://example.com/checkout",
}, { runtimeId: runtime.id });

const result = await bctrl.tools.call("stagehand.act", {
  pageId: page.id,
  instruction: "Click the Continue button and wait for the next page to load.",
}, { runtimeId: runtime.id });

if (!result.success) {
  throw new Error(result.message);
}

console.log(result.actionDescription);
console.log(result.actions);

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](/sdk/tools/catalog) to
open, list, or activate pages before calling Stagehand.

## Request parameters

| Parameter     | Type      | Required | Description                                             |
| ------------- | --------- | -------- | ------------------------------------------------------- |
| `instruction` | `string`  | Yes      | Natural-language action, from 1 to 20,000 characters.   |
| `pageId`      | `PageId`  | No       | Page to target. Uses the active page when omitted.      |
| `timeoutMs`   | `integer` | No       | Maximum action time in milliseconds. Maximum: `120000`. |

## Response

| Field               | Type                | Always present | Description                                       |
| ------------------- | ------------------- | -------------- | ------------------------------------------------- |
| `success`           | `boolean`           | Yes            | Whether Stagehand completed the requested action. |
| `message`           | `string`            | Yes            | Human-readable result summary.                    |
| `actionDescription` | `string`            | Yes            | Description of the action Stagehand performed.    |
| `actions`           | `StagehandAction[]` | Yes            | Concrete browser actions selected by Stagehand.   |
| `cacheStatus`       | `"HIT" \| "MISS"`   | No             | Whether a cached result was used.                 |

Each `StagehandAction` contains:

| Field         | Type       | Always present | Description                               |
| ------------- | ---------- | -------------- | ----------------------------------------- |
| `selector`    | `string`   | Yes            | Element selector used by the action.      |
| `description` | `string`   | Yes            | Human-readable description of the action. |
| `method`      | `string`   | No             | Browser method used for the action.       |
| `arguments`   | `string[]` | No             | Arguments passed to the method.           |

## Run asynchronously

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

```ts
const call = await bctrl.tools.start("stagehand.act", {
  pageId: page.id,
  instruction: "Complete the shipping form using the saved customer details.",
  timeoutMs: 120000,
}, { runtimeId: runtime.id });

const result = await bctrl.toolCalls.result(call.id, {
  waitSeconds: 120,
});

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](/sdk/tools/stagehand/stagehand-observe) — find actionable elements first
* [Stagehand extract](/sdk/tools/stagehand/stagehand-extract) — read structured data from a page
* [Tools](/sdk/tools) — understand Tools, Toolsets, and ToolCalls
* [Runtimes](/sdk/runtimes) — configure the browser Runtime