browsa (Python)
Real browsers for AI agents: the official Python SDK for browsa.io.
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
- API reference: https://browsa.io/docs
- Docs: https://browsa.io/docs
- Support: mailto:support@browsa.io
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.