Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide sets up a Claude Managed Agent that browses the web through a Browserbase session. You create the agent and environment once, then start as many sessions as you need.

​
Prerequisites

​
1. Install dependencies

npm install @anthropic-ai/sdk @browserbasehq/sdk
npm install -g @browserbasehq/cli @browserbasehq/browse-cli
Claude uses @browserbasehq/browse-cli (browse) to drive the session. Session creation can go through @browserbasehq/cli (bb) or curl — install both so you can switch freely. Step 2 declares them as sandbox dependencies too.

​
2. Create the agent and environment

Create both once, store the returned IDs as env vars, and reuse them across sessions. 
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const SYSTEM_PROMPT = `You are a browsing agent. You control a remote Browserbase session via the browse CLI.

Workflow:
1. Create a Browserbase session — either with: bb sessions create --body '{"projectId":"<PROJECT_ID>"}' or with curl against https://api.browserbase.com/v1/sessions
2. Prefix every browse command with BROWSERBASE_API_KEY=<key> and use --connect <sessionId>.
3. Take screenshots to see the page. Only take snapshots (truncated with | head -200) when you need ref IDs to click.
4. Report findings concisely and cite key URLs.`;

const agent = await client.beta.agents.create({
  name: "Browserbase Agent",
  model: "claude-opus-4-7",
  system: SYSTEM_PROMPT,
  tools: [
    {
      type: "agent_toolset_20260401",
      configs: [
        { name: "web_fetch", enabled: false },
        { name: "web_search", enabled: false },
      ],
    },
  ],
});

const environment = await client.beta.environments.create({
  name: "browserbase-env",
  config: {
    type: "cloud",
    packages: {
      npm: ["@browserbasehq/cli", "@browserbasehq/browse-cli"],
    },
    networking: { type: "unrestricted" },
  },
});

console.log(`MANAGED_AGENT_ID=${agent.id}`);
console.log(`MANAGED_ENVIRONMENT_ID=${environment.id}`);
The Anthropic SDK sets the managed-agents-2026-04-01 beta header automatically. If you’re calling the REST API directly with curl, add -H "anthropic-beta: managed-agents-2026-04-01" to every request.
Disabling web_fetch and web_search forces Claude to browse through Browserbase. Leave them on and Claude shortcuts around the real browser.

​
3. Set your environment variables

ANTHROPIC_API_KEY=sk-ant-...
BROWSERBASE_API_KEY=bb_...
BROWSERBASE_PROJECT_ID=proj_...
MANAGED_AGENT_ID=agent_...
MANAGED_ENVIRONMENT_ID=env_...

​
4. Start a session and stream events

A session is one running instance of the agent. You open an SSE stream against the session, send a user message, and process events as they arrive — agent text, tool calls, and a final session.status_idle event when Claude is done. The prompt tells Claude how to create a Browserbase session. You can show it either flavor — the bb CLI or curl straight against the API. Both work; pick whichever you prefer and stay consistent. 
const prompt = `Go to Hacker News, find the top story, and summarize the comments.

You have these credentials available:
BROWSERBASE_API_KEY=${process.env.BROWSERBASE_API_KEY}
BROWSERBASE_PROJECT_ID=${process.env.BROWSERBASE_PROJECT_ID}

Create a Browserbase session with the bb CLI:
  export BROWSERBASE_API_KEY=$BROWSERBASE_API_KEY
  bb sessions create --body '{"projectId":"'$BROWSERBASE_PROJECT_ID'"}'

The command prints JSON with an \`id\` — that's your sessionId. Then drive the session:
  BROWSERBASE_API_KEY=$BROWSERBASE_API_KEY browse --json --connect <sessionId> open https://news.ycombinator.com`;

const session = await client.beta.sessions.create({
  agent: process.env.MANAGED_AGENT_ID!,
  environment_id: process.env.MANAGED_ENVIRONMENT_ID!,
  title: "Browserbase quickstart",
});

const stream = await client.beta.sessions.events.stream(session.id);

// Send the user message after the stream opens
await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [{ type: "text", text: prompt }],
    },
  ],
});

// Process streaming events until the agent goes idle
for await (const event of stream) {
  if (event.type === "agent.message") {
    for (const block of event.content) {
      process.stdout.write(block.text);
    }
  } else if (event.type === "agent.tool_use") {
    console.log(`\n[Using tool: ${event.name}]`);
  } else if (event.type === "session.status_idle") {
    console.log("\n\nAgent finished.");
    break;
  }
}
The session lives until you archive it — Anthropic only bills for compute while it’s running. Event history is persisted server-side and you can refetch it with client.beta.sessions.events.list(session.id).

​
5. Watch the run live

Every Browserbase session has a Live View URL. Grab it once the agent creates the session — from your own code with the Browserbase SDK, from the sandbox with the bb CLI, or directly with curl. 
import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });
const debug = await bb.sessions.debug(sessionId);
console.log(debug.debuggerFullscreenUrl);
Share the URL in your UI (Slack, web app, or dashboard) so users can watch Claude drive the browser in real time. After the session ends, the full video replay appears in session recordings.

​
Ending the session

Two sessions to clean up — Anthropic’s and Browserbase’s. Anthropic Managed Agents: archive the session when you’re done. Archiving terminates the container and stops compute billing. Sessions are also deleted after a TTL — see Anthropic’s docs for current values. 
await client.beta.sessions.archive(session.id);
Browserbase: sessions don’t end automatically — close them explicitly or rely on the session timeout. 
import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });
await bb.sessions.update(sessionId, {
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  status: "REQUEST_RELEASE",
});

​
Troubleshooting

Disable web_search and web_fetch in the agent_toolset_20260401 configs. Without them, Claude has to use the Browse CLI.
Pipe every snapshot through head -200. Tell Claude in the system prompt to prefer screenshot over snapshot and only fall back to snapshots when it needs a ref ID to click.
Every browse invocation needs BROWSERBASE_API_KEY in the environment. Prefix each command: BROWSERBASE_API_KEY=$KEY browse --json --connect $SID open https://....
Long-running sessions stay alive — Anthropic only times out compute, not the session itself. If you’re hitting an inactivity timeout, send another user.message event to wake the agent up. For multi-stage workflows, just keep sending events on the same session ID; the conversation history is preserved server-side.
Don’t end the Browserbase session between user messages. Pass the existing sessionId in the next prompt and Claude reconnects with browse --connect <sessionId>. Cookies and local storage persist because it’s the same browser. Across separate Anthropic sessions, use Browserbase Contexts to persist cookies and storage.

​
Next steps

Browse CLI reference

Every command Claude can issue against a Browserbase session.

Session Live View

Embed real-time browser views in your chat UI.

Contexts

Persist cookies and storage across agent runs.

Agent Identity

Verified browsers, proxies, and auth for agents on the open web.