browsa 0.1.3__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {browsa-0.1.3 → browsa-0.3.0}/LICENSE +1 -1
- browsa-0.3.0/PKG-INFO +270 -0
- browsa-0.3.0/README.md +239 -0
- {browsa-0.1.3 → browsa-0.3.0}/browsa/__init__.py +24 -7
- browsa-0.3.0/browsa/_version.py +1 -0
- browsa-0.3.0/browsa/client.py +1476 -0
- {browsa-0.1.3 → browsa-0.3.0}/browsa/errors.py +0 -6
- browsa-0.3.0/browsa/types.py +601 -0
- browsa-0.3.0/browsa.egg-info/PKG-INFO +270 -0
- {browsa-0.1.3 → browsa-0.3.0}/pyproject.toml +6 -5
- browsa-0.3.0/tests/test_unit.py +967 -0
- browsa-0.1.3/PKG-INFO +0 -160
- browsa-0.1.3/README.md +0 -130
- browsa-0.1.3/browsa/_version.py +0 -1
- browsa-0.1.3/browsa/client.py +0 -753
- browsa-0.1.3/browsa/types.py +0 -111
- browsa-0.1.3/browsa.egg-info/PKG-INFO +0 -160
- browsa-0.1.3/tests/test_unit.py +0 -124
- {browsa-0.1.3 → browsa-0.3.0}/browsa/webhooks.py +0 -0
- {browsa-0.1.3 → browsa-0.3.0}/browsa.egg-info/SOURCES.txt +0 -0
- {browsa-0.1.3 → browsa-0.3.0}/browsa.egg-info/dependency_links.txt +0 -0
- {browsa-0.1.3 → browsa-0.3.0}/browsa.egg-info/requires.txt +0 -0
- {browsa-0.1.3 → browsa-0.3.0}/browsa.egg-info/top_level.txt +0 -0
- {browsa-0.1.3 → browsa-0.3.0}/setup.cfg +0 -0
- {browsa-0.1.3 → browsa-0.3.0}/tests/test_live.py +0 -0
browsa-0.3.0/PKG-INFO
ADDED
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: browsa
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Official Python SDK for Browsa: real cloud browsers for AI agents (browsa.io)
|
|
5
|
+
Author-email: Browsa <support@browsa.io>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://browsa.io
|
|
8
|
+
Project-URL: Documentation, https://browsa.io/docs
|
|
9
|
+
Project-URL: Source, https://github.com/browsa-io/browsa/tree/main/browsa-python
|
|
10
|
+
Project-URL: Issues, https://github.com/browsa-io/browsa/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/browsa-io/browsa/releases
|
|
12
|
+
Keywords: browser-automation,ai-agents,browser-use,real-browser,scraping,playwright
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
|
|
22
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
23
|
+
Requires-Python: >=3.9
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
28
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
|
|
29
|
+
Requires-Dist: ruff>=0.1; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<a href="https://browsa.io"><img src="https://browsa.io/browsa-logo-lockup.png" alt="Browsa" width="340"></a>
|
|
34
|
+
</p>
|
|
35
|
+
|
|
36
|
+
# browsa (Python)
|
|
37
|
+
|
|
38
|
+
Real browsers for AI agents: the official Python SDK for [browsa.io](https://browsa.io).
|
|
39
|
+
|
|
40
|
+
[](https://pypi.org/project/browsa/)
|
|
41
|
+
[](https://pypi.org/project/browsa/)
|
|
42
|
+
|
|
43
|
+
## Install
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
pip install browsa
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Zero dependencies. Pure stdlib. Single-file wheel.
|
|
50
|
+
|
|
51
|
+
## Five-line hello world
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
from browsa import Client
|
|
55
|
+
|
|
56
|
+
c = Client(api_key="agt_live_...")
|
|
57
|
+
job = c.run_task(
|
|
58
|
+
task="Go to news.ycombinator.com and return the top story title.",
|
|
59
|
+
llm="claude-opus-5-5",
|
|
60
|
+
llm_api_key="sk-ant-...",
|
|
61
|
+
)
|
|
62
|
+
print(job.final_result)
|
|
63
|
+
print("watch live:", job.live_url)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
That runs a real Chromium fork (Phantom, our real browser) inside an isolated burner session, driven by [browser-use](https://browser-use.com) + Claude Opus. The agent navigates, extracts, and returns. A live noVNC stream URL is available the moment the burner spawns.
|
|
67
|
+
|
|
68
|
+
## Saved LLM keys
|
|
69
|
+
|
|
70
|
+
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:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
import os
|
|
74
|
+
|
|
75
|
+
key = c.create_llm_key("anthropic", os.environ["ANTHROPIC_API_KEY"], name="Prod Anthropic")
|
|
76
|
+
print(key.id, key.masked, key.status) # 3f6c... sk-ant-…a1b2 valid
|
|
77
|
+
|
|
78
|
+
# The first key of a provider becomes its default, so this needs no key at all:
|
|
79
|
+
job = c.run_task(task="Return the title of example.com")
|
|
80
|
+
|
|
81
|
+
# Or pick a saved key by id (also on create_task, create_schedule and auto):
|
|
82
|
+
job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
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](#models)).
|
|
86
|
+
|
|
87
|
+
| Method | Endpoint |
|
|
88
|
+
|---|---|
|
|
89
|
+
| `create_llm_key(provider, api_key, *, name=None, base_url=None, default=None)` | `POST /v1/llm-keys` |
|
|
90
|
+
| `list_llm_keys()` | `GET /v1/llm-keys` |
|
|
91
|
+
| `get_llm_key(llm_key_id)` | `GET /v1/llm-keys/{id}` |
|
|
92
|
+
| `validate_llm_key(llm_key_id)` | `POST /v1/llm-keys/{id}/validate` |
|
|
93
|
+
| `rotate_llm_key(llm_key_id, api_key, *, base_url=None)` | `POST /v1/llm-keys/{id}/rotate` |
|
|
94
|
+
| `update_llm_key(llm_key_id, *, name=None, default=None)` | `POST /v1/llm-keys/{id}` |
|
|
95
|
+
| `delete_llm_key(llm_key_id)` | `DELETE /v1/llm-keys/{id}` |
|
|
96
|
+
|
|
97
|
+
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"`).
|
|
98
|
+
|
|
99
|
+
## Models
|
|
100
|
+
|
|
101
|
+
A task runs on one of Browsa's hosted tiers, or on any provider model with your own key.
|
|
102
|
+
|
|
103
|
+
| `llm` | What it is |
|
|
104
|
+
|---|---|
|
|
105
|
+
| `"browsa"` | The default hosted model |
|
|
106
|
+
| `"browsa-fast"` | Fastest and lightest |
|
|
107
|
+
| `"browsa-smart"` | For harder tasks |
|
|
108
|
+
| 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) |
|
|
109
|
+
|
|
110
|
+
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:
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
m = c.models()
|
|
114
|
+
for tier in m.hosted:
|
|
115
|
+
print(tier.id, tier.model, tier.reasoning, tier.credits_per_task, tier.default)
|
|
116
|
+
print(m.own_key.providers, m.own_key.default_models)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
`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.
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
job = c.run_task(
|
|
123
|
+
task="Go to news.ycombinator.com and return the top story title.",
|
|
124
|
+
llm="browsa-smart",
|
|
125
|
+
reasoning="high",
|
|
126
|
+
)
|
|
127
|
+
print(job.final_result)
|
|
128
|
+
print(job.llm_tier, job.reasoning) # browsa-smart high
|
|
129
|
+
if job.usage:
|
|
130
|
+
print(job.usage.input_tokens, job.usage.output_tokens, job.usage.requests)
|
|
131
|
+
print(job.llm_cost_usd) # None for hosted runs
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
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.
|
|
135
|
+
|
|
136
|
+
## Async
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
import asyncio
|
|
140
|
+
from browsa import AsyncClient
|
|
141
|
+
|
|
142
|
+
async def main():
|
|
143
|
+
async with AsyncClient(api_key="agt_live_...") as c:
|
|
144
|
+
job = await c.run_task(
|
|
145
|
+
task="Scrape the top 5 products on producthunt.com today.",
|
|
146
|
+
llm="claude-opus-5-5",
|
|
147
|
+
llm_api_key="sk-ant-...",
|
|
148
|
+
country="US",
|
|
149
|
+
)
|
|
150
|
+
print(job.final_result)
|
|
151
|
+
|
|
152
|
+
asyncio.run(main())
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Webhooks
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
from browsa import webhooks
|
|
159
|
+
|
|
160
|
+
# In your receiver (Flask/FastAPI/whatever):
|
|
161
|
+
ok = webhooks.verify_signature(
|
|
162
|
+
body=raw_request_body,
|
|
163
|
+
header=request.headers["X-Agents-Signature"],
|
|
164
|
+
secret=os.environ["BROWSA_WEBHOOK_SECRET"], # hex-encoded
|
|
165
|
+
)
|
|
166
|
+
if not ok:
|
|
167
|
+
return 401
|
|
168
|
+
# Trust the payload only after this point.
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## What you get
|
|
172
|
+
|
|
173
|
+
| Capability | Notes |
|
|
174
|
+
|---|---|
|
|
175
|
+
| Sync + async clients | `Client` + `AsyncClient`, same surface |
|
|
176
|
+
| Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
|
|
177
|
+
| Hosted tiers + reasoning | `llm="browsa" / "browsa-fast" / "browsa-smart"`, `reasoning=`, `models()`, `job.usage` |
|
|
178
|
+
| Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
|
|
179
|
+
| Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
|
|
180
|
+
| Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
|
|
181
|
+
| Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc. |
|
|
182
|
+
| `X-Request-Id` propagation | Every error carries the server's request id |
|
|
183
|
+
| Zero deps | Single wheel, audit-friendly, no transitive surface |
|
|
184
|
+
|
|
185
|
+
## Advanced
|
|
186
|
+
|
|
187
|
+
### Long-running tasks with progress callback
|
|
188
|
+
|
|
189
|
+
```python
|
|
190
|
+
def show(job):
|
|
191
|
+
print(f" step {job.step_count}/{job.progress_total} status={job.status}")
|
|
192
|
+
|
|
193
|
+
job = c.run_task(
|
|
194
|
+
task="Open-ended research: scrape arxiv for papers on test-time compute, return top 10 by citation.",
|
|
195
|
+
llm="claude-opus-5-5",
|
|
196
|
+
llm_api_key="sk-ant-...",
|
|
197
|
+
max_steps=80,
|
|
198
|
+
on_progress=show,
|
|
199
|
+
)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Interactive (input_required) tasks
|
|
203
|
+
|
|
204
|
+
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
|
|
205
|
+
|
|
206
|
+
```python
|
|
207
|
+
job = c.create_task(task="...", llm="...", llm_api_key="...")
|
|
208
|
+
while not job.is_terminal:
|
|
209
|
+
job = c.get_job(job.id, wait=30)
|
|
210
|
+
if job.status == "input_required":
|
|
211
|
+
answer = input(f"Agent asks: {job.input_question}\n> ")
|
|
212
|
+
job = c.respond_to_job(job.id, answer)
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### Sessions: follow-up messages on the same browser
|
|
216
|
+
|
|
217
|
+
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.
|
|
218
|
+
|
|
219
|
+
```python
|
|
220
|
+
s = c.create_session("Go to example.com and return the H1.", llm="browsa")
|
|
221
|
+
first = c.wait_for_job(s.id)
|
|
222
|
+
print(first.final_result)
|
|
223
|
+
|
|
224
|
+
turn = c.run_message(s.session_id, "Now open the Learn more link and tell me its URL and H1")
|
|
225
|
+
print(turn.final_result)
|
|
226
|
+
|
|
227
|
+
session = c.get_session(s.session_id)
|
|
228
|
+
print(session.status, session.browser.expires_in_seconds, [t.final_result for t in session.turns])
|
|
229
|
+
c.stop_session(s.session_id)
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
`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"`.
|
|
233
|
+
|
|
234
|
+
### JA3-spoofed sessions
|
|
235
|
+
|
|
236
|
+
Some sites fingerprint TLS handshake shape. Set a profile to spoof macOS Chrome:
|
|
237
|
+
|
|
238
|
+
```python
|
|
239
|
+
job = c.run_task(
|
|
240
|
+
task="Go to a TLS-fingerprint-fingerprinted site",
|
|
241
|
+
llm="claude-opus-5-5", llm_api_key="sk-...",
|
|
242
|
+
ja3_profile="macos_chrome_137", # uses utls
|
|
243
|
+
)
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### Observe and act (no Playwright)
|
|
247
|
+
|
|
248
|
+
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.
|
|
249
|
+
|
|
250
|
+
```python
|
|
251
|
+
b = c.create_agent(ttl="10m")
|
|
252
|
+
c.act(b["id"], "navigate", url="https://example.com/login")
|
|
253
|
+
view = c.observe(b["id"])
|
|
254
|
+
print(view["text"]) # [3] textbox "Email" empty …
|
|
255
|
+
r = c.act(b["id"], "type", id=3, text="ada@example.com")
|
|
256
|
+
print(r["status"], r["text"]) # ok ~ [3] textbox "Email" value "ada@example.com"
|
|
257
|
+
c.act(b["id"], "click", role="button", name="Sign in")
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
`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>.
|
|
261
|
+
|
|
262
|
+
## Docs
|
|
263
|
+
|
|
264
|
+
- API reference: <https://browsa.io/docs>
|
|
265
|
+
- Docs: <https://browsa.io/docs>
|
|
266
|
+
- Support: <mailto:support@browsa.io>
|
|
267
|
+
|
|
268
|
+
## License
|
|
269
|
+
|
|
270
|
+
MIT.
|
browsa-0.3.0/README.md
ADDED
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://browsa.io"><img src="https://browsa.io/browsa-logo-lockup.png" alt="Browsa" width="340"></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# browsa (Python)
|
|
6
|
+
|
|
7
|
+
Real browsers for AI agents: the official Python SDK for [browsa.io](https://browsa.io).
|
|
8
|
+
|
|
9
|
+
[](https://pypi.org/project/browsa/)
|
|
10
|
+
[](https://pypi.org/project/browsa/)
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pip install browsa
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Zero dependencies. Pure stdlib. Single-file wheel.
|
|
19
|
+
|
|
20
|
+
## Five-line hello world
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
from browsa import Client
|
|
24
|
+
|
|
25
|
+
c = Client(api_key="agt_live_...")
|
|
26
|
+
job = c.run_task(
|
|
27
|
+
task="Go to news.ycombinator.com and return the top story title.",
|
|
28
|
+
llm="claude-opus-5-5",
|
|
29
|
+
llm_api_key="sk-ant-...",
|
|
30
|
+
)
|
|
31
|
+
print(job.final_result)
|
|
32
|
+
print("watch live:", job.live_url)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
That runs a real Chromium fork (Phantom, our real browser) inside an isolated burner session, driven by [browser-use](https://browser-use.com) + Claude Opus. The agent navigates, extracts, and returns. A live noVNC stream URL is available the moment the burner spawns.
|
|
36
|
+
|
|
37
|
+
## Saved LLM keys
|
|
38
|
+
|
|
39
|
+
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:
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import os
|
|
43
|
+
|
|
44
|
+
key = c.create_llm_key("anthropic", os.environ["ANTHROPIC_API_KEY"], name="Prod Anthropic")
|
|
45
|
+
print(key.id, key.masked, key.status) # 3f6c... sk-ant-…a1b2 valid
|
|
46
|
+
|
|
47
|
+
# The first key of a provider becomes its default, so this needs no key at all:
|
|
48
|
+
job = c.run_task(task="Return the title of example.com")
|
|
49
|
+
|
|
50
|
+
# Or pick a saved key by id (also on create_task, create_schedule and auto):
|
|
51
|
+
job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
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](#models)).
|
|
55
|
+
|
|
56
|
+
| Method | Endpoint |
|
|
57
|
+
|---|---|
|
|
58
|
+
| `create_llm_key(provider, api_key, *, name=None, base_url=None, default=None)` | `POST /v1/llm-keys` |
|
|
59
|
+
| `list_llm_keys()` | `GET /v1/llm-keys` |
|
|
60
|
+
| `get_llm_key(llm_key_id)` | `GET /v1/llm-keys/{id}` |
|
|
61
|
+
| `validate_llm_key(llm_key_id)` | `POST /v1/llm-keys/{id}/validate` |
|
|
62
|
+
| `rotate_llm_key(llm_key_id, api_key, *, base_url=None)` | `POST /v1/llm-keys/{id}/rotate` |
|
|
63
|
+
| `update_llm_key(llm_key_id, *, name=None, default=None)` | `POST /v1/llm-keys/{id}` |
|
|
64
|
+
| `delete_llm_key(llm_key_id)` | `DELETE /v1/llm-keys/{id}` |
|
|
65
|
+
|
|
66
|
+
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"`).
|
|
67
|
+
|
|
68
|
+
## Models
|
|
69
|
+
|
|
70
|
+
A task runs on one of Browsa's hosted tiers, or on any provider model with your own key.
|
|
71
|
+
|
|
72
|
+
| `llm` | What it is |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `"browsa"` | The default hosted model |
|
|
75
|
+
| `"browsa-fast"` | Fastest and lightest |
|
|
76
|
+
| `"browsa-smart"` | For harder tasks |
|
|
77
|
+
| 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) |
|
|
78
|
+
|
|
79
|
+
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:
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
m = c.models()
|
|
83
|
+
for tier in m.hosted:
|
|
84
|
+
print(tier.id, tier.model, tier.reasoning, tier.credits_per_task, tier.default)
|
|
85
|
+
print(m.own_key.providers, m.own_key.default_models)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`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.
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
job = c.run_task(
|
|
92
|
+
task="Go to news.ycombinator.com and return the top story title.",
|
|
93
|
+
llm="browsa-smart",
|
|
94
|
+
reasoning="high",
|
|
95
|
+
)
|
|
96
|
+
print(job.final_result)
|
|
97
|
+
print(job.llm_tier, job.reasoning) # browsa-smart high
|
|
98
|
+
if job.usage:
|
|
99
|
+
print(job.usage.input_tokens, job.usage.output_tokens, job.usage.requests)
|
|
100
|
+
print(job.llm_cost_usd) # None for hosted runs
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
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.
|
|
104
|
+
|
|
105
|
+
## Async
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
import asyncio
|
|
109
|
+
from browsa import AsyncClient
|
|
110
|
+
|
|
111
|
+
async def main():
|
|
112
|
+
async with AsyncClient(api_key="agt_live_...") as c:
|
|
113
|
+
job = await c.run_task(
|
|
114
|
+
task="Scrape the top 5 products on producthunt.com today.",
|
|
115
|
+
llm="claude-opus-5-5",
|
|
116
|
+
llm_api_key="sk-ant-...",
|
|
117
|
+
country="US",
|
|
118
|
+
)
|
|
119
|
+
print(job.final_result)
|
|
120
|
+
|
|
121
|
+
asyncio.run(main())
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Webhooks
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from browsa import webhooks
|
|
128
|
+
|
|
129
|
+
# In your receiver (Flask/FastAPI/whatever):
|
|
130
|
+
ok = webhooks.verify_signature(
|
|
131
|
+
body=raw_request_body,
|
|
132
|
+
header=request.headers["X-Agents-Signature"],
|
|
133
|
+
secret=os.environ["BROWSA_WEBHOOK_SECRET"], # hex-encoded
|
|
134
|
+
)
|
|
135
|
+
if not ok:
|
|
136
|
+
return 401
|
|
137
|
+
# Trust the payload only after this point.
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## What you get
|
|
141
|
+
|
|
142
|
+
| Capability | Notes |
|
|
143
|
+
|---|---|
|
|
144
|
+
| Sync + async clients | `Client` + `AsyncClient`, same surface |
|
|
145
|
+
| Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
|
|
146
|
+
| Hosted tiers + reasoning | `llm="browsa" / "browsa-fast" / "browsa-smart"`, `reasoning=`, `models()`, `job.usage` |
|
|
147
|
+
| Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
|
|
148
|
+
| Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
|
|
149
|
+
| Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
|
|
150
|
+
| Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc. |
|
|
151
|
+
| `X-Request-Id` propagation | Every error carries the server's request id |
|
|
152
|
+
| Zero deps | Single wheel, audit-friendly, no transitive surface |
|
|
153
|
+
|
|
154
|
+
## Advanced
|
|
155
|
+
|
|
156
|
+
### Long-running tasks with progress callback
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
def show(job):
|
|
160
|
+
print(f" step {job.step_count}/{job.progress_total} status={job.status}")
|
|
161
|
+
|
|
162
|
+
job = c.run_task(
|
|
163
|
+
task="Open-ended research: scrape arxiv for papers on test-time compute, return top 10 by citation.",
|
|
164
|
+
llm="claude-opus-5-5",
|
|
165
|
+
llm_api_key="sk-ant-...",
|
|
166
|
+
max_steps=80,
|
|
167
|
+
on_progress=show,
|
|
168
|
+
)
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Interactive (input_required) tasks
|
|
172
|
+
|
|
173
|
+
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
job = c.create_task(task="...", llm="...", llm_api_key="...")
|
|
177
|
+
while not job.is_terminal:
|
|
178
|
+
job = c.get_job(job.id, wait=30)
|
|
179
|
+
if job.status == "input_required":
|
|
180
|
+
answer = input(f"Agent asks: {job.input_question}\n> ")
|
|
181
|
+
job = c.respond_to_job(job.id, answer)
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Sessions: follow-up messages on the same browser
|
|
185
|
+
|
|
186
|
+
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.
|
|
187
|
+
|
|
188
|
+
```python
|
|
189
|
+
s = c.create_session("Go to example.com and return the H1.", llm="browsa")
|
|
190
|
+
first = c.wait_for_job(s.id)
|
|
191
|
+
print(first.final_result)
|
|
192
|
+
|
|
193
|
+
turn = c.run_message(s.session_id, "Now open the Learn more link and tell me its URL and H1")
|
|
194
|
+
print(turn.final_result)
|
|
195
|
+
|
|
196
|
+
session = c.get_session(s.session_id)
|
|
197
|
+
print(session.status, session.browser.expires_in_seconds, [t.final_result for t in session.turns])
|
|
198
|
+
c.stop_session(s.session_id)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
`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"`.
|
|
202
|
+
|
|
203
|
+
### JA3-spoofed sessions
|
|
204
|
+
|
|
205
|
+
Some sites fingerprint TLS handshake shape. Set a profile to spoof macOS Chrome:
|
|
206
|
+
|
|
207
|
+
```python
|
|
208
|
+
job = c.run_task(
|
|
209
|
+
task="Go to a TLS-fingerprint-fingerprinted site",
|
|
210
|
+
llm="claude-opus-5-5", llm_api_key="sk-...",
|
|
211
|
+
ja3_profile="macos_chrome_137", # uses utls
|
|
212
|
+
)
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### Observe and act (no Playwright)
|
|
216
|
+
|
|
217
|
+
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.
|
|
218
|
+
|
|
219
|
+
```python
|
|
220
|
+
b = c.create_agent(ttl="10m")
|
|
221
|
+
c.act(b["id"], "navigate", url="https://example.com/login")
|
|
222
|
+
view = c.observe(b["id"])
|
|
223
|
+
print(view["text"]) # [3] textbox "Email" empty …
|
|
224
|
+
r = c.act(b["id"], "type", id=3, text="ada@example.com")
|
|
225
|
+
print(r["status"], r["text"]) # ok ~ [3] textbox "Email" value "ada@example.com"
|
|
226
|
+
c.act(b["id"], "click", role="button", name="Sign in")
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
`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>.
|
|
230
|
+
|
|
231
|
+
## Docs
|
|
232
|
+
|
|
233
|
+
- API reference: <https://browsa.io/docs>
|
|
234
|
+
- Docs: <https://browsa.io/docs>
|
|
235
|
+
- Support: <mailto:support@browsa.io>
|
|
236
|
+
|
|
237
|
+
## License
|
|
238
|
+
|
|
239
|
+
MIT.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
"""
|
|
2
|
-
browsa —
|
|
2
|
+
browsa — real browsers for AI agents.
|
|
3
3
|
|
|
4
4
|
Quickstart:
|
|
5
5
|
|
|
@@ -10,13 +10,13 @@ Quickstart:
|
|
|
10
10
|
# Run a task synchronously (blocks until the agent finishes)
|
|
11
11
|
job = client.run_task(
|
|
12
12
|
task="Go to news.ycombinator.com and return the top story title.",
|
|
13
|
-
llm="claude-opus-
|
|
13
|
+
llm="claude-opus-5-5",
|
|
14
14
|
llm_api_key="sk-ant-...",
|
|
15
15
|
)
|
|
16
16
|
print(job.final_result)
|
|
17
17
|
print(f"Live stream: {job.live_url}")
|
|
18
18
|
|
|
19
|
-
That's it. Five lines of Python to drive a real
|
|
19
|
+
That's it. Five lines of Python to drive a real browser through
|
|
20
20
|
an AI agent, get back structured output, and a live noVNC viewer URL.
|
|
21
21
|
|
|
22
22
|
For async usage:
|
|
@@ -24,15 +24,18 @@ For async usage:
|
|
|
24
24
|
from browsa import AsyncClient
|
|
25
25
|
|
|
26
26
|
async with AsyncClient(api_key="agt_live_...") as c:
|
|
27
|
-
job = await c.run_task(task="...", llm="claude-opus-
|
|
27
|
+
job = await c.run_task(task="...", llm="claude-opus-5-5", ...)
|
|
28
28
|
|
|
29
29
|
For webhooks see browsa.webhooks.verify_signature.
|
|
30
30
|
"""
|
|
31
31
|
from .client import Client, AsyncClient
|
|
32
|
-
from .types import
|
|
32
|
+
from .types import (
|
|
33
|
+
HostedModel, Job, JobFile, JobStatus, LLMKey, Models, OwnKeyModels, Schedule,
|
|
34
|
+
Session, SessionBrowser, SessionTurn, Usage, Webhook,
|
|
35
|
+
NetworkProxy, Proxy, ProxyConfig, ProxyNetwork, ProxyNetworkTier,
|
|
36
|
+
)
|
|
33
37
|
from .errors import (
|
|
34
38
|
BrowsaError,
|
|
35
|
-
NeoutError, # deprecated alias of BrowsaError — kept for backwards compat
|
|
36
39
|
APIError,
|
|
37
40
|
AuthError,
|
|
38
41
|
RateLimitError,
|
|
@@ -47,11 +50,25 @@ from ._version import __version__
|
|
|
47
50
|
__all__ = [
|
|
48
51
|
"Client",
|
|
49
52
|
"AsyncClient",
|
|
53
|
+
"HostedModel",
|
|
50
54
|
"Job",
|
|
55
|
+
"JobFile",
|
|
51
56
|
"JobStatus",
|
|
57
|
+
"LLMKey",
|
|
58
|
+
"Models",
|
|
59
|
+
"OwnKeyModels",
|
|
60
|
+
"Schedule",
|
|
61
|
+
"Session",
|
|
62
|
+
"SessionBrowser",
|
|
63
|
+
"SessionTurn",
|
|
64
|
+
"Usage",
|
|
52
65
|
"Webhook",
|
|
66
|
+
"NetworkProxy",
|
|
67
|
+
"Proxy",
|
|
68
|
+
"ProxyConfig",
|
|
69
|
+
"ProxyNetwork",
|
|
70
|
+
"ProxyNetworkTier",
|
|
53
71
|
"BrowsaError",
|
|
54
|
-
"NeoutError",
|
|
55
72
|
"APIError",
|
|
56
73
|
"AuthError",
|
|
57
74
|
"RateLimitError",
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.3.0"
|