Stagehand 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) |
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) |
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
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."