Stagehand - Stagehand

Stagehand owns the browser connection and exposes top-level lifecycle, metrics, and AI methods.

TypeScript
Python
Go

Quick start

import { localBrowser, Stagehand } from "@browserbasehq/stagehand";

const stagehand = await Stagehand.create({ browser: await localBrowser.launch() });

create()

Create a Stagehand instance and connect it to a browser. Stagehand.create() is the only way to build one; there is no public constructor, and the returned instance is already initialized.

const stagehand = await Stagehand.create({ browser: await localBrowser.launch() });

StagehandBrowser

required

A browser handle from browserbase.launch(), browserbase.connect(), localBrowser.launch(), or localBrowser.connect(). Each handle can back only one Stagehand instance.

Promise<Stagehand>

An initialized Stagehand instance.

Properties

Read-only accessors on an instance.

const page = await stagehand.browser.context.activePage();

StagehandBrowser

The browser handle you passed to Stagehand.create(). Reach pages and the context through it when you hold the instance but not the handle: stagehand.browser.context. Stagehand does not close this browser for you.

boolean

Whether the instance is connected and able to serve calls. This is false after close().

close()

Close the Stagehand session and release browser resources.

await stagehand.close();

Promise<void>

Resolves after the operation completes.

experimentalBatch()

Run a trusted, self-contained JavaScript callback inside the Stagehand extension service worker. Operations made through the supplied batch context route directly through the worker, avoiding an SDK-to-browser round trip for every command.

Batch callbacks execute in the Stagehand service worker, not the webpage. Treat callback source as application code rather than untrusted input.

const result = await stagehand.experimentalBatch(
  async (batch, input) => {
    await batch.page.goto(input.url);
    await batch.act("Click More information");

    return {
      title: await batch.page.title(),
      heading: await batch.page.locator("h1").innerText(),
    };
  },
  { url: "https://example.com" },
);

Callback arguments

Stagehand invokes the function in the service worker with two arguments: a worker-local ExperimentalBatchContext and the JSON input supplied to experimentalBatch().

await callback(
  {
    page: workerPage,
    context: workerContext,
    act: workerAct,
    observe: workerObserve,
    extract: workerExtract,
    metrics: workerMetrics,
  },
  input,
);

The function parameter names are chosen by the caller. Destructuring is ordinary JavaScript shorthand, not special Stagehand injection syntax:

async ({ page, act }, input) => {
  await page.goto(input.url);
  await act("Click More information");
};

// Equivalent to:
async (batch, input) => {
  const page = batch.page;
  const act = batch.act;
};

Callbacks may ignore arguments they do not need. For example, await stagehand.experimentalBatch(async () => "done") is valid.

ExperimentalBatchCallback<Input, Result>

A self-contained callback executed in the extension service worker. It receives the batch context first and input second. Values from the caller’s lexical scope are not captured.

Input

JSON-serializable input passed as the callback’s second argument. When omitted, the callback receives undefined; pass null explicitly to receive null.

ExperimentalBatchOptions

Options controlling the selected page and overall deadline.

Page

The page exposed as the callback context’s page. The active page at batch startup is used when omitted. This does not change the default target of act(), observe(), or extract(); those methods use their own page option or the active page when called.

number

The overall callback deadline in milliseconds. Defaults to 30,000.

Promise<Awaited<Result>>

The callback’s JSON-serializable return value.

Batch callback context

The callback receives an ExperimentalBatchContext, not the outer SDK Stagehand instance:

page: the worker-local Page selected when the batch starts;
context: a worker-local browser context facade;
act, observe, and extract: the normal Stagehand AI operations;
metrics: the normal Stagehand metrics operation.

The context intentionally does not expose context.close(), Stagehand lifecycle methods, nested callback batches, or page event subscriptions. Host-only behavior such as local file paths and screenshot output paths is also unavailable because the callback runs in a browser service worker, not Node.js.

Passing data across the worker boundary

The callback is serialized and evaluated in a different JavaScript runtime, so it cannot capture variables from the calling process. Pass external data through input, similarly to page.evaluate():

const selector = "button[type=submit]";

// Incorrect: selector is not defined in the service worker.
await stagehand.experimentalBatch(async ({ page }) => {
  await page.locator(selector).click();
});

// Correct: input explicitly crosses the runtime boundary.
await stagehand.experimentalBatch(
  async ({ page }, input) => {
    await page.locator(input.selector).click();
  },
  { selector },
);

Both input and the callback’s return value must be JSON-serializable.

Selecting and targeting pages

options.page transfers an SDK page ID to the worker. The callback receives the corresponding worker-local page as batch.page; the outer Page object itself does not cross the boundary.

const [myPage] = await stagehand.browser.context.pages();

await stagehand.experimentalBatch(
  async ({ page: selectedPage }, input) => {
    await selectedPage.goto(input.url);
  },
  { url: "https://example.com" },
  { page: myPage },
);

batch.page is fixed when the batch starts: it represents options.page, or the active page at startup when no page is supplied. The AI methods follow the same targeting rules as the regular SDK: an operation-level page option wins; otherwise they resolve the active page when the operation runs. Changing the active page therefore affects later act(), observe(), and extract() calls, but does not replace batch.page.

await stagehand.experimentalBatch(async (batch) => {
  const nextPage = await batch.context.newPage("https://example.com/next");
  await batch.context.setActivePage(nextPage);

  await batch.act("Click Continue"); // Uses nextPage, the current active page.
  await batch.act("Click Back", { page: batch.page }); // Explicitly uses the startup page.
});

Timeout cancellation prevents the callback from starting further Stagehand operations. An operation already running when the timeout occurs may still finish, so a batch is not an atomic transaction.

metrics()

Return token usage and inference timing metrics for this session. Each Stagehand instance starts at zero. Every successful operation returns metadata.usage; deterministic actions and cache hits report zero-valued usage, so they leave the counters unchanged. Calls that throw before returning a result are not recorded. Reading metrics does not reset them.

const metrics = await stagehand.metrics();

Promise<StagehandMetrics>

The operation result.

number

Prompt tokens used.

number

Completion tokens used.

number

Reasoning tokens used.

number

Cached input tokens used.

number

Inference time in milliseconds.

number

Prompt tokens used.

number

Completion tokens used.

number

Reasoning tokens used.

number

Cached input tokens used.

number

Inference time in milliseconds.

number

Prompt tokens used.

number

Completion tokens used.

number

Reasoning tokens used.

number

Cached input tokens used.

number

Inference time in milliseconds.

number

Prompt tokens used.

number

Completion tokens used.

number

Reasoning tokens used.

number

Cached input tokens used.

number

Inference time in milliseconds.

act()

Perform an action described in natural language.

const result = await stagehand.act("Click the sign in button");

Action | string

A natural-language action to perform, or an action returned by observe().

string

The CSS selector or XPath for the action target.

string

A human-readable description of the action.

string

The action method to execute.

string[]

Arguments to pass to the action method.

StagehandClientActOptions

Options that configure this operation.

Caching

Override server-side caching with a boolean or threshold options object.

number

The positive identical-result threshold required before serving a cache hit.

Locator[]

Page-created locators to exclude from instruction-planning context. Create each with page.locator("..."); use .nth(index) on a locator to exclude only that indexed match.

Locator

The page locator that identifies the action target. Create it with page.locator("..."); use .nth(index) on the locator to target a specific match.

ModelConfig

Model configuration for this call. When neither this nor an initialized model exists, Browserbase selects one automatically for Gateway sessions.

string

The model provider API key.

object

Additional model provider headers.

ModelName

A supported provider-prefixed model identifier.

number

The operation timeout in milliseconds.

Variables

Variables available to the instruction.

Promise<ActResult>

The operation result.

ActResultData

The action outcome.

string

A summary of the completed action.

Action[]

The actions that were performed.

string[]

Arguments passed to the action.

string

A human-readable action description.

string

The action method.

string

The action target selector.

string

The operation message.

boolean

Whether the action succeeded.

StagehandResultMetadata

Metadata associated with the operation.

CacheMetadata

Cache observability for this result; status is DISABLED when no cache lookup ran.

CacheStatus

"HIT" when a cached result was served, "MISS" when the result was computed, or "DISABLED" when no cache lookup ran.

number

Times this cache key has been seen, including this request.

number

The hit-count threshold in effect for this key.

string

Why the cache did not serve this request; misses only.

CacheTokenSavings

LLM tokens avoided by serving this request from cache; hits only.

number

Input tokens avoided.

number

Output tokens avoided.

number

Total tokens avoided.

string

The action ID associated with the operation.

StagehandResultUsage

Aggregate LLM usage for the operation. All counters are 0 when the operation does not run inference.

number

Input tokens consumed by all LLM calls.

number

Output tokens consumed by all LLM calls.

number

Reasoning tokens consumed by all LLM calls.

number

Cached input tokens used by all LLM calls.

number

Total time spent waiting for LLM inference, in milliseconds.

observe()

Find candidate actions on the page from an optional instruction.

const actions = await stagehand.observe("Find the sign in button");

string

The natural-language instruction.

StagehandClientObserveOptions

Options that configure this operation.

Caching

Override server-side caching for this request. Requests with locator or ignoreLocators bypass server-side caching and return metadata.cache.status as DISABLED.

number

The identical-result threshold required before serving a cache hit.

Locator[]

Page-created CSS or XPath locators to exclude from consideration. Create each with page.locator("..."); use .nth(index) on a locator to exclude only that indexed match. text= locators are not yet supported for observe snapshot scoping.

Locator

A page-created CSS or XPath locator that scopes the operation. Create it with page.locator("..."); use .nth(index) on the locator to target a specific match. text= locators are not yet supported for observe snapshot scoping.

ModelConfig

Model configuration for this call. When neither this nor an initialized model exists, Browserbase selects one automatically for Gateway sessions.

string

The model provider API key.

object

Additional model provider headers.

ModelName

The model identifier.

number

The operation timeout in milliseconds.

Variables

Variables available to the instruction.

Promise<ObserveResult>

The operation result.

Action[]

Candidate actions found on the page.

string[]

Arguments passed to the action.

string

A human-readable action description.

string

The action method.

string

The action target selector.

StagehandResultMetadata

Metadata associated with the operation.

CacheMetadata

Cache observability for this result; status is DISABLED when no cache lookup ran.

CacheStatus

Whether server-side caching served or computed this result.

number

Times this cache key has been seen, including this request.

number

The hit-count threshold in effect for this key.

string

Why the cache did not serve this request; misses only.

CacheTokenSavings

LLM tokens avoided by serving this request from cache; hits only.

number

Input tokens avoided.

number

Output tokens avoided.

number

Total tokens avoided.

string

The action ID associated with the operation.

StagehandResultUsage

Aggregate LLM usage for the operation. All counters are 0 when the operation does not run inference.

number

Input tokens consumed by all LLM calls.

number

Output tokens consumed by all LLM calls.

number

Reasoning tokens consumed by all LLM calls.

number

Cached input tokens used by all LLM calls.

number

Total time spent waiting for LLM inference, in milliseconds.

extract()

Extract structured data from the page.

const product = await stagehand.extract("Extract the product", ProductSchema);
console.log(product.data, product.metadata.cache.status);

string

The natural-language instruction.

Schema

The schema used to validate extracted data. Defaults to an object with a string extraction field when omitted; when selecting a custom schema generic, provide the matching runtime schema.

StagehandClientExtractOptions

Options that configure this operation.

Caching

Override server-side caching for this request.

number

The identical-result threshold required before serving a cache hit.

Locator[]

Locator

ModelConfig

Model configuration for this call. When neither this nor an initialized model exists, Browserbase selects one automatically for Gateway sessions.

string

The model provider API key.

object

Additional model provider headers.

ModelName

The model identifier.

boolean

Whether the operation may use a screenshot.

number

The operation timeout in milliseconds.

Promise<ExtractResult<Schema>>

The extraction result.

z.output<Schema>

Data validated against the caller’s schema.

StagehandResultMetadata

Metadata associated with the extraction.

CacheMetadata

Cache observability for this result; status is DISABLED when no cache lookup ran.

CacheStatus

Whether server-side caching served or computed this result.

number

Times this cache key has been seen, including this request.

number

The hit-count threshold in effect for this key.

string

Why the cache did not serve this request; misses only.

CacheTokenSavings

LLM tokens avoided by serving this request from cache; hits only.

number

Input tokens avoided.

number

Output tokens avoided.

number

Total tokens avoided.

string

The action ID associated with the extraction.

StagehandResultUsage

Aggregate LLM usage for the operation. All counters are 0 when the operation does not run inference.

number

Input tokens consumed by all LLM calls.

number

Output tokens consumed by all LLM calls.

number

Reasoning tokens consumed by all LLM calls.

number

Cached input tokens used by all LLM calls.

number

Total time spent waiting for LLM inference, in milliseconds.

Quick start

from stagehand import Stagehand, local_browser

stagehand = await Stagehand.create(browser=await local_browser.launch())

create()

Create a Stagehand instance and connect it to a browser. Stagehand.create() is the only way to build one; there is no public constructor, and the returned instance is already initialized.

stagehand = await Stagehand.create(browser=await local_browser.launch())

StagehandBrowser

required

A browser handle from browserbase.launch(), browserbase.connect(), local_browser.launch(), or local_browser.connect(). Each handle can back only one Stagehand instance.

Stagehand

An initialized Stagehand instance.

Properties

Read-only accessors on an instance.

page = await stagehand.browser.context.active_page()

StagehandBrowser

bool

Whether the instance is connected and able to serve calls. This is False after close().

close()

Close the Stagehand session and release browser resources.

await stagehand.close()

None

Resolves after the operation completes.

experimental_batch()

Run trusted, self-contained JavaScript source inside the Stagehand extension service worker. Operations made through the supplied batch context route directly through the worker, avoiding a Python-to-browser round trip for every command. Python source is not translated to JavaScript; this method accepts an explicit JavaScript function string.

Batch callbacks execute in the Stagehand service worker, not the webpage. Treat callback source as application code rather than untrusted input.

result = await stagehand.experimental_batch(
    """
    async (batch, input) => {
      await batch.page.goto(input.url);
      await batch.act("Click More information");
      return { title: await batch.page.title() };
    }
    """,
    {"url": "https://example.com"},
)

Stagehand evaluates the function in the service worker and calls it with two JavaScript arguments:

a worker-local batch context containing page, context, act, observe, extract, and metrics;
the decoded JSON value passed as the Python method’s input argument.

JavaScript destructuring such as async ({ page, act }, input) => { ... } only creates local variables from that context. It does not select a page or tell Stagehand which values to inject.

str

Self-contained JavaScript function source executed in the extension service worker. Python variables and closures are not captured.

object

JSON-serializable input passed as the JavaScript callback’s second argument. When omitted, the callback receives JavaScript undefined; explicitly passing None produces JavaScript null.

int

The overall callback deadline in milliseconds. Defaults to 30,000.

Page | None

object

The callback’s decoded JSON return value.

Batch callback context

The first JavaScript argument is a batch context, not the outer Python Stagehand object:

batch.page: the worker-local page selected when the batch starts;
batch.context: a worker-local browser context facade;
batch.act(), batch.observe(), and batch.extract(): Stagehand AI operations;
batch.metrics(): Stagehand metrics.

The context does not expose context.close(), Stagehand lifecycle methods, nested batches, or page event subscriptions. Node.js APIs, local filesystem paths, screenshot output paths, and other host-only behavior are unavailable in the browser service worker.

Passing input instead of capturing variables

The JavaScript source cannot reference Python variables. Transfer values explicitly through the method’s second argument:

selector = "button[type=submit]"

result = await stagehand.experimental_batch(
    """
    async (batch, input) => {
      await batch.page.locator(input.selector).click();
      return { title: await batch.page.title() };
    }
    """,
    {"selector": selector},
)

Both input and output must be JSON-serializable.

Selecting and targeting pages

Passing page=my_page transfers the Python page’s ID. The service worker reconstructs it as batch.page; the Python Page object itself is not available inside the JavaScript source.

my_page = (await stagehand.browser.context.pages())[0]

result = await stagehand.experimental_batch(
    """
    async (batch, input) => {
      await batch.page.goto(input.url);
      return { title: await batch.page.title() };
    }
    """,
    {"url": "https://example.com"},
    page=my_page,
)

batch.page is fixed at batch startup. It represents the supplied page, or the active page at startup when page is omitted. batch.act(), batch.observe(), and batch.extract() instead use their own operation-level page option or resolve the active page when called, matching ordinary Stagehand behavior.Timeout cancellation prevents later Stagehand operations from starting, but an operation already running at the deadline may still finish. Callback batches are not atomic transactions.

metrics()

Return token usage and inference timing metrics for this session. Each Stagehand instance starts at zero. Every successful operation returns metadata.usage; deterministic actions and cache hits report zero-valued usage, so they leave the counters unchanged. Calls that raise before returning a result are not recorded. Reading metrics does not reset them.

metrics = await stagehand.metrics()

StagehandMetrics

The operation result.

float

Prompt tokens used.

float

Completion tokens used.

float

Reasoning tokens used.

float

Cached input tokens used.

float

Inference time in milliseconds.

float

Prompt tokens used.

float

Completion tokens used.

float

Reasoning tokens used.

float

Cached input tokens used.

float

Inference time in milliseconds.

float

Prompt tokens used.

float

Completion tokens used.

float

Reasoning tokens used.

float

Cached input tokens used.

float

Inference time in milliseconds.

float

Prompt tokens used.

float

Completion tokens used.

float

Reasoning tokens used.

float

Cached input tokens used.

float

Inference time in milliseconds.

act()

Perform an action described in natural language.

result = await stagehand.act("Click the sign in button")

Action | ActionInput | str

A natural-language action to perform, or an action returned by observe().

str

The CSS selector or XPath for the action target.

str

A human-readable description of the action.

str

The action method to execute.

list[str]

Arguments to pass to the action method.

Page | None

The SDK page to target. Uses the active page when omitted.

ModelConfig

Model configuration for this call. When neither this nor an initialized model exists, Browserbase selects one automatically for Gateway sessions.

str

The model provider API key.

dict[str, object]

Additional model provider headers.

ModelName

A supported provider-prefixed model identifier.

Variables | None

Variables available to the instruction.

float | None

Maximum wait time in milliseconds.

Locator | None

The page locator that identifies the action target. Create it with page.locator("..."); use .nth(index) on the locator to target a specific match.

list[Locator] | None

Page-created locators to exclude from instruction-planning context. Create each with page.locator("..."); use .nth(index) on a locator to exclude only that indexed match.

bool | CacheOptions | None

Override server-side caching with a boolean or CacheOptions.

int

The positive identical-result threshold required before serving a cache hit.

ActResult

The operation result.

ActResultData

The action outcome.

str

A summary of the completed action.

list[Action]

The actions that were performed.

list[str]

Arguments passed to the action.

str

A human-readable action description.

str

The action method.

str

The action target selector.

str

The operation message.

bool

Whether the action succeeded.

StagehandResultMetadata

Metadata associated with the operation.

CacheMetadata

Cache observability for this result; status is DISABLED when no cache lookup ran.

CacheStatus

"HIT" when a cached result was served, "MISS" when the result was computed, or "DISABLED" when no cache lookup ran.

int

Times this cache key has been seen, including this request.

int

The hit-count threshold in effect for this key.

str

Why the cache did not serve this request; misses only.

CacheTokenSavings

LLM tokens avoided by serving this request from cache; hits only.

int

Input tokens avoided.

int

Output tokens avoided.

int

Total tokens avoided.

str

The action ID associated with the operation.

StagehandResultUsage

Aggregate LLM usage for the operation. All counters are 0 when the operation does not run inference.

int

Input tokens consumed by all LLM calls.

int

Output tokens consumed by all LLM calls.

int

Reasoning tokens consumed by all LLM calls.

int

Cached input tokens used by all LLM calls.

int

Total time spent waiting for LLM inference, in milliseconds.

observe()

Find candidate actions on the page from an optional instruction.

actions = await stagehand.observe("Find the sign in button")

str | None

The natural-language instruction.

Page | None

The SDK page to target. Uses the active page when omitted.

ModelConfig

Model configuration for this call. When neither this nor an initialized model exists, Browserbase selects one automatically for Gateway sessions.

str

The model provider API key.

dict[str, object]

Additional model provider headers.

ModelName

The model identifier.

Variables | None

Variables available to the instruction.

float | None

Maximum wait time in milliseconds.

Locator | None

list[Locator] | None

bool | CacheOptions | None

Override server-side caching for this request. Requests with locator or ignore_locators bypass server-side caching and return metadata.cache.status as DISABLED.

int

The identical-result threshold required before serving a cache hit.

ObserveResult

The operation result.

list[Action]

Candidate actions found on the page.

list[str]

Arguments passed to the action.

str

A human-readable action description.

str

The action method.

str

The action target selector.

StagehandResultMetadata

Metadata associated with the operation.

CacheMetadata

Cache observability for this result; status is DISABLED when no cache lookup ran.

CacheStatus

Whether server-side caching served or computed this result.

int

Times this cache key has been seen, including this request.

int

The hit-count threshold in effect for this key.

str

Why the cache did not serve this request; misses only.

CacheTokenSavings

LLM tokens avoided by serving this request from cache; hits only.

int

Input tokens avoided.

int

Output tokens avoided.

int

Total tokens avoided.

str

The action ID associated with the operation.

StagehandResultUsage

Aggregate LLM usage for the operation. All counters are 0 when the operation does not run inference.

int

Input tokens consumed by all LLM calls.

int

Output tokens consumed by all LLM calls.

int

Reasoning tokens consumed by all LLM calls.

int

Cached input tokens used by all LLM calls.

int

Total time spent waiting for LLM inference, in milliseconds.

extract()

Extract structured data from the page.

product = await stagehand.extract("Extract the product", Product)
print(product.data, product.metadata.cache.status)

str

The natural-language instruction.

type[ResultModel]

The schema used to validate extracted data. Defaults to a model with a string extraction field.

Page | None

The SDK page to target. Uses the active page when omitted.

ModelConfig

Model configuration for this call. When neither this nor an initialized model exists, Browserbase selects one automatically for Gateway sessions.

str

The model provider API key.

dict[str, object]

Additional model provider headers.

ModelName

The model identifier.

float | None

Maximum wait time in milliseconds.

Locator | None

bool | None

Whether extraction may use a screenshot.

list[Locator] | None

bool | CacheOptions | None

Override server-side caching for this request.

int

The identical-result threshold required before serving a cache hit.

ExtractResult[ResultModel]

The extraction result.

ResultModel

Data validated against the caller’s Pydantic model.

StagehandResultMetadata

Metadata associated with the extraction.

CacheMetadata

Cache observability for this result; status is DISABLED when no cache lookup ran.

CacheStatus

Whether server-side caching served or computed this result.

int

Times this cache key has been seen, including this request.

int

The hit-count threshold in effect for this key.

str

Why the cache did not serve this request; misses only.

CacheTokenSavings

LLM tokens avoided by serving this request from cache; hits only.

int

Input tokens avoided.

int

Output tokens avoided.

int

Total tokens avoided.

str

The action ID associated with the extraction.

StagehandResultUsage

Aggregate LLM usage for the operation. All counters are 0 when the operation does not run inference.

int

Input tokens consumed by all LLM calls.

int

Output tokens consumed by all LLM calls.

int

Reasoning tokens consumed by all LLM calls.

int

Cached input tokens used by all LLM calls.

int

Total time spent waiting for LLM inference, in milliseconds.

Quick start

package main

import (
	"context"
	"log"

	stagehand "github.com/browserbase/stagehand/packages/sdk-go"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	browser, err := stagehand.LaunchLocalBrowser(ctx, nil)
	if err != nil {
		return err
	}
	defer browser.Close(ctx)

	client, err := stagehand.Create(ctx, stagehand.CreateOptions{Browser: browser})
	if err != nil {
		return err
	}
	defer client.Close(ctx)

	return nil
}

Every Stagehand call takes a context.Context as its first parameter and returns an error as its last result; cancel the context to abandon the call.

Create()

Create a Stagehand instance and connect it to a browser. The package-level stagehand.Create() function is the only way to build one, and the returned instance is already initialized.

func Create(ctx context.Context, options CreateOptions) (*Stagehand, error)

*Browser

required

A browser handle from LaunchBrowserbase(), ConnectBrowserbase(), LaunchLocalBrowser(), or ConnectLocalBrowser(). Each handle can back only one Stagehand instance.

The remaining CreateOptions fields (APIKey, APIURL, Cache, DOMSettleTimeoutMs, Model, Generate, Logging, SelfHeal, SystemPrompt, and Telemetry) are optional and covered in the configuration guides.

(*Stagehand, error)

An initialized Stagehand instance.

Properties

Read-only accessor methods on an instance.

browserContext, err := client.Browser().Context()
if err != nil {
	return err
}
page, err := browserContext.ActivePage(ctx)
if err != nil {
	return err
}
if _, err := page.Goto(ctx, "https://example.com", nil); err != nil {
	return err
}

*Browser

The browser handle you passed to Create(). Reach pages and the context through it when you hold the instance but not the handle: client.Browser().Context(). Stagehand does not close this browser for you.

bool

Whether the instance is connected and able to serve calls. This is false after Close().

Close()

Close the Stagehand session and release its resources. The Browser handle stays open; close it separately with browser.Close(ctx).

if err := client.Close(ctx); err != nil {
	return err
}

error

nil after the operation completes. Close() runs once; later calls return the first result.

ExperimentalBatch()

Run trusted, self-contained JavaScript source inside the Stagehand extension service worker. Operations made through the supplied batch context route directly through the worker, avoiding a Go-to-browser round trip for every command. Go source is not translated to JavaScript; this method accepts an explicit JavaScript function string.

Batch callbacks execute in the Stagehand service worker, not the webpage. Treat callback source as application code rather than untrusted input.

func (s *Stagehand) ExperimentalBatch(ctx context.Context, source string, input any, result any, options ExperimentalBatchOptions) error

var result struct {
	Title string `json:"title"`
}
err := client.ExperimentalBatch(
	ctx,
	`async (batch, input) => {
	  await batch.page.goto(input.url);
	  await batch.act("Click More information");
	  return { title: await batch.page.title() };
	}`,
	map[string]string{"url": "https://example.com"},
	&result,
	stagehand.ExperimentalBatchOptions{},
)
if err != nil {
	return err
}

Stagehand evaluates the function in the service worker and calls it with two JavaScript arguments:

a worker-local batch context containing page, context, act, observe, extract, and metrics;
the decoded JSON value passed as the Go method’s input argument.

JavaScript destructuring such as async ({ page, act }, input) => { ... } only creates local variables from that context. It does not select a page or tell Stagehand which values to inject.

string

Self-contained JavaScript function source executed in the extension service worker. Go variables are not captured.

any

JSON-serializable input passed as the JavaScript callback’s second argument. When nil, the callback receives JavaScript undefined.

any

required

A non-nil pointer that receives the callback’s decoded JSON return value. A callback that returns undefined decodes as JSON null.

ExperimentalBatchOptions

Batch configuration. Pass the zero value stagehand.ExperimentalBatchOptions{} for the defaults.

time.Duration

The overall callback deadline. Defaults to 30 seconds.

*Page

The page exposed as the callback context’s page. The active page at batch startup is used when omitted. This does not change the default target of Act(), Observe(), or Extract(); those methods use their own Page option or the active page when called.

error

nil after the callback’s return value is decoded into result.

Batch callback context

The first JavaScript argument is a batch context, not the outer Go Stagehand client:

batch.page: the worker-local page selected when the batch starts;
batch.context: a worker-local browser context facade;
batch.act(), batch.observe(), and batch.extract(): Stagehand AI operations;
batch.metrics(): Stagehand metrics.

Passing input instead of capturing variables

The JavaScript source cannot reference Go variables. Transfer values explicitly through the method’s input argument:

selector := "button[type=submit]"

var result struct {
	Title string `json:"title"`
}
err := client.ExperimentalBatch(
	ctx,
	`async (batch, input) => {
	  await batch.page.locator(input.selector).click();
	  return { title: await batch.page.title() };
	}`,
	map[string]string{"selector": selector},
	&result,
	stagehand.ExperimentalBatchOptions{},
)
if err != nil {
	return err
}

Both input and output must be JSON-serializable.

Selecting and targeting pages

Passing Page in the options transfers the Go page’s ID. The service worker reconstructs it as batch.page; the Go Page object itself is not available inside the JavaScript source.

pages, err := browserContext.Pages(ctx)
if err != nil {
	return err
}
myPage := pages[0]

var result struct {
	Title string `json:"title"`
}
err = client.ExperimentalBatch(
	ctx,
	`async (batch, input) => {
	  await batch.page.goto(input.url);
	  return { title: await batch.page.title() };
	}`,
	map[string]string{"url": "https://example.com"},
	&result,
	stagehand.ExperimentalBatchOptions{Page: myPage},
)
if err != nil {
	return err
}

batch.page is fixed at batch startup. It represents the supplied page, or the active page at startup when Page is omitted. batch.act(), batch.observe(), and batch.extract() instead use their own operation-level page option or resolve the active page when called, matching ordinary Stagehand behavior.Timeout cancellation prevents later Stagehand operations from starting, but an operation already running at the deadline may still finish. Callback batches are not atomic transactions.

Metrics()

Return token usage and inference timing metrics for this session. Each Stagehand instance starts at zero. Every successful operation returns Metadata.Usage; deterministic actions and cache hits report zero-valued usage, so they leave the counters unchanged. Calls that return an error before producing a result are not recorded. Reading metrics does not reset them.

metrics, err := client.Metrics(ctx)
if err != nil {
	return err
}
fmt.Println(metrics)

(StagehandMetrics, error)

The operation result.

float64

Prompt tokens used.

float64

Completion tokens used.

float64

Reasoning tokens used.

float64

Cached input tokens used.

float64

Inference time in milliseconds.

float64

Prompt tokens used.

float64

Completion tokens used.

float64

Reasoning tokens used.

float64

Cached input tokens used.

float64

Inference time in milliseconds.

float64

Prompt tokens used.

float64

Completion tokens used.

float64

Reasoning tokens used.

float64

Cached input tokens used.

float64

Inference time in milliseconds.

float64

Prompt tokens used.

float64

Completion tokens used.

float64

Reasoning tokens used.

float64

Cached input tokens used.

float64

Inference time in milliseconds.

Act()

Perform an action described in natural language.

result, err := client.Act(ctx, stagehand.ActInstruction("Click the sign in button"), nil)
if err != nil {
	return err
}
fmt.Println(result)

func (s *Stagehand) Act(ctx context.Context, instruction ActInstructionValue, options *StagehandClientActOptions) (ActResult, error)

ActInstructionValue

A natural-language action to perform, or an action returned by Observe(). Construct with stagehand.ActInstruction("...") for natural language, or stagehand.ObservedAction(action) for an observed Action with these fields:

string

The CSS selector or XPath for the action target.

string

A human-readable description of the action.

*string

The action method to execute.

[]string

Arguments to pass to the action method.

*StagehandClientActOptions

Options that configure this operation. Pass nil for defaults.

*Caching

Override server-side caching for this request. Construct with stagehand.CacheEnabled(enabled) or stagehand.CacheWithThreshold(threshold), where the threshold is the positive identical-result count required before serving a cache hit.

[]*PageLocator

Page-created locators to exclude from instruction-planning context. Create each with page.Locator("..."); use Nth(index) on a locator to exclude only that indexed match.

*PageLocator

The page locator that identifies the action target. Create it with page.Locator("..."); use Nth(index) on the locator to target a specific match.

*ModelConfig

Model configuration for this call. When neither this nor an initialized model exists, Browserbase selects one automatically for Gateway sessions.

*string

The model provider API key.

ModelConfigHeaders

Additional model provider headers.

ModelName

A supported provider-prefixed model identifier.

*Page

The SDK page to target. Uses the active page when omitted.

*float64

The operation timeout in milliseconds.

Variables

Variables available to the instruction.

(ActResult, error)

The operation result.

ActResultData

The action outcome.

string

A summary of the completed action.

[]Action

The actions that were performed.

[]string

Arguments passed to the action.

string

A human-readable action description.

*string

The action method.

string

The action target selector.

string

The operation message.

bool

Whether the action succeeded.

StagehandResultMetadata

Metadata associated with the operation.

CacheMetadata

Cache observability for this result; status is DISABLED when no cache lookup ran.

CacheStatus

CacheStatusHIT when a cached result was served, CacheStatusMISS when the result was computed, or CacheStatusDISABLED when no cache lookup ran.

*int

Times this cache key has been seen, including this request.

*int

The hit-count threshold in effect for this key.

*string

Why the cache did not serve this request; misses only.

*CacheTokenSavings

LLM tokens avoided by serving this request from cache; hits only.

int

Input tokens avoided.

int

Output tokens avoided.

int

Total tokens avoided.

*string

The action ID associated with the operation.

StagehandResultUsage

Aggregate LLM usage for the operation. All counters are 0 when the operation does not run inference.

int

Input tokens consumed by all LLM calls.

int

Output tokens consumed by all LLM calls.

int

Reasoning tokens consumed by all LLM calls.

int

Cached input tokens used by all LLM calls.

int

Total time spent waiting for LLM inference, in milliseconds.

Observe()

Find candidate actions on the page from an optional instruction.

instruction := "Find the sign in button"

actions, err := client.Observe(ctx, &instruction, nil)
if err != nil {
	return err
}
fmt.Println(actions)

func (s *Stagehand) Observe(ctx context.Context, instruction *string, options *StagehandClientObserveOptions) (ObserveResult, error)

*string

The natural-language instruction. Pass nil to observe without one.

*StagehandClientObserveOptions

Options that configure this operation. Pass nil for defaults.

*Caching

Override server-side caching for this request. Construct with stagehand.CacheEnabled(enabled) or stagehand.CacheWithThreshold(threshold), where the threshold is the identical-result count required before serving a cache hit.

[]*PageLocator

Page-created CSS or XPath locators to exclude from consideration. Create each with page.Locator("..."); use Nth(index) on a locator to exclude only that indexed match. text= locators are not yet supported for observe snapshot scoping.

*PageLocator

A page-created CSS or XPath locator that scopes the operation. Create it with page.Locator("..."); use Nth(index) on the locator to target a specific match. text= locators are not yet supported for observe snapshot scoping.

*ModelConfig

Model configuration for this call. When neither this nor an initialized model exists, Browserbase selects one automatically for Gateway sessions.

*string

The model provider API key.

ModelConfigHeaders

Additional model provider headers.

ModelName

The model identifier.

*Page

The SDK page to target. Uses the active page when omitted.

*float64

The operation timeout in milliseconds.

Variables

Variables available to the instruction.

(ObserveResult, error)

The operation result.

[]Action

Candidate actions found on the page.

[]string

Arguments passed to the action.

string

A human-readable action description.

*string

The action method.

string

The action target selector.

StagehandResultMetadata

Metadata associated with the operation.

CacheMetadata

Cache observability for this result; status is DISABLED when no cache lookup ran.

CacheStatus

Whether server-side caching served or computed this result.

*int

Times this cache key has been seen, including this request.

*int

The hit-count threshold in effect for this key.

*string

Why the cache did not serve this request; misses only.

*CacheTokenSavings

LLM tokens avoided by serving this request from cache; hits only.

int

Input tokens avoided.

int

Output tokens avoided.

int

Total tokens avoided.

*string

The action ID associated with the operation.

StagehandResultUsage

Aggregate LLM usage for the operation. All counters are 0 when the operation does not run inference.

int

Input tokens consumed by all LLM calls.

int

Output tokens consumed by all LLM calls.

int

Reasoning tokens consumed by all LLM calls.

int

Cached input tokens used by all LLM calls.

int

Total time spent waiting for LLM inference, in milliseconds.

Extract()

Extract structured data from the page. Extract is a package-level generic function rather than a method: the type parameter is the schema. Stagehand derives a JSON Schema from T, extracts matching data, and decodes the result into a T. Unlike TypeScript and Python, there is no default schema; supply T explicitly.

type Product struct {
	Name  string  `json:"name"`
	Price float64 `json:"price"`
}

product, err := stagehand.Extract[Product](ctx, client, "Extract the product", nil)
if err != nil {
	return err
}
fmt.Println(product.Data, product.Metadata.Cache.Status)

func Extract[T any](ctx context.Context, client *Stagehand, instruction string, options *StagehandClientExtractOptions) (TypedExtractResult[T], error)

*Stagehand

The Stagehand instance to extract with.

string

The natural-language instruction.

*StagehandClientExtractOptions

Options that configure this operation. Pass nil for defaults.

*Caching

Override server-side caching for this request. Construct with stagehand.CacheEnabled(enabled) or stagehand.CacheWithThreshold(threshold), where the threshold is the identical-result count required before serving a cache hit.

[]*PageLocator

*PageLocator

*ModelConfig

Model configuration for this call. When neither this nor an initialized model exists, Browserbase selects one automatically for Gateway sessions.

*string

The model provider API key.

ModelConfigHeaders

Additional model provider headers.

ModelName

The model identifier.

*Page

The SDK page to target. Uses the active page when omitted.

*bool

Whether the operation may use a screenshot.

*float64

The operation timeout in milliseconds.

(TypedExtractResult[T], error)

The extraction result.

Data decoded into the caller’s type.

StagehandResultMetadata

Metadata associated with the extraction.

CacheMetadata

Cache observability for this result; status is DISABLED when no cache lookup ran.

CacheStatus

Whether server-side caching served or computed this result.

*int

Times this cache key has been seen, including this request.

*int

The hit-count threshold in effect for this key.

*string

Why the cache did not serve this request; misses only.

*CacheTokenSavings

LLM tokens avoided by serving this request from cache; hits only.

int

Input tokens avoided.

int

Output tokens avoided.

int

Total tokens avoided.

*string

The action ID associated with the extraction.

StagehandResultUsage

Aggregate LLM usage for the operation. All counters are 0 when the operation does not run inference.

int

Input tokens consumed by all LLM calls.

int

Output tokens consumed by all LLM calls.

int

Reasoning tokens consumed by all LLM calls.

int

Cached input tokens used by all LLM calls.

int

Total time spent waiting for LLM inference, in milliseconds.

​Quick start

​create()

​Properties

​close()

​experimentalBatch()

​Callback arguments

​Batch callback context

​Passing data across the worker boundary

​Selecting and targeting pages

​metrics()

​act()

​observe()

​extract()

​Quick start

​create()

​Properties

​close()

​experimental_batch()

​Batch callback context

​Passing input instead of capturing variables

​Selecting and targeting pages

​metrics()

​act()

​observe()

​extract()

​Quick start

​Create()

​Properties

​Close()

​ExperimentalBatch()

​Batch callback context

​Passing input instead of capturing variables

​Selecting and targeting pages

​Metrics()

​Act()

​Observe()

​Extract()

Quick start

create()

Properties

close()

experimentalBatch()

Callback arguments

Batch callback context

Passing data across the worker boundary

Selecting and targeting pages

metrics()

act()

observe()

extract()

Quick start

create()

Properties

close()

experimental_batch()

Batch callback context

Passing input instead of capturing variables

Selecting and targeting pages

metrics()

act()

observe()

extract()

Quick start

Create()

Properties

Close()

ExperimentalBatch()

Batch callback context

Passing input instead of capturing variables

Selecting and targeting pages

Metrics()

Act()

Observe()

Extract()