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"
]

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.

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.