LoopfourStagehand Block
AI-driven browser automation for portal navigation, downloads, and form filling
The Stagehand block provides AI-driven browser automation powered by Stagehand and Browserbase. Use it to navigate web portals, download reports, fill forms, and extract data from websites that do not have APIs.
Stagehand uses computer vision and AI to understand web pages, making it resilient to UI changes. Actions are described in natural language rather than brittle CSS selectors.
Available Actions
Navigate
Open a URL in the browser session.
| Option | Type | Description |
|---|---|---|
url | string | URL to navigate to |
contextId | string | Browserbase context ID for auth persistence (optional) |
Act
Execute a browser action described in natural language.
| Option | Type | Description |
|---|---|---|
instruction | string | What to do (e.g., "Click the login button") |
timeoutMs | number | Action timeout in milliseconds (default: 30000) |
agentFallback | boolean | Fall back to agent mode if act fails (default: false) |
observeBeforeAct | boolean | Require exactly one observed action, then execute it without another model call |
retryAttempts | number | Additional retries for invalid AI structured output (default: 2, maximum: 4) |
Extract
Extract structured data from the current page.
| Option | Type | Description |
|---|---|---|
instruction | string | What to extract (e.g., "Get the invoice total and due date") |
Download
Download a file triggered by a browser action.
| Option | Type | Description |
|---|---|---|
instruction | string | Action that triggers the download (e.g., "Click the PDF download link") |
downloadWaitMs | number | Wait time before polling for the file (default: 3000) |
observeBeforeAct | boolean | Require exactly one observed click action before triggering the download |
retryAttempts | number | Additional retries for invalid AI output, missing downloads, canceled downloads, or MIME mismatches (default: 2, maximum: 4) |
persistToFolder | string | Write the file straight to this workspace folder and return { fileId, filePath } instead of inline content. Keeps large downloads out of the step result. |
expectedMimeType | string | Optional. Leave empty to accept any content type — the stored MIME is then derived from the file's bytes. |
Set expectedMimeType only when the site always serves the same type. For a
sniffable type (application/pdf, image/png, image/jpeg,
application/zip) it is a hard assertion against the downloaded bytes: if they
disagree the step fails even though the file downloaded correctly, and a site
that sometimes serves a .zip instead of a PDF will fail every time. Prefer
leaving it unset and validating the artifact in a later step with the
workspace_files extract archive operation.
Screenshot
Capture the current page state.
| Option | Type | Description |
|---|---|---|
fullPage | boolean | Capture entire page vs viewport only (default: false) |
Agent
Run an autonomous multi-step browser task.
| Option | Type | Description |
|---|---|---|
instruction | string | High-level goal (e.g., "Log in and download the monthly report") |
maxSteps | number | Maximum actions the agent can take (default: 10) |
Example Patterns
Download Accounting Reports
Schedule (monthly) -> Stagehand (navigate to portal)
-> Stagehand (act: log in) -> Stagehand (act: navigate to reports)
-> Stagehand (download: click PDF download)
-> Agent (extract data from PDF) -> QuickBooks (record entries)Fill Tax Forms
Trigger -> Stagehand (navigate to tax portal)
-> Stagehand (act: fill in company name) -> Stagehand (act: fill in EIN)
-> Stagehand (act: submit form) -> Stagehand (screenshot: confirmation)
-> Slack (share confirmation)Session Management
Browser sessions are cached per workflow run. One Browserbase session is shared across all Stagehand steps in a single execution, with a 15-minute TTL.
Auth persistence: Use Browserbase Contexts to persist cookies and login state across workflow runs. Create a context once, log in, and reuse the contextId in subsequent runs to skip login steps.
Best Practices
- Use
contextIdfor authenticated portals. This avoids re-authenticating on every run. - Set
agentFallback: truefor unreliable UI elements. If anactinstruction fails (e.g., button not found), the agent mode can recover by exploring the page. - Use
observeBeforeActfor high-value controls. The runtime requires exactly one selector-backed action and fails without clicking when the result is missing or ambiguous. - Keep download retries bounded. Each retry takes a fresh Browserbase download baseline, so a bad first file cannot be returned as the next attempt's result.
- Use
screenshotfor debugging. Take screenshots before and after critical actions to verify the browser state. - Keep instructions specific. "Click the blue Download PDF button in the Reports section" is better than "download the report."