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.
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .pytest_cache/
4
+ .benchmarks/
5
+ dist/
6
+ build/
7
+ *.egg-info/
8
+ .venv/
9
+ browsa_screenshots/
@@ -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())