Add Browserbase to an Eve agent - Browserbase Documentation

This guide adds Browserbase to an Eve agent. You’ll give the agent Search and Fetch for lightweight web context plus a persistent browser for interactive pages.

Create an Eve agent

Eve requires Node.js 24 or newer. Create a project, then enter its directory:

npx eve@latest init browserbase-eve-agent
cd browserbase-eve-agent

Install the Browserbase extension

Add the Browserbase extension to your project:

pnpm add @browserbasehq/eve

Set your environment variables

Copy your Browserbase API key from the Dashboard. Add it and your Vercel AI Gateway key to .env:

.env

BROWSERBASE_API_KEY=bb_live_...
AI_GATEWAY_API_KEY=your_vercel_ai_gateway_key

The Browserbase API key creates cloud browsers and powers Stagehand through Browserbase Model Gateway. The Vercel AI Gateway key powers the outer Eve agent.

If you link the project to Vercel, you can use VERCEL_OIDC_TOKEN instead of AI_GATEWAY_API_KEY.

Mount the extension

Create agent/extensions/browserbase.ts:

Node.js agent/extensions/browserbase.ts

import browserbase from "@browserbasehq/eve";

export default browserbase({
  apiKey: process.env.BROWSERBASE_API_KEY!,
  model: "openai/gpt-5.4-mini",
});

Eve uses the filename as the tool namespace. This file creates tools such as browserbase__search, browserbase__fetch, browserbase__navigate, and browserbase__extract.

Configure the agent model

Create or update agent/agent.ts:

Node.js agent/agent.ts

import { defineAgent } from "eve";

export default defineAgent({
  model: "openai/gpt-5.4-mini",
});

Guide the agent's browser use

Add these instructions to agent/instructions.md:

Use Browserbase Search to discover sources, then Fetch to retrieve straightforward content.
Create a browser session only when a page requires JavaScript or interaction.
For browser tasks, navigate before you observe, act, or extract.
Stop the browser session when you finish the task.

Run the agent

Start Eve’s terminal interface:

npx eve dev

Try this prompt:

Open https://news.ycombinator.com and return the titles and URLs of the first five stories. Use a Browserbase session and stop it when you are done.

Open the Sessions dashboard to watch the agent use the browser.

Choose the right browser tool

For predictable runs, use create_session, navigate, observe, and then act or extract. Use agent when the task needs Stagehand to plan several browser steps on its own. Always call stop_session after the task.

Example agent

Compare your project with the complete runnable example.

Extension source

Review the extension’s tools, configuration, and session lifecycle.

Create an Eve agent

Install the Browserbase extension

Set your environment variables

Mount the extension

Configure the agent model

Guide the agent's browser use

Run the agent

​Choose the right browser tool

Example agent

Extension source

Choose the right browser tool