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="browsa",
    on_progress=lambda j: j.live_url and print("watch live:", j.live_url),
)
print(job.outcome, job.final_result)

That runs Phantom, our Chromium build, in a temporary cloud browser, driven by Browsa's hosted model: no LLM key needed. To use your own model instead, pass llm="anthropic:claude-sonnet-5-5" with llm_api_key, or save the key once (below).

job.status says the run ended; job.outcome says how. outcome == "failed" with status == "completed" means the agent finished but could not do the task, and final_result says what stopped it.

live_url is a Phantom Live link to watch the browser. It exists only while the task runs (so read it in on_progress or from create_task), and each link opens once.

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 a hosted tier such as llm="browsa" (see Models).

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").

Models

A task runs on one of Browsa's hosted tiers, or on any provider model with your own key.

llm What it is
"browsa" The default hosted model
"browsa-fast" Fastest and lightest
"browsa-smart" For harder tasks
anything else, e.g. "anthropic:claude-sonnet-5-5" A provider model, run with your own key (llm_api_key, llm_key_id or the workspace default)

Hosted tiers need no LLM key and add a flat number of credits per task. Which model each tier runs on, and what it costs, are server settings that can change, so read them from models() (free, read-only) instead of hardcoding them:

m = c.models()
for tier in m.hosted:
    print(tier.id, tier.model, tier.reasoning, tier.credits_per_task, tier.default)
print(m.own_key.providers, m.own_key.default_models)

reasoning sets how much the model reasons: "low", "medium" or "high". Leave it out for the tier's or the provider's default. It is accepted by create_task, run_task, create_session, send_message, run_message and create_schedule; the API answers 400 for any other value.

job = c.run_task(
    task="Go to news.ycombinator.com and return the top story title.",
    llm="browsa-smart",
    reasoning="high",
)
print(job.final_result)
print(job.llm_tier, job.reasoning)          # browsa-smart high
if job.usage:
    print(job.usage.input_tokens, job.usage.output_tokens, job.usage.requests)
print(job.llm_cost_usd)                     # None for hosted runs

A finished job has usage (input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, requests), llm_cost_usd, llm_tier and reasoning (the level that was applied). llm_cost_usd is an estimate from public list prices for runs with your own key; it is None when unknown and always None for hosted runs, which are paid in credits. All four are None on jobs that do not have them, such as jobs run before these fields existed.

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
Hosted tiers + reasoning llm="browsa" / "browsa-fast" / "browsa-smart", reasoning=, models(), job.usage
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, TimeoutError, etc.; every one is a BrowsaError
Typed Ships py.typed; works with mypy --strict and pyright
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
)

Observe and act (no Playwright)

Read a running browser's page as compact text with element ids, then act on the ids. Each act returns what changed, not the whole page.

b = c.create_agent(ttl="10m")
c.act(b["id"], "navigate", url="https://example.com/login")
view = c.observe(b["id"])
print(view["text"])                        # [3] textbox "Email"  empty …
r = c.act(b["id"], "type", id=3, text="ada@example.com")
print(r["status"], r["text"])              # ok  ~ [3] textbox "Email"  value "ada@example.com"
c.act(b["id"], "click", role="button", name="Sign in")

status is ok, failed, blocked, challenge or stale; none of them raises. stale means the ids came from a view the server no longer has (ids_reset is true): nothing was done and text carries a new view. Both calls are free. Format and actions: https://browsa.io/docs#agents-observe.

Downloads and Phantom Live

Files a browser downloads are kept with the browser, not on your machine, so Playwright's download.save_as() cannot reach them. List and fetch them through the API before you stop the browser:

files = c.list_downloads(b["id"])                   # [{"name", "size", "modified_at"}]
data = c.download_file(b["id"], files[0]["name"])   # bytes

With Playwright the name is the last part of download.path().

create_live_link gives a link that shows a running browser in any web browser, to watch or to take over:

link = c.create_live_link(b["id"], scope="control", ttl_seconds=600)
print(link["live_url"])                             # opens once; make one per person

scope is "view" (default) or "control". Both calls are free.

Docs

License

MIT.

Metadata

Release files for browsa 0.3.1

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.3.1
File Size Uploaded Provenance Actions
browsa-0.3.1.tar.gz 49.1 kB Without provenance Details for browsa-0.3.1.tar.gz

Built distribution (wheel)

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

Total release size: 84.6 kB

Release files / browsa-0.3.1.tar.gz

Download URL browsa-0.3.1.tar.gz
Size 49.1 kB
Tags Source
SHA-256 checksum
How to use checksums
27ffddb20d6c69d0ceb3017fc00fc5248f610a5142850eef7c2e266881f15d3a
BLAKE2b-256 checksum
How to use checksums
6ff85ef7c8015ff5074b1e131e705efea141789e943786d0a4ad134fc06eca4f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.8

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

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

Security for browsa 0.3.1

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