Agents - Browserbase Documentation

Quickstart

Create your first agent run and poll for the result.

How it works

Learn how agents work, what tools they use, and how runs progress.

Run an agent

Endpoint reference for starting an agent run.

Browser agents use case

Understand when to use Agents versus building a custom browser-agent loop.

Overview

Agents are the lowest-friction way to automate work on the web with Browserbase. Describe the task in natural language, and Browserbase runs an autonomous agent that can browse, click, type, search, extract data, use files, and return a result. Use Agents when you want Browserbase to own the browser loop for you. You do not need to write Playwright scripts, wire up Stagehand, provision model providers, or deploy runtime infrastructure. Each run gets a dedicated Browserbase browser session with the same observability tools available to standard sessions.

Quick reference

Concept	What it does
Agent	The autonomous Browserbase agent that can perform one or more runs.
Run	A single natural language task executed by an agent.
Messages	The chronological transcript of what the agent did during a run.
Session	The Browserbase browser session that backs the run for live view, recording, and replay.

How it works

Send a task

Create a run with a natural language instruction and optional browser settings.

Browserbase starts the agent

Browserbase creates the browser session, runtime, tools, and model loop needed to complete the task.

The agent completes the run

The agent chooses the right tools, navigates the web, interacts with pages, and extracts the requested result.

Inspect the outcome

Poll the run, read its messages, and review the browser session when you need to debug.

Create a run

Send a task to /v1/agents/runs. The response includes an agentId and a runId.

cURL
Node.js
Python

curl -X POST https://api.browserbase.com/v1/agents/runs \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "task": "Go to Hacker News and return the top 3 stories with their titles and URLs"
  }'

const response = await fetch("https://api.browserbase.com/v1/agents/runs", {
  method: "POST",
  headers: {
    "x-bb-api-key": process.env.BROWSERBASE_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    task: "Go to Hacker News and return the top 3 stories with their titles and URLs",
  }),
});

const { agentId, runId } = await response.json();
console.log({ agentId, runId });

import os
import requests

response = requests.post(
    "https://api.browserbase.com/v1/agents/runs",
    headers={
        "x-bb-api-key": os.environ["BROWSERBASE_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "task": "Go to Hacker News and return the top 3 stories with their titles and URLs",
    },
)

data = response.json()
print(data["agentId"], data["runId"])

Run lifecycle

Agent runs are asynchronous. Create a run, poll it until it reaches a terminal state, then read the final result and session details.

Status	Description
`PENDING`	The run is queued.
`RUNNING`	The agent is working on the task.
`COMPLETED`	The run finished successfully.
`FAILED`	The run failed.
`STOPPED`	The run was stopped by request.
`TIMED_OUT`	The run exceeded its timeout.

Built-in capabilities

Agents use the Browserbase platform out of the box:

Browser automation: navigate pages, click, type, wait, observe, and extract using Stagehand.
Search: discover relevant pages before opening a browser.
Files: read, write, and process files in the run environment.
Shell: run commands in the sandbox when code or CLIs are the fastest path.
Identity and access: use Browserbase browser settings for proxies, CAPTCHA solving, and agent identity.
Observability: inspect live sessions, recordings, replay, and run messages.

When to use Agents

Use Agents when	Use another Browserbase tool when
You want an autonomous agent to complete a web task from a natural language instruction.	You need deterministic browser control in your own code: use browser sessions.
You do not want to maintain Playwright, Stagehand, model, or runtime orchestration.	You want to deploy custom browser logic: use Functions.
You want built-in search, browsing, files, shell, and observability in one run.	You only need cheap read-only recon: use Search or Fetch.

Next steps

Agents quickstart

Create and poll your first agent run.

How it works

Learn the execution loop, built-in tools, run lifecycle, and observability.

API reference

See request and response fields for creating a run.

Agent Auth & Identity

Give agents stronger trust signals for protected websites.

Enterprise data controls

Agents is currently outside the scope of Zero Data Retention (ZDR) and Bring Your Own Storage (BYOS). Please contact us if you need to ZDR / BYOS / BYO model key.

Quickstart

How it works

Run an agent

Browser agents use case

​Overview

​Quick reference

​How it works

​Create a run

​Run lifecycle

​Built-in capabilities

​When to use Agents

​Next steps

Agents quickstart

How it works

API reference

Agent Auth & Identity

​Enterprise data controls

Overview

Quick reference

How it works

Create a run

Run lifecycle

Built-in capabilities

When to use Agents

Next steps

Enterprise data controls