Skip to main content
This guide sets up a Claude Managed Agent that browses the web through a Browserbase session. You create the agent and environment once, then dispatch as many runs 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 dispatches. 
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  defaultHeaders: { "anthropic-beta": "managed-agents-2026-04-01" },
});

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}`);
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. Dispatch a run

Each dispatch is one turn of the agent loop. Pass the user prompt plus the Browserbase credentials Claude needs to create a session. The prompt tells Claude how to create a 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 run = await client.beta.agents.dispatch(process.env.MANAGED_AGENT_ID!, {
  environment_id: process.env.MANAGED_ENVIRONMENT_ID!,
  input: [{ role: "user", content: prompt }],
});

console.log(run.output);
Anthropic runs the loop to completion and returns the final message plus tool-use traces. The Browserbase session lives for the duration of the run and records everything Claude does.

​
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 run ends, the full video replay appears in session recordings.

​
Ending the session

Managed Agents tears down the sandbox when the run finishes. 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://....
Managed Agents has a default dispatch timeout. For long tasks, split work across multiple dispatches and pass prior tool_use_id references so Claude picks up where it left off.
Don’t end the Browserbase session between dispatches. 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.

​
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.