Stagehand block

Configure the Stagehand browser block to act in a web portal from a workflow: the instructions, settings and output it returns to the run.

The Stagehand block drives a hosted Chrome browser (on Browserbase) with plain-language instructions: open a page, click and type, read data off the screen, download a file. In a workflow definition it is a step with type: "action" and action set to stagehand.<action>. For the plain-language guide, see Work in a web portal.

When to use it

Download statements or invoices from a vendor or bank portal that has no API.
Read a value off a web page, such as a balance or an order status.
Fill in a form on a portal as part of a workflow.

If the system has an API, use its integration block or the API Request block instead. Browser steps are slower and depend on the page layout.

How a session works

All Stagehand steps in one run share one browser session, so a navigate step followed by act and download steps works on the same page. Start with navigate.

Actions

`action`	Editor label	What it does	Required
`stagehand.navigate`	Navigate	Opens a URL. Waits up to 60 seconds for the page.	`url`
`stagehand.act`	Act	Does one thing described in `instruction`, such as "Click Sign in".	`instruction`
`stagehand.extract`	Extract	Reads data described in `instruction` from the page.	`instruction`
`stagehand.observe`	Observe	Lists the actions the page offers that match `instruction`.	`instruction`
`stagehand.download`	Download	Does `instruction` to start a download and returns the file.	`instruction`
`stagehand.screenshot`	Screenshot	Captures the page.	None
`stagehand.agent`	Agent	Works through a multi-step task in `instruction` on its own.	`instruction`

Configuration

Field (`config` key)	Editor label	Type	Used by	Meaning
`url`	URL	string	`navigate`	The page to open.
`instruction`	Instruction	string	All except `navigate`	What to do or read, in plain words.
`contextId`	Browser Context ID	string	`navigate`	A saved browser context, so a login carries over between runs. The editor's placeholder `{{company.browserContextId}}` does not resolve at run time; paste the context id or reference a value from `input`.
`schema`	Not shown	object	`extract`	Optional JSON Schema for the data to return.
`retryAttempts`	Retry Attempts	number	`act`, `download`	Extra attempts after a retryable failure. 0 to 4, default 2.
`observeBeforeAct`	Observe Before Acting	boolean	`act`, `download`	Find exactly one matching element first, then act on it.
`downloadWaitMs`	Download Wait (ms)	number	`download`	How long to wait for the download to start. Default 3000.
`persistToFolder`	Persist To Folder	string	`download`	Save the file in Files under this folder and return its id instead of base64 content. Recommended for anything but small files.
`fileName`	Not shown	string	`download`	Name to use when the browser gives none.
`fullPage`	Full Page	boolean	`screenshot`	Capture the whole page, not only the visible part.
`maxSteps`	Max Steps	number	`agent`	Step limit for the agent. 1 to 50, default 10.
`systemPrompt`	System Prompt	string	`agent`	Instructions for the browser agent.

Put portal passwords in company secrets and reference them in the instruction, for example Type {{secrets.VENDOR_PORTAL_PASSWORD}} into the password field.

Output

Action	Fields
`navigate`	`currentUrl`, `title`, `sessionId`, `recordingUrl`, `liveViewUrl`
`act`	`success`, `description`, `result`, `sessionId`, `recordingUrl`, `usedFallback`
`extract`	`data` (the extracted values), `sessionId`, `recordingUrl`
`observe`	`observations`, `sessionId`, `recordingUrl`
`download`	`fileName`, `mimeType`, `sizeBytes`, `attempts`, `correlation`, `downloadGuid`, `suggestedFileName`, `sessionId`, `recordingUrl`; with `persistToFolder`, `fileId`, `filePath` and `persisted: true`; without it, `content` (base64)
`screenshot`	`screenshot` (base64 PNG), `sessionId`, `recordingUrl`
`agent`	`success`, `actions` (number taken), `result`, `sessionId`, `recordingUrl`

recordingUrl links to a replay of the browser session, which helps when a step fails.

Example

This workflow signs in to a vendor portal, downloads last month's statement into Files, and reads its text.

{
  "name": "Download vendor statement",
  "trigger": { "type": "schedule", "cron": "0 8 2 * *", "timezone": "America/Chicago" },
  "steps": [
    {
      "id": "open_portal",
      "type": "action",
      "name": "Open portal",
      "action": "stagehand.navigate",
      "config": { "url": "https://portal.example-vendor.com/login" }
    },
    {
      "id": "sign_in",
      "type": "action",
      "name": "Sign in",
      "action": "stagehand.act",
      "config": {
        "instruction": "Sign in with username ap@example.com and password {{secrets.VENDOR_PORTAL_PASSWORD}}"
      }
    },
    {
      "id": "get_statement",
      "type": "action",
      "name": "Download last month's statement",
      "action": "stagehand.download",
      "config": {
        "instruction": "Open Statements and click Download PDF for last month",
        "persistToFolder": "Vendor statements",
        "retryAttempts": 2
      }
    },
    {
      "id": "read_statement",
      "type": "action",
      "name": "Read statement",
      "action": "pdf.readText",
      "config": { "fileId": "{{steps.get_statement.fileId}}" }
    }
  ]
}

Errors and limits

A missing url or instruction fails the step.
act and download retry the failures they can recover from, such as a model answer that did not match or a download that could not be matched to the click. Other failures fail the step.
Results depend on the page. A portal redesign can break an instruction; check the session recording and update the wording.
A download without persistToFolder is carried in the run as base64, which counts toward the run's memory and output size.