​
Overview

Stagehand is a relatively low-level AI-native framework for building browser agents in JavaScript.

Stagehand is designed to be a seamless extension of Playwright, and in particular, its Page API.

Thanks to Laminar’s native integration with Playwright, you can trace your Stagehand agents with ease.

​
Usage

1

Initialize Laminar

First, we need to initialize Laminar and pass all the LLM modules that you use in your Stagehand agents.

Import the LLM provider SDK and pass it to instrumentModules, depending on the model that you use with Stagehand.

For example, if you use OpenAI with Stagehand, you can do the following:

import { Stagehand } from '@browserbase/stagehand';
import { Laminar } from '@lmnr-ai/lmnr';
import { OpenAI } from 'openai';

Laminar.initialize({
  projectApiKey: process.env.LMNR_API_KEY,
  instrumentModules: {
    stagehand: Stagehand,
    OpenAI: OpenAI,
  },
});
2

Using Stagehand

You can now use the Stagehand API as usual.

await stagehand.init({
  modelName: 'gpt-4.1-mini',
  modelClientOptions: {
    apiKey: process.env.OPENAI_API_KEY,
  },
});
const page = stagehand.page;
await page.act("...");
3

Finalizing Stagehand traces

In order to finalize Stagehand traces, make sure to call stagehand.close() and Laminar.flush(), especially if you are using Laminar and Stagehand in standalone scripts or edge runtimes.

await stagehand.close(); // closes the browser and the parent span
await Laminar.flush(); // sends any remaining spans to Laminar

​
Example result

An example trace for page.act('go to Laminar pricing page')

​
Troubleshooting

​
I can’t see LLM calls, token counts, and costs in my trace

It is likely that you’ve started off with npx create-browser-app, which creates the package as an ESM module.

​
Solution

Remove the "type": "module" from your package.json file.

You can also explicitly set the type to commonjs in your package.json file.

package.json
"type": "commonjs"

For further reading, check the section on this issue in our Troubleshooting guide.