Stagehand

Executes browser actions from natural language commands by fusing vision-based element detection with DOM parsing. The act() primitive accepts plain English instructions like 'click the login button' and internally routes through a hybrid handler architecture that combines screenshot analysis with DOM traversal, enabling the LLM to ground language in both visual and structural context. Uses a handler-based dispatch system that abstracts away selector brittleness by reasoning about element semantics rather than CSS paths.

Extracts typed data from web pages by combining screenshot capture with DOM analysis, then passing both to an LLM with a schema constraint. The extract() primitive accepts a TypeScript type or JSON schema and returns validated structured data matching that schema. Internally, it builds a context window containing the visual page state and DOM tree, instructs the LLM to locate and parse the requested data, and validates output against the schema before returning.

Provides a built-in evaluation framework for measuring automation success rates, latency, and cost across different models and configurations. The evaluation system defines test categories (e.g., e-commerce, form filling, data extraction) and runs automation workflows against benchmark sites, collecting metrics on success rate, steps taken, LLM calls, and execution time. Results are aggregated and compared across model/configuration combinations to guide optimization.

Provides a command-line interface (browse CLI) for interactive browser automation and debugging. The CLI launches a browser session, accepts natural language commands, and executes them via Stagehand's core primitives. It includes a daemon architecture for session persistence, network capture for debugging, and real-time feedback on action execution. Developers can use the CLI to explore pages, test automation logic, and debug failures interactively.

Exposes Stagehand capabilities via HTTP API, enabling remote automation execution from any HTTP client. The server implements REST endpoints for act(), extract(), observe(), and agent operations, with OpenAPI specification for SDK generation. Multi-region routing supports load balancing across Browserbase instances. Developers can deploy the server and call it from any language/framework, decoupling automation logic from client code.

Implements a structured error handling system that classifies automation failures into semantic categories (e.g., element not found, navigation timeout, LLM error) with detailed error messages and recovery suggestions. SDK errors are typed and include context (page state, action attempted, LLM response) to aid debugging. The error system integrates with logging and observability to track failure patterns.

Integrates structured logging and metrics collection throughout Stagehand's execution, tracking action execution, LLM calls, cache hits/misses, and performance metrics. Logs are emitted at configurable levels (debug, info, warn, error) and can be routed to external observability systems (DataDog, New Relic, etc.). Metrics include latency per operation, token usage, cost, and success rates, enabling performance monitoring and cost optimization.

Discovers and describes interactive elements on a page by synthesizing DOM structure with visual analysis. The observe() primitive returns a list of observable elements with their semantic properties (role, label, visibility, interactivity) by parsing the DOM tree and cross-referencing with screenshot analysis. This enables developers to query 'what buttons are visible?' or 'find all input fields' without writing selectors, using the LLM to understand element semantics.

Orchestrates multi-step browser automation workflows by decomposing high-level goals into sequences of act/extract/observe calls. The agent() system uses an LLM with access to a tool registry (DOM tools, Hybrid tools, or Computer Use Agent tools) to reason about task decomposition, decide which tool to call next, and track progress toward the goal. Internally, it maintains agent context (variables, execution history, page state), handles tool invocation via a handler dispatch system, and implements self-healing through caching and cache invalidation when page state changes.

Caches the results of act() and extract() calls with deterministic replay and self-healing capabilities. The ActCache system stores action outcomes (e.g., 'clicking button X navigated to page Y') and replays them on subsequent runs if the preconditions (page state, element presence) are met. If preconditions change, the cache is invalidated and the action is re-executed. This enables workflows to skip expensive LLM calls for repeated actions while automatically adapting to page changes.

Abstracts LLM provider differences (OpenAI, Anthropic, Ollama, custom) behind a unified client interface, enabling model selection, provider fallback, and cost optimization. The LLM Client Architecture supports configuring primary and fallback models, routing requests based on capability requirements (vision, function calling), and handling provider-specific response formats. Developers specify model preferences via configuration, and Stagehand automatically selects the appropriate provider and handles API differences.

Allows developers to choose between three tool execution modes for agent actions: DOM-only (fast, selector-based), Hybrid (balanced, vision + DOM), or Computer Use Agent (slow, pure vision). The agent system routes tool calls through the selected mode, trading off speed vs robustness. DOM mode uses Playwright locators directly; Hybrid mode uses vision + DOM fusion; CUA mode delegates to a vision-based agent provider (Anthropic Computer Use, etc.). Developers configure mode per agent or per action.

Enables developers to extend agent capabilities with custom tools via the Model Context Protocol (MCP). Custom tools are registered in the agent's tool registry and invoked by the LLM during reasoning. MCP provides a standardized interface for tool definition (schema, parameters, execution logic) and allows tools to be implemented in any language and run in separate processes. Stagehand's agent system handles tool invocation, parameter validation, and result marshaling.

Manages browser sessions with support for both local execution (via Playwright) and cloud execution (via Browserbase). The V3 class initializes a browser connection through a CDP (Chrome DevTools Protocol) abstraction layer that works with local browsers or Browserbase cloud instances. Developers specify execution environment via configuration, and Stagehand handles connection setup, session lifecycle, and cleanup. Cloud execution enables headless automation without local browser installation.

Manages page and frame context through the V3Context abstraction, which tracks the current page, active frame, and navigation state. The context system enables multi-frame automation (iframes, shadow DOM) by maintaining a frame stack and routing actions to the correct frame. V3Context also tracks page state changes (navigation, DOM mutations) and invalidates caches when state changes, enabling self-healing automation.