stagehand

Files (1)

• SKILL.md

SKILL.md (first lines)

# Stagehand

Browser automation through the **Browserbase Stagehand** MCP server. Provides
four core primitives — `act`, `observe`, `extract`, and `agent` — for
declarative, AI-powered web interaction.

## Installation

### Prerequisites

- Node.js >= 18
- A Browserbase API key ([sign up](https://browserbase.com))
- An ox/Kilo agent with MCP support

### Step 1 — Install the Stagehand MCP server

```bash
npm install -g @browserbase/stagehand-mcp
```

### Step 2 — Configure with ox

Add to `~/.config/ox/mcp.json`:

```json
{
  "mcpServers": {
    "stagehand": {
      "command": "npx",
      "args": ["@browserbase/stagehand-mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "your-api-key-here",
        "BROWSERBASE_PROJECT_ID": "your-project-id"
      }
    }
  }
}
```

Or set env vars in your shell profile:

```bash
export BROWSERBASE_API_KEY="bs_..."
export BROWSERBASE_PROJECT_ID="c1e..."
```

### Step 3 — Verify

```bash
ox mcp list
# stagehand — registered, ready
```

## The Four Primitives

### act — Perform an action

Execute a user-described action using AI. Stagehand figures out the best way.

```js
await tools.stagehand_act({
  action: "Click the 'Sign In' button"
});

await tools.stagehand_act({
  action: "Fill in the email field with user@example.com"
});
```

### observe — Inspect the page

Get structured information about the current page state.

```js
const observation = await tools.stagehand_observe({
  query: "What is the current page title and URL?"
});
console.log(observation.result);
```

### extract — Pull structured data

Extract specific information following a schema.

```js
const data = await tools.stagehand_extract({
  prompt: "Extract all product names and prices from this page",
  schema: {
    products: [{ name: "string", price: "string" }]
  }
});
```

### agent — Autonomous browsing session

Run a full AI agent loop to achieve a goal.

```js
const result = await tools.stagehand_agent({
  task: "Search for red sneakers on Amazon and add the first result to cart"
});
```

## Usage Examples

### Web Scraping with Extract

```js
// 1. Navigate to page
await tools.stagehand_act({
  action: "Go to https://news.ycombinator.com"
});

// 2. Extract structured data
const posts = await tools.stagehand_extract({
  prompt: "Extract all story titles, URLs, and point counts",
  schema: {
    stories: [{
      title: "string",

From SAI141003/ox, MIT.

More from SAI141003/ox