Skip to main content

Browsa

browsa (Python)

Real browsers for AI agents: the official Python SDK for browsa.io.

PyPI version Python

Install

pip install browsa

Zero dependencies. Pure stdlib. Single-file wheel.

Five-line hello world

from browsa import Client

c = Client(api_key="agt_live_...")
job = c.run_task(
    task="Go to news.ycombinator.com and return the top story title.",
    llm="claude-opus-5-5",
    llm_api_key="sk-ant-...",
)
print(job.final_result)
print("watch live:", job.live_url)

That runs a real Chromium fork (Phantom, our real browser) inside an isolated burner session, driven by browser-use + Claude Opus. The agent navigates, extracts, and returns. A live noVNC stream URL is available the moment the burner spawns.

Saved LLM keys

Save your LLM provider key once in the workspace (dashboard: https://app.browsa.io/dashboard/llm-keys, or the API) and tasks use it without the secret in your code:

import os

key = c.create_llm_key("anthropic", os.environ["ANTHROPIC_API_KEY"], name="Prod Anthropic")
print(key.id, key.masked, key.status)        # 3f6c...  sk-ant-…a1b2  valid

# The first key of a provider becomes its default, so this needs no key at all:
job = c.run_task(task="Return the title of example.com")

# Or pick a saved key by id (also on create_task, create_schedule and auto):
job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)

Which key a task uses, first match wins: llm_api_key (per task), then llm_key_id, then the workspace's default saved key for the provider of llm (with llm omitted: the first default in the order anthropic, openai, google), then llm="browsa" (Browsa's hosted model).

Method Endpoint
create_llm_key(provider, api_key, *, name=None, base_url=None, default=None) POST /v1/llm-keys
list_llm_keys() GET /v1/llm-keys
get_llm_key(llm_key_id) GET /v1/llm-keys/{id}
validate_llm_key(llm_key_id) POST /v1/llm-keys/{id}/validate
rotate_llm_key(llm_key_id, api_key, *, base_url=None) POST /v1/llm-keys/{id}/rotate
update_llm_key(llm_key_id, *, name=None, default=None) POST /v1/llm-keys/{id}
delete_llm_key(llm_key_id) DELETE /v1/llm-keys/{id}

Providers: anthropic, openai, google, openai_compatible (needs base_url). Each returns an LLMKey (or nothing, for delete). The API never returns the secret, only masked (prefix + last 4). Keys are checked with a free model-list call when saved or rotated; an invalid key raises APIError with code LLM_KEY_INVALID and nothing changes. Rotating keeps the id, so schedules and queued runs pick up the new secret. Jobs show llm_key_id, llm_key_masked and llm_key_source ("saved" or "default").

Async

import asyncio
from browsa import AsyncClient

async def main():
    async with AsyncClient(api_key="agt_live_...") as c:
        job = await c.run_task(
            task="Scrape the top 5 products on producthunt.com today.",
            llm="claude-opus-5-5",
            llm_api_key="sk-ant-...",
            country="US",
        )
        print(job.final_result)

asyncio.run(main())

Webhooks

from browsa import webhooks

# In your receiver (Flask/FastAPI/whatever):
ok = webhooks.verify_signature(
    body=raw_request_body,
    header=request.headers["X-Agents-Signature"],
    secret=os.environ["BROWSA_WEBHOOK_SECRET"],  # hex-encoded
)
if not ok:
    return 401
# Trust the payload only after this point.

What you get

Capability Notes
Sync + async clients Client + AsyncClient, same surface
Real Job envelope Typed dataclass + .raw escape hatch
Long-poll waits wait_for_job(timeout=...) uses server-side ?wait=30
Live step events for ev in client.stream_job_events(job_id, after=0); resume with after=<last n>
Webhook signature verify HMAC-SHA256, constant-time compare, skew check
Canonical error envelope AuthError, InvalidIDError, RateLimitError, etc.
X-Request-Id propagation Every error carries the server's request id
Zero deps Single wheel, audit-friendly, no transitive surface

Advanced

Long-running tasks with progress callback

def show(job):
    print(f"  step {job.step_count}/{job.progress_total}  status={job.status}")

job = c.run_task(
    task="Open-ended research: scrape arxiv for papers on test-time compute, return top 10 by citation.",
    llm="claude-opus-5-5",
    llm_api_key="sk-ant-...",
    max_steps=80,
    on_progress=show,
)

Interactive (input_required) tasks

If your task can pause for human input (captcha, decision point), watch for status input_required and respond:

job = c.create_task(task="...", llm="...", llm_api_key="...")
while not job.is_terminal:
    job = c.get_job(job.id, wait=30)
    if job.status == "input_required":
        answer = input(f"Agent asks: {job.input_question}\n> ")
        job = c.respond_to_job(job.id, answer)

Sessions: follow-up messages on the same browser

Start a task with create_session and the browser stays up after it ends (15 minutes by default, browser_ttl_seconds up to 3600), so you can send follow-ups that continue on the same page. A follow-up pays no new browser, only the task's base and step credits.

s = c.create_session("Go to example.com and return the H1.", llm="browsa")
first = c.wait_for_job(s.id)
print(first.final_result)

turn = c.run_message(s.session_id, "Now open the Learn more link and tell me its URL and H1")
print(turn.final_result)

session = c.get_session(s.session_id)
print(session.status, session.browser.expires_in_seconds, [t.final_result for t in session.turns])
c.stop_session(s.session_id)

send_message returns the new turn's Job right away (use run_message to wait). Model fields you leave out reuse the previous turn's model, but a BYOK llm_api_key must be sent again on every message. A closed browser raises APIError with code == "BROWSER_EXPIRED"; a turn still running raises code == "SESSION_BUSY".

JA3-spoofed sessions

Some sites fingerprint TLS handshake shape. Set a profile to spoof macOS Chrome:

job = c.run_task(
    task="Go to a TLS-fingerprint-fingerprinted site",
    llm="claude-opus-5-5", llm_api_key="sk-...",
    ja3_profile="macos_chrome_137",  # uses utls
)

Docs

License

MIT.

Metadata

Release files for browsa 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for browsa 0.2.0
File Size Uploaded Provenance Actions
browsa-0.2.0.tar.gz 35.5 kB Without provenance Details for browsa-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for browsa 0.2.0
File Interpreter ABI Platform Actions
browsa-0.2.0-py3-none-any.whl Python 3 none any Details for browsa-0.2.0-py3-none-any.whl

Total release size: 62.9 kB

Release files / browsa-0.2.0.tar.gz

Download URL browsa-0.2.0.tar.gz
Size 35.5 kB
Tags Source
SHA-256 checksum
How to use checksums
249df36a31b9197500c8642d660af8c5d8d05d129d3aabdb492e0fc1b0204b6d
BLAKE2b-256 checksum
How to use checksums
570f381fe2562a4ee85ec86c7f647c0315f7b06bf41710733030e2f122edf273
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.2

Release files / browsa-0.2.0-py3-none-any.whl

Download URL browsa-0.2.0-py3-none-any.whl
Size 27.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2bd9243215a3602e80e4171043c8edeb5590cc16ec9e5229a48ec3014c6f78a7
BLAKE2b-256 checksum
How to use checksums
ef3a8f6c3b8ab2159d817dd2734d9b27d911f06ca205349ead1b0e5197330930
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.2

Security for browsa 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page