Skip to main content

​
Overview

Stagehand is an AI-powered browser automation framework with methods like observe(), extract(), and act(). This guide walks you through deploying and running a Stagehand project on Intuned. You’ll build a sample scraper that extracts book data—without writing Playwright selectors or custom parsing logic. The same patterns apply to any automation you build with the framework.
This guide assumes you have a basic understanding of Intuned projects. If you’re new to Intuned, start with the getting started guide.

​
When to use AI automation

Intuned supports AI-powered browser automation frameworks like Stagehand, Browser Use, and others. Use AI automation when:
  • Pages are dynamic — Elements change position, structure, or content unpredictably
  • You don’t know the exact page structure — Scraping sites you haven’t mapped in detail
  • You want natural language control — Describe what to do instead of writing precise selectors
  • Traditional Playwright code is too brittle for your case — AI agents adapt to minor UI changes automatically
Stagehand is one option for AI automation on Intuned. The setup patterns in this guide apply to other AI frameworks as well. For a deeper dive into choosing between deterministic, AI-driven, and hybrid approaches, check out Flexible Automations.

​
Guide

Let’s build a getBooks API with AI. The template handles all the Stagehand setup for you. You can develop with Stagehand in two ways:
  • Online IDE — Zero setup. Write, test, and deploy directly from your browser.
  • CLI — Use your favorite IDE with full version control.
1

Create a project

  1. Go to Intuned dashboard
  2. Select + New Project > Templates > Stagehand
  3. Select your language (Python or TypeScript)
  4. Name it and select Create Project
Create Stagehand project from template
2

Explore the project

The template includes a book scraper API that combines Playwright with AI agents.Project structure:
my-stagehand-project/
├── api/
│   └── getBooks.ts              # Main automation API
├── hooks/
│   └── setupContext.ts          # Stagehand initialization
├── package.json                 # Dependencies
└── intuned.json                 # Project configuration
The automation code:
Python
from typing import TypedDict, cast
from intuned_runtime import attempt_store
from pydantic import BaseModel
from stagehand import Stagehand, StagehandPage
import os

class Params(TypedDict):
    category: str | None

async def automation(page: StagehandPage, params: Params, *args, **kwargs):
    # Stagehand in python uses Stagehand V2. It extends Playwright page as a StagehandPage object.
    category = params.get("category")
    stagehand = cast(Stagehand, attempt_store.get("stagehand"))
    await page.set_viewport_size({"width": 1280, "height": 800})

    await page.goto("https://books.toscrape.com")
    
    # Computer Use Agent uses X,Y coordinates to control the page
    agent = stagehand.agent(
        provider="google",
        model="gemini-2.5-computer-use-preview-10-2025",
        instructions="""You are a helpful assistant that can use a web browser.
Do not ask follow up questions, the user will trust your judgement.""",
    )
    
    if category:
        await agent.execute(
            instruction=f'Navigate to the "{category}" category by clicking on it',
            max_steps=30,
            auto_screenshot=True
        )

    class BookDetails(BaseModel):
        title: str
        price: str
        rating: str | None = None
        availability: str | None = None

    class BooksResponse(BaseModel):
        books: list[BookDetails]

    return await page.extract(
        "Extract all books visible on the page with complete details",
        schema=BooksResponse,
    )
What this does: Navigates to https://books.toscrape.com, optionally uses an AI agent to navigate to a specific category, then extracts all book details with type-safe schemas (Pydantic for Python, Zod for TypeScript).
3

Run your automation

Run the book scraper to test your setup.
  1. In the Online IDE, select the API from the dropdown
  2. Select Select Parameter and enter {"category": "Travel"}
  3. Select Start Run
Running Stagehand automation in IDE
4

Deploy and test

Deploy your automation to Intuned’s infrastructure.
  1. In the Online IDE, select Deploy in the top-right corner
  2. After deployment completes, go to the project’s Runs page
  3. Select Start Run, then choose your API
  4. Enter parameters: {"category": "Travel"} and select Start Run
Running Stagehand automation in Dashboard
  1. After the run completes, view the extracted results
View Stagehand run results
Learn more about Runs and how to trigger them programmatically.

​
How it works

  • Stagehand connects to Intuned’s managed browser using CDP via the setupContext hook.
Check out our setup hook recipe.
  • The Stagehand instance is stored in attemptStore for your API to access
  • Your API accepts parameters (like category) that can vary for each run
  • The automation combines Playwright with Stagehand’s AI-based methods

Stagehand Documentation

Official Stagehand documentation and API reference

Stagehand GitHub

View the source code and contribute to Stagehand

Intuned Cookbook

Browse examples and recipes for Intuned projects

attemptStore Reference

Learn more about sharing data between hooks and APIs