---
title: Stagehand
description: Web automation and data extraction
---

import { BlockInfoCard } from "@/components/ui/block-info-card"

<BlockInfoCard 
  type="stagehand"
  color="#FFC83C"
/>

{/* MANUAL-CONTENT-START:intro */}
[Stagehand](https://stagehand.com) is a tool that enables both extraction of structured data from webpages and autonomous web automation using Browserbase and modern LLMs (OpenAI or Anthropic).

Stagehand offers two main capabilities in Sim:

- **stagehand_extract**: Extract structured data from a single webpage. You specify what you want (a schema), and the AI retrieves and parses the data in that shape from the page. This is best for extracting lists, fields, or objects when you know exactly what information you need and where to get it.

- **stagehand_agent**: Run an autonomous web agent capable of completing multi-step tasks, interacting with elements, navigating between pages, and returning structured results. This is much more flexible: the agent can do things like log in, search, fill forms, gather data from multiple places, and output a final result according to a requested schema.

**Key Differences:**

- *stagehand_extract* is a rapid “extract this data from this page” operation. It works best for direct, one-step extraction tasks.
- *stagehand_agent* performs complex, multi-step autonomous tasks on the web — such as navigation, searching, or even transactions — and can dynamically extract data according to your instructions and an optional schema.

In practice, use **stagehand_extract** when you know what you want and where, and use **stagehand_agent** when you need a bot to think through and execute interactive workflows.

By integrating Stagehand, Sim agents can automate data gathering, analysis, and workflow execution on the web: updating databases, organizing information, and generating custom reports—seamlessly and autonomously.
{/* MANUAL-CONTENT-END */}


## Usage Instructions

Integrate Stagehand into the workflow. Can extract structured data from webpages or run an autonomous agent to perform tasks.



## Actions

### `stagehand_extract`

Extract structured data from a webpage using Stagehand

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `url` | string | Yes | URL of the webpage to extract data from |
| `instruction` | string | Yes | Instructions for extraction |
| `provider` | string | No | AI provider to use: openai or anthropic |
| `apiKey` | string | Yes | API key for the selected provider |
| `schema` | json | Yes | JSON schema defining the structure of the data to extract |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `data` | object | Extracted structured data matching the provided schema |

### `stagehand_agent`

Run an autonomous web agent to complete tasks and extract structured data

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `startUrl` | string | Yes | URL of the webpage to start the agent on |
| `task` | string | Yes | The task to complete or goal to achieve on the website |
| `variables` | json | No | Optional variables to substitute in the task \(format: \{key: value\}\). Reference in task using %key% |
| `provider` | string | No | AI provider to use: openai or anthropic |
| `apiKey` | string | Yes | API key for the selected provider |
| `outputSchema` | json | No | Optional JSON schema defining the structure of data the agent should return |
| `mode` | string | No | Agent tool mode: dom \(default\), hybrid, or cua |
| `maxSteps` | number | No | Maximum agent steps \(default 20, max 200\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `agentResult` | object | Result from the Stagehand agent execution |
|   ↳ `success` | boolean | Whether the agent task completed successfully without errors |
|   ↳ `completed` | boolean | Whether the agent finished executing \(may be false if max steps reached\) |
|   ↳ `message` | string | Final status message or result summary from the agent |
|   ↳ `actions` | array | List of all actions performed by the agent during task execution |
|     ↳ `type` | string | Type of action performed \(e.g., "act", "observe", "ariaTree", "close", "wait", "navigate"\) |
|     ↳ `reasoning` | string | AI reasoning for why this action was taken |
|     ↳ `taskCompleted` | boolean | Whether the task was completed after this action |
|     ↳ `action` | string | Description of the action taken \(e.g., "click the submit button"\) |
|     ↳ `instruction` | string | Instruction that triggered this action |
|     ↳ `pageUrl` | string | URL of the page when this action was performed |
|     ↳ `pageText` | string | Page text content \(for ariaTree actions\) |
|     ↳ `timestamp` | number | Unix timestamp when the action was performed |
|     ↳ `timeMs` | number | Time in milliseconds \(for wait actions\) |
| `structuredOutput` | object | Extracted data matching the provided output schema |
| `liveViewUrl` | string | Embeddable Browserbase live view URL \(active only while the session is running\) |
| `sessionId` | string | Browserbase session identifier |


