Browser Agent Python SDK

A powerful & efficient browser agent that automates any task on the web.

Getting started

Requires Python 3.11 or newer, Chrome or a compatible Chromium installation, and a provider API key unless using vllm or codex. Codex additionally requires the Codex CLI on PATH.

pip install browser-agent-python-sdk

The distribution is named browser-agent-python-sdk; import it as browser_agent.

The SDK downloads the matching Browser Agent CLI from its GitHub Release on first use, verifies its SHA-256 checksum, and reuses it from the user cache. Set BROWSER_AGENT_CLI_PATH to a preinstalled CLI executable for offline environments, or BROWSER_AGENT_CLI_CACHE_DIR to choose the managed cache location.

from browser_agent import BrowserAgent, BrowserAgentTask

agent = BrowserAgent(
    provider="openai",
    model="gpt-5.4",
    download_directory="./downloads",
)

task = BrowserAgentTask(
    task="Find the first five articles on the OpenAI blog.",
    url="https://openai.com/news/",
)

Agent configuration

All BrowserAgent constructor arguments are keyword-only.

Providers and reasoning

Provider: TypeAlias = Literal[
    "openai", "vllm", "together", "anthropic", "google", "codex", "openrouter"
]

ReasoningEffort: TypeAlias = Literal[
    "none", "minimal", "low", "medium", "high", "xhigh", "max", "enabled"
]

ValidatorLifecycleMode: TypeAlias = Literal["retry", "disabled"]

vllm additionally requires endpoint_url. Codex rejects api_key and endpoint_url; it always uses the Codex CLI login and fixed ChatGPT backend.

Install the Codex CLI with npm install -g @openai/codex, then configure the agent without an API key:

agent = BrowserAgent(
    provider="codex",
    model="gpt-5.6-luna",
    reasoning_effort="xhigh",
    download_directory="./downloads",
)

Before launching several Codex-backed runs concurrently, perform one login gate and relay its status messages:

from browser_agent import ensure_codex_login

await ensure_codex_login(on_log=lambda entry: print(entry.message))

To check the same stored session without starting OAuth:

from browser_agent import check_codex_login

if not await check_codex_login():
    raise RuntimeError("Run the interactive login command first")

If the user is not logged in, the SDK forwards the CLI's OAuth URL through the existing on_log stderr events. Open the URL and complete login; the callback resumes the run. PATH and CODEX_HOME are preserved for the child process. Codex requests use https://chatgpt.com/backend-api/codex/responses, a private, unstable backend contract that may change without notice.

The SDK applies the selected model, endpoint, reasoning effort, and prompt budget to every execution stage. Target-URL discovery uses none reasoning. The default runtime profile enables checklist and whole-context extraction with full retry verification, and disables workflow orchestration, incremental DOM history, cookie dismissal and pre-step screenshots.

For OpenRouter, use its organization-prefixed model ID and provide an explicit reasoning effort:

agent = BrowserAgent(
    provider="openrouter",
    model="z-ai/glm-5.2",
    reasoning_effort="xhigh",
    openrouter_provider="baseten/fp8",
    download_directory="./downloads",
)

openrouter_provider is valid only with provider="openrouter". It restricts OpenRouter routing to that provider and disables fallbacks. Exact endpoint IDs such as baseten/fp8 are passed through unchanged.

Custom tools

Use BrowserAgentCustomTool to give the agent trusted JavaScript functions that run in the browser-agent CLI host. Each tool receives one runtime object and may return any JSON-serializable value. Its argument schema must be a JSON Schema Draft 2020-12 object schema.

from browser_agent import BrowserAgent, BrowserAgentCustomTool

agent = BrowserAgent(
    provider="openai",
    model="gpt-5.4",
    download_directory="./downloads",
    custom_tools=(
        BrowserAgentCustomTool(
            name="read_heading",
            description="Read the text of a heading selected by CSS.",
            arguments={
                "type": "object",
                "properties": {"selector": {"type": "string"}},
                "required": ["selector"],
                "additionalProperties": False,
            },
            javascript="""async ({ args, cdp }) => {
                const { result } = await cdp.Runtime.evaluate({
                    expression: `document.querySelector(${JSON.stringify(args.selector)})?.textContent ?? null`,
                    returnByValue: true,
                });
                return result.value;
            }""",
        ),
    ),
)

Names must match ^[a-z][a-z0-9_]{0,63}$ and cannot duplicate another custom tool or a built-in tool. Definitions are sent only in the initial run request; when the sequence is empty, the request and agent system prompt are unchanged. JavaScript source is not placed in temporary config files or shown to the model. The runtime object contains validated args, the current active-target cdp client, memory_read(), memory_write(content), memory_result_write([{link, summary}, ...]), and terminal return_results(items?). Direct page globals are unavailable; use CDP Runtime methods for page JavaScript. No filesystem or workspace binding is provided. Do not pass untrusted source.

Task configuration

@dataclass(frozen=True, slots=True)
class BrowserAgentTask:
    task: str
    url: str | None = None
    credentials: Sequence[BrowserAgentCredential] = ()


@dataclass(frozen=True, slots=True)
class BrowserAgentCredential:
    username: str
    password: str
    domain: str

Credentials are login details for a website the task may need to access. They are distinct from api_key, which authenticates with the model provider. Each credential contains:

import os

from browser_agent import BrowserAgentCredential, BrowserAgentTask

task = BrowserAgentTask(
    task="Open my account.",
    url="https://example.com",
    credentials=(
        BrowserAgentCredential(
            username="person@example.com",
            password=os.environ["EXAMPLE_PASSWORD"],
            domain="https://example.com",
        ),
    ),
)

BrowserAgent.run() accepts one BrowserAgentTask or a non-empty sequence of tasks.