Skip to main content
Version: Next

externalStagehand

V3

Purpose: A high-level orchestrator for Stagehand V3. Abstracts away whether the browser runs locally via Chrome or remotely on Browserbase, and exposes simple entrypoints (act, extract, observe) that delegate to the corresponding handler classes.

Responsibilities:

  • Bootstraps Chrome or Browserbase, ensures a working CDP WebSocket, and builds a V3Context.
  • Manages lifecycle: init, context access, cleanup.
  • Bridges external page objects (Playwright/Puppeteer) into internal frameIds for handlers.
  • Provides a stable API surface for downstream code regardless of runtime environment.

Index

Constructors

Properties

Accessors

Methods

Constructors

externalconstructor

  • new Stagehand(opts): V3

  • Parameters

    • externalopts: V3Options

    Returns V3

Properties

externaloptionalbrowserbaseSessionId

browserbaseSessionId?: string

externalreadonlybus

bus: EventEmitter<DefaultEventMap>

Event bus for internal communication. Emits events like 'screenshot' when screenshots are captured during agent execution.

externalreadonlydisableAPI

disableAPI: boolean

externalreadonlyexperimental

experimental: boolean

externalllmClient

llmClient: LLMClient

externalreadonlylogInferenceToFile

logInferenceToFile: boolean

externalstagehandMetrics

stagehandMetrics: StagehandMetrics

externalverbose

verbose: 0 | 1 | 2

Accessors

externalbrowserbaseDebugURL

  • get browserbaseDebugURL(): undefined | string

  • Returns undefined | string

externalbrowserbaseSessionID

  • get browserbaseSessionID(): undefined | string

  • Returns undefined | string

externalbrowserbaseSessionURL

  • get browserbaseSessionURL(): undefined | string

  • Returns undefined | string

externalcontext

  • get context(): V3Context

  • Expose the current CDP-backed context.

    Returns V3Context

externalhistory

  • get history(): Promise<readonly HistoryEntry[]>

  • Async property for history so callers can await v3.history. Returns a frozen copy to avoid external mutation.

    Returns Promise<readonly HistoryEntry[]>

externalisBrowserbase

  • get isBrowserbase(): boolean

  • Returns true if the browser is running on Browserbase.

    Returns boolean

externallogger

  • get logger(): (logLine) => void

  • Returns (logLine) => void

      • (logLine): void

      • Parameters

        • externallogLine: LogLine

        Returns void

externalmetrics

  • get metrics(): Promise<StagehandMetrics>

  • Async property for metrics so callers can await v3.metrics. When using API mode, fetches metrics from the API. Otherwise returns local metrics.

    Returns Promise<StagehandMetrics>

Methods

externalact

  • Run an "act" instruction through the ActHandler.

    New API:

    • act(instruction: string, options?: ActOptions)
    • act(action: Action, options?: ActOptions)

    Parameters

    • externalinstruction: string
    • externaloptionaloptions: ActOptions

    Returns Promise<ActResult>

externaladdToHistory

  • addToHistory(method, parameters, result): void

  • Parameters

    • externalmethod: agent | act | extract | observe | navigate
    • externalparameters: unknown
    • externaloptionalresult: unknown

    Returns void

externalagent

  • agent(options): { execute: (instructionOrOptions) => Promise<AgentStreamResult> }
  • agent(options): { execute: (instructionOrOptions) => Promise<AgentResult> }

  • Create a v3 agent instance (AISDK tool-based) with execute(). Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).

    When stream: true, returns a streaming agent where execute() returns AgentStreamResult When stream is false/undefined, returns a non-streaming agent where execute() returns AgentResult

    Parameters

    Returns { execute: (instructionOrOptions) => Promise<AgentStreamResult> }

    • externalexecute: (instructionOrOptions) => Promise<AgentStreamResult>
        • (instructionOrOptions): Promise<AgentStreamResult>

        • Parameters

          • externalinstructionOrOptions: string | AgentStreamExecuteOptions

          Returns Promise<AgentStreamResult>

externalclose

  • close(opts): Promise<void>

  • Best-effort cleanup of context and launched resources.

    Parameters

    • externaloptionalopts: { force?: boolean }
      • externaloptionalforce: boolean

    Returns Promise<void>

externalconnectURL

  • connectURL(): string

  • Return the browser-level CDP WebSocket endpoint.

    Returns string

externalextract

  • extract(): Promise<{ pageText: string }>
  • extract(options): Promise<{ pageText: string }>
  • extract(instruction, options): Promise<{ extraction: string }>
  • extract<T>(instruction, schema, options): Promise<InferStagehandSchema<T>>

  • Run an "extract" instruction through the ExtractHandler.

    Accepted forms:

    • extract() → pageText
    • extract(options) → pageText
    • extract(instruction) → defaultExtractSchema
    • extract(instruction, schema) → schema-inferred
    • extract(instruction, schema, options)

    Returns Promise<{ pageText: string }>

externalinit

  • init(): Promise<void>

  • Entrypoint: initializes handlers, launches Chrome or Browserbase, and sets up a CDP context.

    Returns Promise<void>

externalisAgentReplayActive

  • isAgentReplayActive(): boolean

  • Returns boolean

externalobserve

  • observe(): Promise<Action[]>
  • observe(options): Promise<Action[]>
  • observe(instruction, options): Promise<Action[]>

  • Run an "observe" instruction through the ObserveHandler.

    Returns Promise<Action[]>

externalrecordAgentReplayStep

  • recordAgentReplayStep(step): void

  • Parameters

    • externalstep: AgentReplayStep

    Returns void

externalupdateMetrics

  • updateMetrics(functionName, promptTokens, completionTokens, reasoningTokens, cachedInputTokens, inferenceTimeMs): void

  • Parameters

    • externalfunctionName: V3FunctionName
    • externalpromptTokens: number
    • externalcompletionTokens: number
    • externalreasoningTokens: number
    • externalcachedInputTokens: number
    • externalinferenceTimeMs: number

    Returns void

Page Options