​
Stagehand constructor

// Basic usage
// Defaults to Browserbase; if no API key is provided, it will default to LOCAL
// Default model is gpt-4o
const stagehand = new Stagehand();

// Custom configuration
const stagehand = new Stagehand({
	env: "LOCAL",
	verbose: 1,
	headless: true,
	enableCaching: true,
	logger: (logLine: LogLine) => {
		console.log(`[${logLine.category}] ${logLine.message}`);
	},
});

// Resume existing Browserbase session
const stagehand = new Stagehand({
	env: "BROWSERBASE",
	browserbaseResumeSessionID: "existing-session-id",
});

This constructor is used to create an instance of Stagehand.

​
Arguments: ConstructorParams

​
env
'LOCAL' | 'BROWSERBASE'

Defaults to 'BROWSERBASE'

​
apiKey
string

Your Browserbase API key. Defaults to BROWSERBASE_API_KEY environment variable

​
projectId
string

Your Browserbase project ID. Defaults to BROWSERBASE_PROJECT_ID environment variable

​
browserBaseSessionCreateParams
SessionCreateParams

Configuration options for creating new Browserbase sessions

​
browserbaseResumeSessionID
string

ID of an existing Browserbase session to resume

​
modelName
AvailableModel

Specifying the default language model to use

​
modelClientOptions
object

Configuration options for the language model client (i.e. apiKey)

​
enableCaching
boolean

Enables caching of LLM responses. When set to true, the LLM requests will be cached on disk and reused for identical requests. Defaults to false

​
headless
boolean

Determines if the browser runs in headless mode. Defaults to false. When the env is set to BROWSERBASE, this will be ignored

​
domSettleTimeoutMs
integer

Specifies the timeout in milliseconds for waiting for the DOM to settle. Defaults to 30_000 (30 seconds)

​
logger
(message: LogLine) => void

message is a LogLine object. Handles log messages. Useful for custom logging implementations. For more information, see the Logging page

​
verbose
integer

Enables several levels of logging during automation: 0: limited to no logging, 1: SDK-level logging, 2: LLM-client level logging (most granular)

​
debugDom
boolean

Draws bounding boxes around elements presented to the LLM during automation

​
llmClient
LLMClient

A custom LLM client implementation that conforms to the LLMClient abstract class

​
systemPrompt
string

A custom system prompt to use for the LLM in addition to the default system prompt for act, extract, and observe methods.

​
Returns: Stagehand object

The constructor returns an instance of the Stagehand class configured with the specified options. However, to use Stagehand, you must still initialize it either with init() or initFromPage().

​
stagehand.init()

await stagehand.init();

init() asynchronously initializes the Stagehand instance. It should be called before any other methods.

​
stagehand.close()

await stagehand.close();

close() is a cleanup method to remove the temporary files created by Stagehand. It’s recommended that you call this explicitly when you’re done with your automation.

Model SupportAct