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

# Python SDK

> All the features and utilities for fast Python development with Browserbase.

If you're working with Python, the official `browserbase` package is the easiest way
to connect to and control headless browsers running on Browserbase.

## Installation

```bash theme={null}
pip install browserbase
```

## Basic usage

Here's an example using the Browserbase Python SDK to create and connect to a session with Playwright:

```python theme={null}
from playwright.sync_api import sync_playwright
from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

# Create a session on Browserbase
session = bb.sessions.create()

# Connect to the remote session
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp(session.connect_url)
context = browser.contexts[0]
page = context.pages[0]

page.goto("https://news.ycombinator.com/")
page.close()
browser.close()
playwright.stop()

print(f"Session complete! View recording at https://browserbase.com/sessions/{session.id}")
```

## Session configuration

Pass configuration options when creating a session to customize browser behavior.

### All configuration options

```python theme={null}
session = bb.sessions.create(
    # Project ID (optional - inferred from API key if not provided)
    project_id="your-project-id",

    # Proxy configuration
    proxies=True,  # Use default proxy

    # Region where the session runs
    region="us-west-2",

    # Keep session alive after disconnection
    keep_alive=True,

    # Session timeout in seconds (60-21600)
    timeout=3600,

    # Extension ID (uploaded via Upload Extension API)
    extension_id="ext_abc123",

    # Browser settings
    browser_settings={
        # Toggle features
        "blockAds": True,
        "solveCaptchas": True,
        "recordSession": True,
        "logSession": True,
        "verified": True,

        # Operating system (only available with verified)
        # Controls user agent and environment signals
        "os": "windows",

        # Context for session persistence
        "context": {
            "id": "my-context-id",
            "persist": True,
        },

        # Viewport configuration (ignored when verified is enabled)
        "viewport": {
            "width": 1920,
            "height": 1080,
        },

        # Custom CAPTCHA selectors
        "captchaImageSelector": "#captcha-image",
        "captchaInputSelector": "#captcha-input",
    },

    # Custom metadata for the session
    user_metadata={
        "userId": "user_123",
        "taskName": "data-extraction-job",
    },
)
```

### Proxy configuration

Configure proxies as a boolean or a list for more control:

```python theme={null}
# Using Browserbase managed proxy with geolocation
session = bb.sessions.create(
    proxies=[
        {
            "type": "browserbase",
            "geolocation": {
                "country": "US",
                "state": "CA",
                "city": "San Francisco",
            },
        },
    ],
)

# Using external proxy
session = bb.sessions.create(
    proxies=[
        {
            "type": "external",
            "server": "http://proxy.example.com:8080",
            "username": "user",
            "password": "pass",
            "domainPattern": "*.example.com",
        },
    ],
)

# Multiple proxies with domain patterns
session = bb.sessions.create(
    proxies=[
        {
            "type": "browserbase",
            "geolocation": {"country": "US"},
            "domainPattern": "*.google.com",
        },
        {
            "type": "external",
            "server": "http://proxy.example.com:8080",
            "domainPattern": "*.example.com",
        },
    ],
)
```

### Common configuration examples

```python theme={null}
# Verified with proxy
session = bb.sessions.create(
    proxies=True,
    browser_settings={
        "verified": True,
        "os": "windows",
    },
)

# Long-running session with keep-alive
session = bb.sessions.create(
    timeout=21600,  # 6 hours
    keep_alive=True,
)

# Session with context persistence
session = bb.sessions.create(
    browser_settings={
        "context": {
            "id": "user-session-context",
            "persist": True,
        },
    },
)

# Custom viewport and ad blocking
session = bb.sessions.create(
    browser_settings={
        "viewport": {"width": 1440, "height": 900},
        "blockAds": True,
    },
)

# Mobile viewport
session = bb.sessions.create(
    browser_settings={
        "viewport": {"width": 390, "height": 844},
    },
)

# Session in specific region with metadata
session = bb.sessions.create(
    region="eu-central-1",
    user_metadata={
        "jobId": "job_456",
        "environment": "production",
    },
)
```

## Agents

Use the Browserbase Python SDK to create and manage Agents and runs. For a polling workflow, see [Integrating Agents](/platform/agents/integrate-api-sdk).

### Create an Agent and run

```python theme={null}
agent = bb.agents.create(
    name="Job Finder",
    system_prompt="Find the best matching role on the company's official job board.",
    result_schema={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
        },
        "required": ["title", "url"],
    },
)

run = bb.agents.runs.create(
    agent_id=agent.agent_id,
    task="Find the best backend engineering role for %candidate%",
    variables={
        "candidate": {
            "value": "a distributed-systems engineer",
            "description": "The candidate profile to match against open roles",
        },
    },
    result_schema={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
        },
        "required": ["title", "url"],
    },
    browser_settings={
        "proxies": True,
        "verified": True,
        "context": {
            "id": "context-id",
            "persist": True,
        },
    },
)

print(run.run_id, run.status)
```

### Methods

| Method                                      | Parameters                                                                      |
| ------------------------------------------- | ------------------------------------------------------------------------------- |
| `bb.agents.create(...)`                     | `name` (required), `system_prompt`, `result_schema`                             |
| `bb.agents.retrieve(agent_id)`              | `agent_id`                                                                      |
| `bb.agents.update(agent_id, ...)`           | `agent_id`, `name`, `system_prompt`, `result_schema`                            |
| `bb.agents.list(...)`                       | `cursor`, `start_at`, `end_at`, `limit`                                         |
| `bb.agents.delete(agent_id)`                | `agent_id`                                                                      |
| `bb.agents.runs.create(...)`                | `task` (required), `agent_id`, `browser_settings`, `result_schema`, `variables` |
| `bb.agents.runs.retrieve(run_id)`           | `run_id`                                                                        |
| `bb.agents.runs.list(...)`                  | `agent_id`, `status`, `cursor`, `start_at`, `end_at`, `limit`                   |
| `bb.agents.runs.list_messages(run_id, ...)` | `run_id`, `since`, `limit`, `all`                                               |

Use `AsyncBrowserbase` for the same methods in asynchronous applications. Use the [Stop a run REST endpoint](/reference/api/stop-a-run) to stop an in-progress run.

<CardGroup cols={2}>
  <Card title="Examples" icon="github" iconType="sharp-solid" href="https://github.com/browserbase/sdk-python/tree/main/examples">
    Quickstart examples using CAPTCHA solving, proxies, extensions, and more.
  </Card>

  <Card title="PyPI package" icon="python" iconType="sharp-solid" href="https://pypi.org/project/browserbase/">
    View the package on PyPI
  </Card>

  <Card title="SDK reference" icon="book" iconType="sharp-solid" href="https://github.com/browserbase/sdk-python/blob/main/api.md">
    View the complete SDK reference documentation
  </Card>
</CardGroup>