crewai-browsa 0.1.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.
- crewai_browsa-0.1.0/.gitignore +9 -0
- crewai_browsa-0.1.0/LICENSE +21 -0
- crewai_browsa-0.1.0/PKG-INFO +277 -0
- crewai_browsa-0.1.0/README.md +245 -0
- crewai_browsa-0.1.0/examples/research_crew.py +53 -0
- crewai_browsa-0.1.0/examples/shopping_crew.py +77 -0
- crewai_browsa-0.1.0/pyproject.toml +64 -0
- crewai_browsa-0.1.0/src/crewai_browsa/__init__.py +38 -0
- crewai_browsa-0.1.0/src/crewai_browsa/_common.py +136 -0
- crewai_browsa-0.1.0/src/crewai_browsa/_version.py +1 -0
- crewai_browsa-0.1.0/src/crewai_browsa/py.typed +0 -0
- crewai_browsa-0.1.0/src/crewai_browsa/tools.py +545 -0
- crewai_browsa-0.1.0/tests/__init__.py +0 -0
- crewai_browsa-0.1.0/tests/conftest.py +107 -0
- crewai_browsa-0.1.0/tests/test_tools.py +525 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Browsa Technologies LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: crewai-browsa
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: CrewAI tools for Browsa: give your crew a Phantom cloud browser to run tasks, scrape, extract and screenshot pages (browsa.io)
|
|
5
|
+
Project-URL: Homepage, https://browsa.io
|
|
6
|
+
Project-URL: Documentation, https://browsa.io/docs
|
|
7
|
+
Project-URL: Repository, https://github.com/browsa-io/browsa
|
|
8
|
+
Project-URL: Issues, https://github.com/browsa-io/browsa/issues
|
|
9
|
+
Author-email: Browsa <support@browsa.io>
|
|
10
|
+
Maintainer-email: Browsa <support@browsa.io>
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: ai-agents,browsa,browser-automation,cloud-browser,crewai,crewai-tools,scraping
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
|
|
23
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: <3.14,>=3.10
|
|
26
|
+
Requires-Dist: browsa>=0.3.1
|
|
27
|
+
Requires-Dist: crewai>=1.15
|
|
28
|
+
Requires-Dist: pydantic>=2
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# crewai-browsa
|
|
34
|
+
|
|
35
|
+
[CrewAI](https://www.crewai.com/) tools for [Browsa](https://browsa.io), cloud browsers for AI agents. Your crew gets Phantom, Browsa's cloud browser, to run browser tasks in plain language and to scrape, extract and screenshot pages.
|
|
36
|
+
|
|
37
|
+
| Tool | What the agent gets | Credits |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| `BrowsaTaskTool` | A browser agent that opens sites, clicks, types and returns the answer (text, or JSON from an `output_schema`) | browser + 1 + 1 per 5 steps, + 5 on a hosted tier |
|
|
40
|
+
| `BrowsaScrapeTool` | One rendered page as Markdown and links | 1 per page |
|
|
41
|
+
| `BrowsaExtractTool` | Fields you describe from one page, as JSON | 1 per page |
|
|
42
|
+
| `BrowsaScreenshotTool` | A PNG of a page, saved to a file | 1 per page |
|
|
43
|
+
|
|
44
|
+
## Install
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pip install crewai-browsa
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Python 3.10 to 3.13. It installs the official [`browsa`](https://pypi.org/project/browsa/) SDK (0.3.1 or later) and `crewai`.
|
|
51
|
+
|
|
52
|
+
## Set your key
|
|
53
|
+
|
|
54
|
+
Create an API key at <https://app.browsa.io/dashboard/keys> and set it:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
export BROWSA_API_KEY=agt_live_...
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
or pass it to any tool: `BrowsaScrapeTool(api_key="agt_live_...")`. New accounts get 100 free credits after email verification, with no card.
|
|
61
|
+
|
|
62
|
+
## Quick start
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
from crewai import Agent, Crew, Task
|
|
66
|
+
from crewai_browsa import BrowsaScrapeTool, BrowsaTaskTool
|
|
67
|
+
|
|
68
|
+
researcher = Agent(
|
|
69
|
+
role="Web researcher",
|
|
70
|
+
goal="Find facts on live websites",
|
|
71
|
+
backstory="You read pages in a cloud browser and cite URLs.",
|
|
72
|
+
tools=[BrowsaScrapeTool(), BrowsaTaskTool()],
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
task = Task(
|
|
76
|
+
description="Return the titles of the top 3 stories on news.ycombinator.com.",
|
|
77
|
+
expected_output="Three titles with their links.",
|
|
78
|
+
agent=researcher,
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
print(Crew(agents=[researcher], tasks=[task]).kickoff())
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Your crew's own model is configured as usual in CrewAI. `BrowsaTaskTool` runs a separate browser agent on Browsa, by default on the hosted tier `browsa`, so no model key is needed for it.
|
|
85
|
+
|
|
86
|
+
## Example: a research crew
|
|
87
|
+
|
|
88
|
+
A researcher reads live pages and a writer turns the notes into a brief. The researcher reads known URLs with the scrape tool (1 credit) and uses a browser task only when it must click or search. Full file: [`examples/research_crew.py`](examples/research_crew.py).
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
from crewai import Agent, Crew, Process, Task
|
|
92
|
+
from crewai_browsa import BrowsaExtractTool, BrowsaScrapeTool, BrowsaTaskTool
|
|
93
|
+
|
|
94
|
+
researcher = Agent(
|
|
95
|
+
role="Web researcher",
|
|
96
|
+
goal="Collect accurate, current facts from the live web, with their source URLs",
|
|
97
|
+
backstory=(
|
|
98
|
+
"You read pages in a cloud browser. Read a known URL with the scrape tool; "
|
|
99
|
+
"use the browser task tool only when you must click, search or page through a site."
|
|
100
|
+
),
|
|
101
|
+
tools=[BrowsaScrapeTool(), BrowsaExtractTool(), BrowsaTaskTool(max_steps=25)],
|
|
102
|
+
)
|
|
103
|
+
writer = Agent(
|
|
104
|
+
role="Analyst",
|
|
105
|
+
goal="Turn the researcher's notes into a short, sourced brief",
|
|
106
|
+
backstory="You write plainly and cite every fact with its URL.",
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
research = Task(
|
|
110
|
+
description=(
|
|
111
|
+
"Find the top 5 stories on the front page of Hacker News (title, points, link). "
|
|
112
|
+
"Then open the top story's link and summarise it in three sentences."
|
|
113
|
+
),
|
|
114
|
+
expected_output="5 stories and a 3-sentence summary of the first.",
|
|
115
|
+
agent=researcher,
|
|
116
|
+
)
|
|
117
|
+
brief = Task(
|
|
118
|
+
description="Write a brief from the research: one line per story, then the summary.",
|
|
119
|
+
expected_output="A Markdown brief with sources.",
|
|
120
|
+
agent=writer,
|
|
121
|
+
context=[research],
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
Crew(agents=[researcher, writer], tasks=[research, brief], process=Process.sequential).kickoff()
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Example: a shopping assistant that compares stores
|
|
128
|
+
|
|
129
|
+
The shopper runs one browser task per store. Each task returns the same JSON shape through an `output_schema`, and an advisor compares the offers. Full file: [`examples/shopping_crew.py`](examples/shopping_crew.py).
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
from crewai import Agent, Crew, Process, Task
|
|
133
|
+
from crewai_browsa import BrowsaTaskTool
|
|
134
|
+
|
|
135
|
+
OFFER_SCHEMA = {
|
|
136
|
+
"type": "object",
|
|
137
|
+
"properties": {
|
|
138
|
+
"store": {"type": "string"},
|
|
139
|
+
"product_title": {"type": "string"},
|
|
140
|
+
"price": {"type": "number"},
|
|
141
|
+
"currency": {"type": "string"},
|
|
142
|
+
"in_stock": {"type": "boolean"},
|
|
143
|
+
"url": {"type": "string"},
|
|
144
|
+
},
|
|
145
|
+
"required": ["store", "product_title", "price", "currency", "in_stock", "url"],
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
shopper = Agent(
|
|
149
|
+
role="Shopping assistant",
|
|
150
|
+
goal="Find the current price and stock of one exact product at each store",
|
|
151
|
+
backstory="You check one store per browser task and skip accessories and bundles.",
|
|
152
|
+
tools=[BrowsaTaskTool(output_schema=OFFER_SCHEMA, max_steps=30, max_credits=20)],
|
|
153
|
+
)
|
|
154
|
+
advisor = Agent(
|
|
155
|
+
role="Buying advisor",
|
|
156
|
+
goal="Recommend where to buy, based only on the offers that were found",
|
|
157
|
+
backstory="You compare like for like and never invent a price.",
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
find_offers = Task(
|
|
161
|
+
description=(
|
|
162
|
+
"Product: Sony WH-1000XM5 headphones, black. For each of bestbuy.com, target.com "
|
|
163
|
+
"and walmart.com, run one browser task: search the store, open the exact listing "
|
|
164
|
+
"and return the offer. Note any store that failed and why."
|
|
165
|
+
),
|
|
166
|
+
expected_output="One JSON offer per store, plus a note for stores with no offer.",
|
|
167
|
+
agent=shopper,
|
|
168
|
+
)
|
|
169
|
+
recommend = Task(
|
|
170
|
+
description="Compare the offers: cheapest in-stock offer first, then the rest.",
|
|
171
|
+
expected_output="A table (store, price, in stock, link) and a one-line recommendation.",
|
|
172
|
+
agent=advisor,
|
|
173
|
+
context=[find_offers],
|
|
174
|
+
)
|
|
175
|
+
|
|
176
|
+
Crew(agents=[shopper, advisor], tasks=[find_offers, recommend], process=Process.sequential).kickoff()
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Browsa's task agent does not press order, payment or subscription buttons unless the task sets `allow_purchase` (it is off by default), so this crew only reads. One task per store keeps each answer separate: when a task about several named stores has no answer for one of them, the whole task's outcome is `failed`.
|
|
180
|
+
|
|
181
|
+
## What `BrowsaTaskTool` returns
|
|
182
|
+
|
|
183
|
+
On success the agent gets JSON:
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
{
|
|
187
|
+
"result": {"store": "...", "price": 279.99, "...": "..."},
|
|
188
|
+
"status": "completed",
|
|
189
|
+
"outcome": "completed",
|
|
190
|
+
"partial": false,
|
|
191
|
+
"job_id": "252e8eac-...",
|
|
192
|
+
"live_url": "https://...",
|
|
193
|
+
"credits_charged": 11
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
- `result` is `structured_output` when an `output_schema` was given, otherwise the agent's text answer.
|
|
198
|
+
- The tool reads `outcome`, not only `status`. `status: "completed"` with `outcome: "failed"` means the agent finished but could not do the task; the tool reports that as a failure, with `outcome_message` saying what stopped it.
|
|
199
|
+
- A task a limit stopped (`step_limit_reached`, `budget_reached`, `timed_out`) that still returned a partial result comes back with `"partial": true`.
|
|
200
|
+
- `live_url` is a Phantom Live link to watch the browser. It exists only while the task runs, and each link opens once.
|
|
201
|
+
|
|
202
|
+
Failures (a failed outcome, an HTTP error such as `402 INSUFFICIENT_CREDIT`, no free browser slot) are returned as CrewAI `ToolFailure` objects, so CrewAI records the call as failed and your crew's tool failure policy applies. The agent still reads the message, the error code and the details. On crewai versions without `ToolFailure` the tool returns the same text.
|
|
203
|
+
|
|
204
|
+
If a task is still running at `timeout` (600 seconds by default), or stops to ask a question the tool cannot answer, the tool cancels it so it does not keep its browser. Pass `cancel_unfinished=False` to leave it running.
|
|
205
|
+
|
|
206
|
+
## Options
|
|
207
|
+
|
|
208
|
+
All tools take `api_key` (default `BROWSA_API_KEY`), `base_url` (default `BROWSA_BASE_URL` or `https://browsa.io`) and `client` (an existing `browsa.Client`).
|
|
209
|
+
|
|
210
|
+
`BrowsaTaskTool`
|
|
211
|
+
|
|
212
|
+
| Option | Default | Meaning |
|
|
213
|
+
|---|---|---|
|
|
214
|
+
| `llm` | `"browsa"` | A hosted tier (`"browsa"`, `"browsa-fast"`, `"browsa-smart"`) or your own model, e.g. `"anthropic:claude-sonnet-5-5"` |
|
|
215
|
+
| `llm_api_key` | none | Your Anthropic, OpenAI or Google key, for this task only |
|
|
216
|
+
| `llm_key_id` | none | A model key saved in your Browsa workspace |
|
|
217
|
+
| `reasoning` | none | `"low"`, `"medium"` or `"high"` |
|
|
218
|
+
| `max_steps` | Browsa's 20 | Most agent steps, up to 100 |
|
|
219
|
+
| `max_credits` | none | Most credits one task may charge |
|
|
220
|
+
| `output_schema` | none | Default JSON Schema for the answer; the agent can pass its own |
|
|
221
|
+
| `timeout` | 600 | Seconds to wait |
|
|
222
|
+
| `cancel_unfinished` | `True` | Cancel on timeout or on a question |
|
|
223
|
+
| `task_options` | `{}` | Any other `POST /v1/tasks` field, e.g. `{"allowed_domains": ["example.com"]}` |
|
|
224
|
+
|
|
225
|
+
The agent passes `task`, and optionally `start_url` and `output_schema`.
|
|
226
|
+
|
|
227
|
+
To use your own model key instead of a hosted tier:
|
|
228
|
+
|
|
229
|
+
```python
|
|
230
|
+
import os
|
|
231
|
+
BrowsaTaskTool(llm="anthropic:claude-sonnet-5-5", llm_api_key=os.environ["ANTHROPIC_API_KEY"])
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
`BrowsaScrapeTool`: `formats` (any of `markdown`, `html`, `text`, `links`; default `["markdown", "links"]`), `max_chars` (30000 here; Browsa's default is 100000), `wait_ms`, `country`, `block`, `max_links`.
|
|
235
|
+
|
|
236
|
+
`BrowsaExtractTool`: the agent passes `url` and a `prompt` or an `extraction_schema`. With `llm_api_key` (an Anthropic or Anthropic-compatible key) or a saved `llm_key_id`, Browsa runs the extraction and the tool returns `data` as JSON. Without a key, Browsa returns the page's clean text and the schema, and your crew's model reads the fields from it.
|
|
237
|
+
|
|
238
|
+
`BrowsaScreenshotTool`: the agent passes `url` and `full_page`; the PNG is written to `output_dir` (default `browsa_screenshots`) and the tool returns its path.
|
|
239
|
+
|
|
240
|
+
All tools also have `_arun`, so they work in async crews.
|
|
241
|
+
|
|
242
|
+
## Costs
|
|
243
|
+
|
|
244
|
+
From <https://browsa.io/pricing>:
|
|
245
|
+
|
|
246
|
+
| What you run | Credits |
|
|
247
|
+
|---|---|
|
|
248
|
+
| Cloud browser | 1 per started 12 minutes it runs, 5 for a full hour |
|
|
249
|
+
| Quick scrape, extract or screenshot | 1 per page |
|
|
250
|
+
| Agent task, your own LLM key | browser + 1 + 1 per 5 steps |
|
|
251
|
+
| Agent task on a hosted tier (`"llm": "browsa"`, `"browsa-fast"` or `"browsa-smart"`) | browser + 1 + 1 per 5 steps + 5 |
|
|
252
|
+
|
|
253
|
+
- A 10-step agent task that finishes inside 12 minutes costs 4 credits with your own key, 9 on a hosted tier. A 20-step task costs 6 or 11.
|
|
254
|
+
- A task that fails gets its whole browser charge back and is not charged for steps or the hosted surcharge. With your own model key, Browsa adds no LLM markup; your provider bills you for tokens.
|
|
255
|
+
- Credit packs: Starter $20 for 200 credits, Growth $100 for 1,200, Pro $500 for 7,500. Credits never expire. No subscription.
|
|
256
|
+
- A workspace has 6 browser slots; a request with every slot in use gets `429 TOO_MANY_REQUESTS` and is not charged. The tool reports it as a retryable failure.
|
|
257
|
+
|
|
258
|
+
Set `max_credits` on `BrowsaTaskTool` to cap what one task may charge.
|
|
259
|
+
|
|
260
|
+
## Development
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
pip install -e ".[dev]"
|
|
264
|
+
pytest
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
The tests fake the HTTP layer under the `browsa` SDK and block real sockets, so they need no key and no network.
|
|
268
|
+
|
|
269
|
+
## Links
|
|
270
|
+
|
|
271
|
+
- Browsa: <https://browsa.io>
|
|
272
|
+
- API docs: <https://browsa.io/docs>
|
|
273
|
+
- Python SDK: <https://pypi.org/project/browsa/>
|
|
274
|
+
- Source: <https://github.com/browsa-io/browsa>
|
|
275
|
+
- Support: support@browsa.io
|
|
276
|
+
|
|
277
|
+
MIT licensed.
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
# crewai-browsa
|
|
2
|
+
|
|
3
|
+
[CrewAI](https://www.crewai.com/) tools for [Browsa](https://browsa.io), cloud browsers for AI agents. Your crew gets Phantom, Browsa's cloud browser, to run browser tasks in plain language and to scrape, extract and screenshot pages.
|
|
4
|
+
|
|
5
|
+
| Tool | What the agent gets | Credits |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| `BrowsaTaskTool` | A browser agent that opens sites, clicks, types and returns the answer (text, or JSON from an `output_schema`) | browser + 1 + 1 per 5 steps, + 5 on a hosted tier |
|
|
8
|
+
| `BrowsaScrapeTool` | One rendered page as Markdown and links | 1 per page |
|
|
9
|
+
| `BrowsaExtractTool` | Fields you describe from one page, as JSON | 1 per page |
|
|
10
|
+
| `BrowsaScreenshotTool` | A PNG of a page, saved to a file | 1 per page |
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pip install crewai-browsa
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Python 3.10 to 3.13. It installs the official [`browsa`](https://pypi.org/project/browsa/) SDK (0.3.1 or later) and `crewai`.
|
|
19
|
+
|
|
20
|
+
## Set your key
|
|
21
|
+
|
|
22
|
+
Create an API key at <https://app.browsa.io/dashboard/keys> and set it:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
export BROWSA_API_KEY=agt_live_...
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
or pass it to any tool: `BrowsaScrapeTool(api_key="agt_live_...")`. New accounts get 100 free credits after email verification, with no card.
|
|
29
|
+
|
|
30
|
+
## Quick start
|
|
31
|
+
|
|
32
|
+
```python
|
|
33
|
+
from crewai import Agent, Crew, Task
|
|
34
|
+
from crewai_browsa import BrowsaScrapeTool, BrowsaTaskTool
|
|
35
|
+
|
|
36
|
+
researcher = Agent(
|
|
37
|
+
role="Web researcher",
|
|
38
|
+
goal="Find facts on live websites",
|
|
39
|
+
backstory="You read pages in a cloud browser and cite URLs.",
|
|
40
|
+
tools=[BrowsaScrapeTool(), BrowsaTaskTool()],
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
task = Task(
|
|
44
|
+
description="Return the titles of the top 3 stories on news.ycombinator.com.",
|
|
45
|
+
expected_output="Three titles with their links.",
|
|
46
|
+
agent=researcher,
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
print(Crew(agents=[researcher], tasks=[task]).kickoff())
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Your crew's own model is configured as usual in CrewAI. `BrowsaTaskTool` runs a separate browser agent on Browsa, by default on the hosted tier `browsa`, so no model key is needed for it.
|
|
53
|
+
|
|
54
|
+
## Example: a research crew
|
|
55
|
+
|
|
56
|
+
A researcher reads live pages and a writer turns the notes into a brief. The researcher reads known URLs with the scrape tool (1 credit) and uses a browser task only when it must click or search. Full file: [`examples/research_crew.py`](examples/research_crew.py).
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
from crewai import Agent, Crew, Process, Task
|
|
60
|
+
from crewai_browsa import BrowsaExtractTool, BrowsaScrapeTool, BrowsaTaskTool
|
|
61
|
+
|
|
62
|
+
researcher = Agent(
|
|
63
|
+
role="Web researcher",
|
|
64
|
+
goal="Collect accurate, current facts from the live web, with their source URLs",
|
|
65
|
+
backstory=(
|
|
66
|
+
"You read pages in a cloud browser. Read a known URL with the scrape tool; "
|
|
67
|
+
"use the browser task tool only when you must click, search or page through a site."
|
|
68
|
+
),
|
|
69
|
+
tools=[BrowsaScrapeTool(), BrowsaExtractTool(), BrowsaTaskTool(max_steps=25)],
|
|
70
|
+
)
|
|
71
|
+
writer = Agent(
|
|
72
|
+
role="Analyst",
|
|
73
|
+
goal="Turn the researcher's notes into a short, sourced brief",
|
|
74
|
+
backstory="You write plainly and cite every fact with its URL.",
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
research = Task(
|
|
78
|
+
description=(
|
|
79
|
+
"Find the top 5 stories on the front page of Hacker News (title, points, link). "
|
|
80
|
+
"Then open the top story's link and summarise it in three sentences."
|
|
81
|
+
),
|
|
82
|
+
expected_output="5 stories and a 3-sentence summary of the first.",
|
|
83
|
+
agent=researcher,
|
|
84
|
+
)
|
|
85
|
+
brief = Task(
|
|
86
|
+
description="Write a brief from the research: one line per story, then the summary.",
|
|
87
|
+
expected_output="A Markdown brief with sources.",
|
|
88
|
+
agent=writer,
|
|
89
|
+
context=[research],
|
|
90
|
+
)
|
|
91
|
+
|
|
92
|
+
Crew(agents=[researcher, writer], tasks=[research, brief], process=Process.sequential).kickoff()
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Example: a shopping assistant that compares stores
|
|
96
|
+
|
|
97
|
+
The shopper runs one browser task per store. Each task returns the same JSON shape through an `output_schema`, and an advisor compares the offers. Full file: [`examples/shopping_crew.py`](examples/shopping_crew.py).
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
from crewai import Agent, Crew, Process, Task
|
|
101
|
+
from crewai_browsa import BrowsaTaskTool
|
|
102
|
+
|
|
103
|
+
OFFER_SCHEMA = {
|
|
104
|
+
"type": "object",
|
|
105
|
+
"properties": {
|
|
106
|
+
"store": {"type": "string"},
|
|
107
|
+
"product_title": {"type": "string"},
|
|
108
|
+
"price": {"type": "number"},
|
|
109
|
+
"currency": {"type": "string"},
|
|
110
|
+
"in_stock": {"type": "boolean"},
|
|
111
|
+
"url": {"type": "string"},
|
|
112
|
+
},
|
|
113
|
+
"required": ["store", "product_title", "price", "currency", "in_stock", "url"],
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
shopper = Agent(
|
|
117
|
+
role="Shopping assistant",
|
|
118
|
+
goal="Find the current price and stock of one exact product at each store",
|
|
119
|
+
backstory="You check one store per browser task and skip accessories and bundles.",
|
|
120
|
+
tools=[BrowsaTaskTool(output_schema=OFFER_SCHEMA, max_steps=30, max_credits=20)],
|
|
121
|
+
)
|
|
122
|
+
advisor = Agent(
|
|
123
|
+
role="Buying advisor",
|
|
124
|
+
goal="Recommend where to buy, based only on the offers that were found",
|
|
125
|
+
backstory="You compare like for like and never invent a price.",
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
find_offers = Task(
|
|
129
|
+
description=(
|
|
130
|
+
"Product: Sony WH-1000XM5 headphones, black. For each of bestbuy.com, target.com "
|
|
131
|
+
"and walmart.com, run one browser task: search the store, open the exact listing "
|
|
132
|
+
"and return the offer. Note any store that failed and why."
|
|
133
|
+
),
|
|
134
|
+
expected_output="One JSON offer per store, plus a note for stores with no offer.",
|
|
135
|
+
agent=shopper,
|
|
136
|
+
)
|
|
137
|
+
recommend = Task(
|
|
138
|
+
description="Compare the offers: cheapest in-stock offer first, then the rest.",
|
|
139
|
+
expected_output="A table (store, price, in stock, link) and a one-line recommendation.",
|
|
140
|
+
agent=advisor,
|
|
141
|
+
context=[find_offers],
|
|
142
|
+
)
|
|
143
|
+
|
|
144
|
+
Crew(agents=[shopper, advisor], tasks=[find_offers, recommend], process=Process.sequential).kickoff()
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Browsa's task agent does not press order, payment or subscription buttons unless the task sets `allow_purchase` (it is off by default), so this crew only reads. One task per store keeps each answer separate: when a task about several named stores has no answer for one of them, the whole task's outcome is `failed`.
|
|
148
|
+
|
|
149
|
+
## What `BrowsaTaskTool` returns
|
|
150
|
+
|
|
151
|
+
On success the agent gets JSON:
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{
|
|
155
|
+
"result": {"store": "...", "price": 279.99, "...": "..."},
|
|
156
|
+
"status": "completed",
|
|
157
|
+
"outcome": "completed",
|
|
158
|
+
"partial": false,
|
|
159
|
+
"job_id": "252e8eac-...",
|
|
160
|
+
"live_url": "https://...",
|
|
161
|
+
"credits_charged": 11
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
- `result` is `structured_output` when an `output_schema` was given, otherwise the agent's text answer.
|
|
166
|
+
- The tool reads `outcome`, not only `status`. `status: "completed"` with `outcome: "failed"` means the agent finished but could not do the task; the tool reports that as a failure, with `outcome_message` saying what stopped it.
|
|
167
|
+
- A task a limit stopped (`step_limit_reached`, `budget_reached`, `timed_out`) that still returned a partial result comes back with `"partial": true`.
|
|
168
|
+
- `live_url` is a Phantom Live link to watch the browser. It exists only while the task runs, and each link opens once.
|
|
169
|
+
|
|
170
|
+
Failures (a failed outcome, an HTTP error such as `402 INSUFFICIENT_CREDIT`, no free browser slot) are returned as CrewAI `ToolFailure` objects, so CrewAI records the call as failed and your crew's tool failure policy applies. The agent still reads the message, the error code and the details. On crewai versions without `ToolFailure` the tool returns the same text.
|
|
171
|
+
|
|
172
|
+
If a task is still running at `timeout` (600 seconds by default), or stops to ask a question the tool cannot answer, the tool cancels it so it does not keep its browser. Pass `cancel_unfinished=False` to leave it running.
|
|
173
|
+
|
|
174
|
+
## Options
|
|
175
|
+
|
|
176
|
+
All tools take `api_key` (default `BROWSA_API_KEY`), `base_url` (default `BROWSA_BASE_URL` or `https://browsa.io`) and `client` (an existing `browsa.Client`).
|
|
177
|
+
|
|
178
|
+
`BrowsaTaskTool`
|
|
179
|
+
|
|
180
|
+
| Option | Default | Meaning |
|
|
181
|
+
|---|---|---|
|
|
182
|
+
| `llm` | `"browsa"` | A hosted tier (`"browsa"`, `"browsa-fast"`, `"browsa-smart"`) or your own model, e.g. `"anthropic:claude-sonnet-5-5"` |
|
|
183
|
+
| `llm_api_key` | none | Your Anthropic, OpenAI or Google key, for this task only |
|
|
184
|
+
| `llm_key_id` | none | A model key saved in your Browsa workspace |
|
|
185
|
+
| `reasoning` | none | `"low"`, `"medium"` or `"high"` |
|
|
186
|
+
| `max_steps` | Browsa's 20 | Most agent steps, up to 100 |
|
|
187
|
+
| `max_credits` | none | Most credits one task may charge |
|
|
188
|
+
| `output_schema` | none | Default JSON Schema for the answer; the agent can pass its own |
|
|
189
|
+
| `timeout` | 600 | Seconds to wait |
|
|
190
|
+
| `cancel_unfinished` | `True` | Cancel on timeout or on a question |
|
|
191
|
+
| `task_options` | `{}` | Any other `POST /v1/tasks` field, e.g. `{"allowed_domains": ["example.com"]}` |
|
|
192
|
+
|
|
193
|
+
The agent passes `task`, and optionally `start_url` and `output_schema`.
|
|
194
|
+
|
|
195
|
+
To use your own model key instead of a hosted tier:
|
|
196
|
+
|
|
197
|
+
```python
|
|
198
|
+
import os
|
|
199
|
+
BrowsaTaskTool(llm="anthropic:claude-sonnet-5-5", llm_api_key=os.environ["ANTHROPIC_API_KEY"])
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`BrowsaScrapeTool`: `formats` (any of `markdown`, `html`, `text`, `links`; default `["markdown", "links"]`), `max_chars` (30000 here; Browsa's default is 100000), `wait_ms`, `country`, `block`, `max_links`.
|
|
203
|
+
|
|
204
|
+
`BrowsaExtractTool`: the agent passes `url` and a `prompt` or an `extraction_schema`. With `llm_api_key` (an Anthropic or Anthropic-compatible key) or a saved `llm_key_id`, Browsa runs the extraction and the tool returns `data` as JSON. Without a key, Browsa returns the page's clean text and the schema, and your crew's model reads the fields from it.
|
|
205
|
+
|
|
206
|
+
`BrowsaScreenshotTool`: the agent passes `url` and `full_page`; the PNG is written to `output_dir` (default `browsa_screenshots`) and the tool returns its path.
|
|
207
|
+
|
|
208
|
+
All tools also have `_arun`, so they work in async crews.
|
|
209
|
+
|
|
210
|
+
## Costs
|
|
211
|
+
|
|
212
|
+
From <https://browsa.io/pricing>:
|
|
213
|
+
|
|
214
|
+
| What you run | Credits |
|
|
215
|
+
|---|---|
|
|
216
|
+
| Cloud browser | 1 per started 12 minutes it runs, 5 for a full hour |
|
|
217
|
+
| Quick scrape, extract or screenshot | 1 per page |
|
|
218
|
+
| Agent task, your own LLM key | browser + 1 + 1 per 5 steps |
|
|
219
|
+
| Agent task on a hosted tier (`"llm": "browsa"`, `"browsa-fast"` or `"browsa-smart"`) | browser + 1 + 1 per 5 steps + 5 |
|
|
220
|
+
|
|
221
|
+
- A 10-step agent task that finishes inside 12 minutes costs 4 credits with your own key, 9 on a hosted tier. A 20-step task costs 6 or 11.
|
|
222
|
+
- A task that fails gets its whole browser charge back and is not charged for steps or the hosted surcharge. With your own model key, Browsa adds no LLM markup; your provider bills you for tokens.
|
|
223
|
+
- Credit packs: Starter $20 for 200 credits, Growth $100 for 1,200, Pro $500 for 7,500. Credits never expire. No subscription.
|
|
224
|
+
- A workspace has 6 browser slots; a request with every slot in use gets `429 TOO_MANY_REQUESTS` and is not charged. The tool reports it as a retryable failure.
|
|
225
|
+
|
|
226
|
+
Set `max_credits` on `BrowsaTaskTool` to cap what one task may charge.
|
|
227
|
+
|
|
228
|
+
## Development
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
pip install -e ".[dev]"
|
|
232
|
+
pytest
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
The tests fake the HTTP layer under the `browsa` SDK and block real sockets, so they need no key and no network.
|
|
236
|
+
|
|
237
|
+
## Links
|
|
238
|
+
|
|
239
|
+
- Browsa: <https://browsa.io>
|
|
240
|
+
- API docs: <https://browsa.io/docs>
|
|
241
|
+
- Python SDK: <https://pypi.org/project/browsa/>
|
|
242
|
+
- Source: <https://github.com/browsa-io/browsa>
|
|
243
|
+
- Support: support@browsa.io
|
|
244
|
+
|
|
245
|
+
MIT licensed.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""A research crew: one agent reads live pages with Browsa, another writes.
|
|
2
|
+
|
|
3
|
+
pip install crewai-browsa
|
|
4
|
+
export BROWSA_API_KEY=agt_live_...
|
|
5
|
+
# plus the key of the model your crew runs on, as usual in CrewAI
|
|
6
|
+
python research_crew.py
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from crewai import Agent, Crew, Process, Task
|
|
10
|
+
|
|
11
|
+
from crewai_browsa import BrowsaExtractTool, BrowsaScrapeTool, BrowsaTaskTool
|
|
12
|
+
|
|
13
|
+
scrape = BrowsaScrapeTool() # 1 credit per page
|
|
14
|
+
extract = BrowsaExtractTool() # 1 credit per page
|
|
15
|
+
browse = BrowsaTaskTool(max_steps=25) # hosted tier "browsa" by default
|
|
16
|
+
|
|
17
|
+
researcher = Agent(
|
|
18
|
+
role="Web researcher",
|
|
19
|
+
goal="Collect accurate, current facts from the live web, with their source URLs",
|
|
20
|
+
backstory=(
|
|
21
|
+
"You read pages in a cloud browser. Read a known URL with the scrape tool; "
|
|
22
|
+
"use the browser task tool only when you must click, search or page through a site."
|
|
23
|
+
),
|
|
24
|
+
tools=[scrape, extract, browse],
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
writer = Agent(
|
|
28
|
+
role="Analyst",
|
|
29
|
+
goal="Turn the researcher's notes into a short, sourced brief",
|
|
30
|
+
backstory="You write plainly and cite every fact with its URL.",
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
research = Task(
|
|
34
|
+
description=(
|
|
35
|
+
"Find what is on the front page of Hacker News right now: the top 5 stories "
|
|
36
|
+
"with title, points and link. Then open the top story's link and summarise it "
|
|
37
|
+
"in three sentences."
|
|
38
|
+
),
|
|
39
|
+
expected_output="A list of 5 stories (title, points, URL) and a 3-sentence summary of the first.",
|
|
40
|
+
agent=researcher,
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
brief = Task(
|
|
44
|
+
description="Write a brief from the research: one line per story, then the summary.",
|
|
45
|
+
expected_output="A Markdown brief with sources.",
|
|
46
|
+
agent=writer,
|
|
47
|
+
context=[research],
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
crew = Crew(agents=[researcher, writer], tasks=[research, brief], process=Process.sequential)
|
|
51
|
+
|
|
52
|
+
if __name__ == "__main__":
|
|
53
|
+
print(crew.kickoff())
|