Stagehand icon

Stagehand

Control browser using Stagehand with CDP URL

Actions3

Observe

AI-generated

Overview

This node, named "Stagehand," enables controlling a browser session via the Chrome DevTools Protocol (CDP) using natural language instructions. It connects to a browser instance through a CDP WebSocket URL and leverages an AI language model to perform three main operations on the page:

  • Act: Execute an action on the page described by a natural language instruction.
  • Extract: Extract structured data from the page based on a provided instruction and schema.
  • Observe: Observe the page and plan an action based on an instruction.

Typical use cases include automating browser interactions without writing code, scraping structured data from web pages, or monitoring page state to decide next steps. For example, you could instruct the node to "click the login button," extract product details into a structured format, or observe changes on a page to trigger further automation.

Properties

Name Meaning
CDP URL The WebSocket URL for connecting to the browser's Chrome DevTools Protocol endpoint.
Instruction A natural language instruction describing what Stagehand should do on the page.
Advanced Options Collection of optional settings:
- Enable Caching: Whether to cache Stagehand operations (true/false).
- Log Messages: Include internal Stagehand log messages in output (true/false).
- Verbose Level: Logging verbosity level with options: No Logs, Only Errors, All Logs.

Note: The node supports other properties related to the "Extract" operation (like schema source and field definitions), but since only the "Observe" operation is requested here, those are not relevant.

Output

The node outputs an array of items, each containing a json object with the following structure:

  • operation: The operation performed, here always "observe".
  • result: The result returned by Stagehand's observe method, typically an object representing the observation or planned action derived from the page.
  • messages (optional): If logging is enabled, an array of internal Stagehand log messages captured during execution.

No binary data output is produced by this node.

Dependencies

  • Requires a running browser instance accessible via a Chrome DevTools Protocol WebSocket URL.
  • Needs an AI language model input connected to the node, providing:
    • A model identifier string.
    • An API key credential for authentication.
  • Uses the external @browserbasehq/stagehand library to interface with the browser and perform operations.
  • Requires n8n environment configured to supply the AI model connection and credentials.

Troubleshooting

  • Missing or invalid AI model input: The node asserts that the AI model input exists and contains both a model name and API key as strings. Ensure the AI language model node is properly connected and configured.
  • Invalid or unreachable CDP URL: The node requires a valid WebSocket URL to connect to the browser. Verify the browser is running with remote debugging enabled and the URL is correct.
  • Unsupported operation error: If an unsupported operation is specified, the node throws an error. Confirm the operation parameter is set to "observe" for this context.
  • Stagehand initialization failures: Network issues or invalid credentials can cause initialization errors. Check connectivity and API key validity.
  • Verbose logging: Enabling verbose logs or message logging can help diagnose issues by providing internal Stagehand messages in the output.

Links and References

Discussion