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

# Agents

> Run autonomous browser agents on Browserbase with one API call.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" iconType="sharp-solid" href="/welcome/quickstarts/agents">
    Create your first agent run and poll for the result.
  </Card>

  <Card title="How it works" icon="gear" iconType="sharp-solid" href="/platform/agents/how-it-works">
    Learn how agents work, what tools they use, and how runs progress.
  </Card>

  <Card title="Run an agent" icon="terminal" iconType="sharp-solid" href="/reference/api/run-an-agent">
    Endpoint reference for starting an agent run.
  </Card>

  <Card title="Browser agents use case" icon="book" iconType="sharp-solid" href="/use-cases/agents">
    Understand when to use Agents versus building a custom browser-agent loop.
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="Send a task">
    Create a run with a natural language instruction and optional browser settings.
  </Step>

  <Step title="Browserbase starts the agent">
    Browserbase creates the browser session, runtime, tools, and model loop needed to complete the task.
  </Step>

  <Step title="The agent completes the run">
    The agent chooses the right tools, navigates the web, interacts with pages, and extracts the requested result.
  </Step>

  <Step title="Inspect the outcome">
    Poll the run, read its messages, and review the browser session when you need to debug.
  </Step>
</Steps>

## Create a run

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

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    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 });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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"])
    ```
  </Tab>
</Tabs>

## 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](/platform/browser/getting-started/create-browser-session). |
| You do not want to maintain Playwright, Stagehand, model, or runtime orchestration.      | You want to deploy custom browser logic: use [Functions](/platform/runtime/overview).                                                      |
| You want built-in search, browsing, files, shell, and observability in one run.          | You only need cheap read-only recon: use [Search](/platform/search/overview) or [Fetch](/platform/fetch/overview).                         |

## Next steps

<CardGroup cols={2}>
  <Card title="Agents quickstart" icon="rocket" iconType="sharp-solid" href="/welcome/quickstarts/agents">
    Create and poll your first agent run.
  </Card>

  <Card title="How it works" icon="gear" iconType="sharp-solid" href="/platform/agents/how-it-works">
    Learn the execution loop, built-in tools, run lifecycle, and observability.
  </Card>

  <Card title="API reference" icon="terminal" iconType="sharp-solid" href="/reference/api/run-an-agent">
    See request and response fields for creating a run.
  </Card>

  <Card title="Agent Auth & Identity" icon="shield-check" iconType="sharp-solid" href="/platform/identity/overview">
    Give agents stronger trust signals for protected websites.
  </Card>
</CardGroup>

## Enterprise data controls

<Warning>
  Agents is currently outside the scope of [Zero Data Retention (ZDR)](/account/enterprise/zero-data-retention) and [Bring Your Own Storage (BYOS)](/account/enterprise/byos-setup-guide). Please [contact us](https://www.browserbase.com/contact) if you need to ZDR / BYOS / BYO model key.
</Warning>