crewai-browsa 0.1.0__py3-none-any.whl

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,38 @@
1
+ """CrewAI tools for Browsa, cloud browsers for AI agents (https://browsa.io).
2
+
3
+ from crewai import Agent
4
+ from crewai_browsa import BrowsaTaskTool, BrowsaScrapeTool
5
+
6
+ agent = Agent(
7
+ role="Web researcher",
8
+ goal="Find facts on live websites",
9
+ backstory="Uses a Phantom cloud browser.",
10
+ tools=[BrowsaTaskTool(), BrowsaScrapeTool()], # reads BROWSA_API_KEY
11
+ )
12
+ """
13
+
14
+ from ._common import BrowsaBaseTool
15
+ from ._version import __version__
16
+ from .tools import (
17
+ BrowsaExtractTool,
18
+ BrowsaExtractToolSchema,
19
+ BrowsaScrapeTool,
20
+ BrowsaScrapeToolSchema,
21
+ BrowsaScreenshotTool,
22
+ BrowsaScreenshotToolSchema,
23
+ BrowsaTaskTool,
24
+ BrowsaTaskToolSchema,
25
+ )
26
+
27
+ __all__ = [
28
+ "BrowsaBaseTool",
29
+ "BrowsaExtractTool",
30
+ "BrowsaExtractToolSchema",
31
+ "BrowsaScrapeTool",
32
+ "BrowsaScrapeToolSchema",
33
+ "BrowsaScreenshotTool",
34
+ "BrowsaScreenshotToolSchema",
35
+ "BrowsaTaskTool",
36
+ "BrowsaTaskToolSchema",
37
+ "__version__",
38
+ ]
@@ -0,0 +1,136 @@
1
+ """Shared plumbing for the Browsa tools: config, the client and failures."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ from typing import Any
8
+
9
+ from browsa import Client
10
+ from browsa.errors import BrowsaError, RateLimitError
11
+ from crewai.tools import BaseTool, EnvVar
12
+ from pydantic import Field, PrivateAttr
13
+
14
+ _ToolFailure: Any
15
+ try: # crewai versions with ToolFailure record a returned one as a failed call.
16
+ from crewai.tools import ToolFailure as _ToolFailure
17
+ except ImportError: # pragma: no cover - exercised by a test that hides it
18
+ _ToolFailure = None
19
+
20
+ API_KEY_ENV = "BROWSA_API_KEY"
21
+ BASE_URL_ENV = "BROWSA_BASE_URL"
22
+ DEFAULT_BASE_URL = "https://browsa.io"
23
+
24
+ # Error codes after which the same call may well work: no free browser
25
+ # slot (429), Browsa's browser failed (502 UPSTREAM_UNAVAILABLE), a timeout.
26
+ _RETRYABLE_CODES = {
27
+ "TOO_MANY_REQUESTS",
28
+ "RATE_LIMIT",
29
+ "UPSTREAM_UNAVAILABLE",
30
+ "UPSTREAM_TIMEOUT",
31
+ "TIMEOUT",
32
+ }
33
+
34
+
35
+ def failure(
36
+ message: str,
37
+ *,
38
+ code: str | None = None,
39
+ retryable: bool = False,
40
+ details: dict[str, Any] | None = None,
41
+ ) -> Any:
42
+ """Report a failed call.
43
+
44
+ On crewai versions that have ``ToolFailure`` this returns one, so the
45
+ framework records the call as failed (and its failure policy applies).
46
+ On older versions it returns the same text the agent would have seen.
47
+ """
48
+ details = {k: v for k, v in (details or {}).items() if v not in (None, "", [])}
49
+ if _ToolFailure is not None:
50
+ return _ToolFailure(
51
+ message=_with_details(message, details),
52
+ code=code,
53
+ retryable=retryable,
54
+ details=details,
55
+ )
56
+ text = _with_details(message, details)
57
+ return f"{text} (code: {code})" if code else text
58
+
59
+
60
+ def _with_details(message: str, details: dict[str, Any]) -> str:
61
+ if not details:
62
+ return message
63
+ return f"{message}\n{json.dumps(details, ensure_ascii=False, indent=2)}"
64
+
65
+
66
+ def failure_from_error(action: str, err: BrowsaError) -> Any:
67
+ """Turn an SDK error (HTTP error envelope, timeout, network) into a failure."""
68
+ code = getattr(err, "code", None)
69
+ status = getattr(err, "status", None)
70
+ retryable = (
71
+ isinstance(err, RateLimitError)
72
+ or (code in _RETRYABLE_CODES)
73
+ or status in (429, 502, 503, 504)
74
+ )
75
+ message = f"Browsa {action} failed: {err.args[0] if err.args else err}"
76
+ details: dict[str, Any] = {
77
+ "http_status": status,
78
+ "request_id": getattr(err, "request_id", None),
79
+ }
80
+ retry_after = getattr(err, "retry_after", None)
81
+ if retry_after:
82
+ details["retry_after_seconds"] = retry_after
83
+ return failure(message, code=code, retryable=retryable, details=details)
84
+
85
+
86
+ class BrowsaBaseTool(BaseTool):
87
+ """Base class: reads the API key and builds one ``browsa.Client``.
88
+
89
+ Args:
90
+ api_key: A Browsa API key (``agt_live_...``). Defaults to the
91
+ ``BROWSA_API_KEY`` environment variable.
92
+ base_url: API base URL. Defaults to ``BROWSA_BASE_URL`` or
93
+ https://browsa.io.
94
+ client: An existing ``browsa.Client`` to use instead (then
95
+ ``api_key`` and ``base_url`` are ignored).
96
+ """
97
+
98
+ package_dependencies: list[str] = Field(default_factory=lambda: ["browsa"])
99
+ env_vars: list[EnvVar] = Field(
100
+ default_factory=lambda: [
101
+ EnvVar(
102
+ name=API_KEY_ENV,
103
+ description="Browsa API key (agt_live_...), from https://app.browsa.io/dashboard/keys",
104
+ required=True,
105
+ ),
106
+ ]
107
+ )
108
+
109
+ _client: Any = PrivateAttr(default=None)
110
+
111
+ def __init__(
112
+ self,
113
+ api_key: str | None = None,
114
+ *,
115
+ base_url: str | None = None,
116
+ client: Any | None = None,
117
+ **kwargs: Any,
118
+ ) -> None:
119
+ super().__init__(**kwargs)
120
+ if client is None:
121
+ key = api_key or os.getenv(API_KEY_ENV)
122
+ if not key:
123
+ raise ValueError(
124
+ f"A Browsa API key is required: pass api_key=... or set {API_KEY_ENV}. "
125
+ "Create one at https://app.browsa.io/dashboard/keys"
126
+ )
127
+ client = Client(
128
+ api_key=key,
129
+ base_url=base_url or os.getenv(BASE_URL_ENV) or DEFAULT_BASE_URL,
130
+ )
131
+ self._client = client
132
+
133
+ @property
134
+ def client(self) -> Any:
135
+ """The ``browsa.Client`` this tool calls."""
136
+ return self._client
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"
crewai_browsa/py.typed ADDED
File without changes
crewai_browsa/tools.py ADDED
@@ -0,0 +1,545 @@
1
+ """CrewAI tools for Browsa (https://browsa.io).
2
+
3
+ Each tool calls the official ``browsa`` Python SDK. Every page is opened in
4
+ Phantom, Browsa's cloud browser.
5
+
6
+ Costs in credits (https://browsa.io/pricing):
7
+
8
+ - BrowsaTaskTool: browser time (1 credit per started 12 minutes) + 1 + 1 per
9
+ 5 steps, plus 5 on a hosted tier (``llm="browsa"``, the default here). A
10
+ task that fails gets its browser charge back and is not charged for steps
11
+ or the hosted surcharge.
12
+ - BrowsaScrapeTool, BrowsaExtractTool, BrowsaScreenshotTool: 1 credit per page.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import asyncio
18
+ import base64
19
+ import json
20
+ import re
21
+ import time
22
+ from pathlib import Path
23
+ from typing import Any, Literal
24
+
25
+ from browsa.errors import BrowsaError
26
+ from pydantic import BaseModel, Field
27
+
28
+ from ._common import BrowsaBaseTool, failure, failure_from_error
29
+
30
+ # Outcomes (GET /v1/jobs/{id}) of a task that ended with a usable answer.
31
+ # "completed" is a full answer. The three limits below can stop a task that
32
+ # still returned a partial result: its status is then "completed".
33
+ _PARTIAL_OUTCOMES = {"step_limit_reached", "budget_reached", "timed_out"}
34
+ _TERMINAL = {"completed", "failed", "cancelled"}
35
+
36
+
37
+ def _dumps(value: Any) -> str:
38
+ return json.dumps(value, ensure_ascii=False, indent=2, default=str)
39
+
40
+
41
+ def _truncate(text: str, limit: int | None) -> str:
42
+ if limit is None or limit <= 0 or len(text) <= limit:
43
+ return text
44
+ return text[:limit] + f"\n\n[truncated: {len(text) - limit} more characters]"
45
+
46
+
47
+ # ── BrowsaTaskTool ─────────────────────────────────────────────────────────
48
+
49
+
50
+ class BrowsaTaskToolSchema(BaseModel):
51
+ """Input for BrowsaTaskTool."""
52
+
53
+ task: str = Field(
54
+ ...,
55
+ description=(
56
+ "What the browser agent should do, in plain language, as one "
57
+ "self-contained instruction. Name the website or URL to start from "
58
+ "and say exactly what to return, e.g. 'Go to books.toscrape.com, "
59
+ "open the Travel category and return the title and price of the "
60
+ "first 3 books.'"
61
+ ),
62
+ )
63
+ start_url: str | None = Field(
64
+ default=None,
65
+ description="Optional URL the browser opens before the agent starts.",
66
+ )
67
+ output_schema: dict[str, Any] | None = Field(
68
+ default=None,
69
+ description=(
70
+ "Optional JSON Schema for the answer, when you need structured data. "
71
+ "The top level must be an object, e.g. "
72
+ '{"type": "object", "properties": {"price": {"type": "number"}}, '
73
+ '"required": ["price"]}. For a list, wrap it in an object property. '
74
+ "No $ref, oneOf, anyOf or allOf. Leave empty for a text answer."
75
+ ),
76
+ )
77
+
78
+
79
+ class BrowsaTaskTool(BrowsaBaseTool):
80
+ """Run a plain-language task in a Phantom cloud browser and return the answer.
81
+
82
+ A browser agent on Browsa opens pages, clicks, types and reads, then
83
+ returns its answer. By default it runs on Browsa's hosted model tier
84
+ ``browsa`` (no model key needed, 5 extra credits per task). Pass your own
85
+ model with ``llm`` plus ``llm_api_key`` (or a saved ``llm_key_id``) to pay
86
+ your provider for tokens instead.
87
+
88
+ The result is JSON with ``result`` (``structured_output`` when an
89
+ ``output_schema`` was given, otherwise the agent's text answer),
90
+ ``outcome``, ``outcome_message``, ``job_id``, ``live_url`` and
91
+ ``credits_charged``. A task whose ``outcome`` is not a success (for example
92
+ ``failed`` with status ``completed``: the agent finished but could not do
93
+ the task) is reported as a tool failure.
94
+
95
+ Args:
96
+ api_key: Browsa API key; defaults to ``BROWSA_API_KEY``.
97
+ llm: Model. A hosted tier (``"browsa"``, ``"browsa-fast"``,
98
+ ``"browsa-smart"``) or your own, e.g.
99
+ ``"anthropic:claude-sonnet-5-5"``. Defaults to ``"browsa"``.
100
+ llm_api_key: Your own model provider key, used for this task only.
101
+ llm_key_id: A model key saved in the Browsa workspace.
102
+ reasoning: ``"low"``, ``"medium"`` or ``"high"``.
103
+ max_steps: Most agent steps (Browsa default 20, max 100).
104
+ max_credits: Most credits one task may charge.
105
+ output_schema: Default JSON Schema for every call; the agent's own
106
+ ``output_schema`` argument overrides it.
107
+ timeout: Seconds to wait for the task (default 600).
108
+ cancel_unfinished: Cancel the task when it is still running at
109
+ ``timeout`` or stops to ask a question (default True), so it does
110
+ not keep its browser.
111
+ task_options: Any other ``POST /v1/tasks`` fields, e.g.
112
+ ``{"allowed_domains": ["example.com"], "country": "US"}``.
113
+ """
114
+
115
+ name: str = "Browsa browser task"
116
+ description: str = (
117
+ "Runs a task in a real cloud web browser (Phantom, by Browsa) driven by a "
118
+ "browser agent: it opens websites, clicks, types, searches, scrolls and "
119
+ "reads, then returns the answer. Use it for anything that needs a live "
120
+ "website, interaction or several pages: comparing prices across stores, "
121
+ "searching a site, reading pages behind menus or forms. Describe the "
122
+ "whole job in one instruction and say what to return. Slower than "
123
+ "reading a single page, since the agent works step by step. Returns "
124
+ "JSON with result, outcome and live_url."
125
+ )
126
+ args_schema: type[BaseModel] = BrowsaTaskToolSchema
127
+
128
+ llm: str | None = "browsa"
129
+ llm_api_key: str | None = Field(default=None, repr=False, exclude=True)
130
+ llm_key_id: str | None = None
131
+ reasoning: Literal["low", "medium", "high"] | None = None
132
+ max_steps: int | None = Field(default=None, ge=1, le=100)
133
+ max_credits: int | None = None
134
+ output_schema: dict[str, Any] | None = None
135
+ timeout: float = 600.0
136
+ poll_wait: int = Field(default=30, ge=1, le=120)
137
+ cancel_unfinished: bool = True
138
+ task_options: dict[str, Any] = Field(default_factory=dict)
139
+
140
+ def _run(
141
+ self,
142
+ task: str,
143
+ start_url: str | None = None,
144
+ output_schema: dict[str, Any] | None = None,
145
+ **_: Any,
146
+ ) -> Any:
147
+ schema = output_schema or self.output_schema
148
+ body: dict[str, Any] = dict(self.task_options)
149
+ for key, value in {
150
+ "llm": self.llm,
151
+ "llm_api_key": self.llm_api_key,
152
+ "llm_key_id": self.llm_key_id,
153
+ "reasoning": self.reasoning,
154
+ "max_steps": self.max_steps,
155
+ "max_credits": self.max_credits,
156
+ "initial_url": start_url,
157
+ "output_schema": schema,
158
+ }.items():
159
+ if value is not None:
160
+ body[key] = value
161
+
162
+ try:
163
+ job = self.client.create_task(task=task, **body)
164
+ except BrowsaError as err:
165
+ return failure_from_error("task", err)
166
+
167
+ live_url = job.live_url
168
+ deadline = time.monotonic() + self.timeout
169
+ try:
170
+ while job.status not in _TERMINAL:
171
+ if job.status == "input_required":
172
+ return self._stop_unfinished(
173
+ job,
174
+ live_url,
175
+ "The browser agent stopped to ask a question this tool cannot answer.",
176
+ code="INPUT_REQUIRED",
177
+ )
178
+ remaining = deadline - time.monotonic()
179
+ if remaining <= 0:
180
+ return self._stop_unfinished(
181
+ job,
182
+ live_url,
183
+ f"The task did not finish within {self.timeout:g} seconds.",
184
+ code="TOOL_TIMEOUT",
185
+ )
186
+ wait = max(1, min(self.poll_wait, int(remaining)))
187
+ job = self.client.get_job(job.id, wait=wait)
188
+ live_url = live_url or job.live_url
189
+ except BrowsaError as err:
190
+ return failure_from_error("task", err)
191
+
192
+ return self._report(job, live_url)
193
+
194
+ async def _arun(self, *args: Any, **kwargs: Any) -> Any:
195
+ return await asyncio.to_thread(self._run, *args, **kwargs)
196
+
197
+ def _stop_unfinished(self, job: Any, live_url: str | None, message: str, *, code: str) -> Any:
198
+ cancelled = False
199
+ if self.cancel_unfinished:
200
+ try:
201
+ self.client.cancel_job(job.id)
202
+ cancelled = True
203
+ except BrowsaError:
204
+ cancelled = False
205
+ tail = " It was cancelled." if cancelled else " It is still running on Browsa."
206
+ return failure(
207
+ message + tail,
208
+ code=code,
209
+ retryable=code == "TOOL_TIMEOUT",
210
+ details={
211
+ "job_id": job.id,
212
+ "status": job.status,
213
+ "question": job.input_question,
214
+ "live_url": live_url,
215
+ "cancelled": cancelled,
216
+ },
217
+ )
218
+
219
+ @staticmethod
220
+ def _report(job: Any, live_url: str | None) -> Any:
221
+ raw_result = job.raw.get("result") if isinstance(job.raw, dict) else None
222
+ raw_result = raw_result if isinstance(raw_result, dict) else {}
223
+ structured = raw_result.get("structured_output")
224
+ answer = structured if structured is not None else job.final_result
225
+
226
+ outcome = job.outcome or (
227
+ "completed" if job.status == "completed" and not job.error_code else None
228
+ )
229
+ report: dict[str, Any] = {
230
+ "result": answer,
231
+ "status": job.status,
232
+ "outcome": outcome,
233
+ "outcome_message": job.outcome_message,
234
+ "partial": outcome in _PARTIAL_OUTCOMES,
235
+ "job_id": job.id,
236
+ "live_url": live_url,
237
+ "credits_charged": job.credits_charged,
238
+ }
239
+ if raw_result.get("purchase_blocked"):
240
+ report["purchase_blocked"] = raw_result["purchase_blocked"]
241
+ if job.signals:
242
+ report["signals"] = job.signals
243
+
244
+ # Read the outcome, not only the status: "completed" with outcome
245
+ # "failed" means the agent finished but could not do the task.
246
+ succeeded = job.status == "completed" and (
247
+ outcome == "completed" or (outcome in _PARTIAL_OUTCOMES and answer)
248
+ )
249
+ if succeeded:
250
+ return _dumps({k: v for k, v in report.items() if v is not None})
251
+
252
+ report["error_code"] = job.error_code
253
+ report["error_message"] = job.error_message
254
+ message = job.outcome_message or job.error_message or "The browser task did not succeed."
255
+ return failure(
256
+ f"Browsa task ended with outcome '{outcome or job.status}': {message}",
257
+ code=job.error_code or outcome,
258
+ retryable=outcome in ("stalled", "timed_out", "blocked_by_bot_check"),
259
+ details=report,
260
+ )
261
+
262
+
263
+ # ── BrowsaScrapeTool ───────────────────────────────────────────────────────
264
+
265
+ ScrapeFormat = Literal["markdown", "html", "text", "links"]
266
+
267
+
268
+ def _default_formats() -> list[ScrapeFormat]:
269
+ return ["markdown", "links"]
270
+
271
+
272
+ class BrowsaScrapeToolSchema(BaseModel):
273
+ """Input for BrowsaScrapeTool."""
274
+
275
+ url: str = Field(
276
+ ..., description="Full URL of the page to read, starting with http:// or https://."
277
+ )
278
+
279
+
280
+ class BrowsaScrapeTool(BrowsaBaseTool):
281
+ """Open one URL in a Phantom cloud browser and return the rendered page.
282
+
283
+ No model involved; 1 credit per page. Returns the page as Markdown by
284
+ default (JavaScript runs first, so single-page apps work).
285
+
286
+ Args:
287
+ api_key: Browsa API key; defaults to ``BROWSA_API_KEY``.
288
+ formats: Any of ``"markdown"``, ``"html"``, ``"text"``, ``"links"``.
289
+ Default ``["markdown", "links"]``.
290
+ max_chars: Cap on text and Markdown (Browsa default 100000; here 30000
291
+ to keep the agent's context small).
292
+ wait_ms: Extra settle time after load, in milliseconds.
293
+ country: ISO-2 country; see Browsa's proxy docs.
294
+ block: Resource types to block, e.g. ``["image", "font", "media"]``.
295
+ max_links: Most links listed in the output (default 100).
296
+ """
297
+
298
+ name: str = "Browsa scrape page"
299
+ description: str = (
300
+ "Reads one web page in a real cloud browser (Phantom, by Browsa) and "
301
+ "returns its rendered content as Markdown plus the page's links. "
302
+ "JavaScript runs first, so dynamic pages work. Use it to read a known "
303
+ "URL; it does not click or type. Input: the full URL."
304
+ )
305
+ args_schema: type[BaseModel] = BrowsaScrapeToolSchema
306
+
307
+ formats: list[ScrapeFormat] = Field(default_factory=_default_formats)
308
+ max_chars: int | None = 30000
309
+ wait_ms: int | None = Field(default=None, ge=0, le=60000)
310
+ country: str | None = None
311
+ block: list[str] | None = None
312
+ max_links: int = 100
313
+
314
+ def _run(self, url: str, **_: Any) -> Any:
315
+ opts: dict[str, Any] = {"formats": list(self.formats)}
316
+ for key, value in {
317
+ "max_chars": self.max_chars,
318
+ "wait_ms": self.wait_ms,
319
+ "country": self.country,
320
+ "block": self.block,
321
+ }.items():
322
+ if value is not None:
323
+ opts[key] = value
324
+ try:
325
+ page = self.client.scrape(url, **opts)
326
+ except BrowsaError as err:
327
+ return failure_from_error("scrape", err)
328
+ if not isinstance(page, dict):
329
+ return failure("Browsa scrape returned no page.", details={"url": url})
330
+
331
+ parts = [f"URL: {page.get('url') or url}"]
332
+ if page.get("http_status") is not None:
333
+ parts.append(f"HTTP status: {page['http_status']}")
334
+ for fmt in ("markdown", "text", "html"):
335
+ if fmt in self.formats and page.get(fmt):
336
+ parts.append(f"\n{_truncate(str(page[fmt]), self.max_chars)}")
337
+ links = page.get("links") or []
338
+ if "links" in self.formats and links:
339
+ shown = links[: self.max_links]
340
+ more = f" (first {len(shown)} of {len(links)})" if len(links) > len(shown) else ""
341
+ parts.append(f"\nLinks{more}:\n" + "\n".join(f"- {link}" for link in shown))
342
+ return "\n".join(parts)
343
+
344
+ async def _arun(self, *args: Any, **kwargs: Any) -> Any:
345
+ return await asyncio.to_thread(self._run, *args, **kwargs)
346
+
347
+
348
+ # ── BrowsaExtractTool ──────────────────────────────────────────────────────
349
+
350
+
351
+ class BrowsaExtractToolSchema(BaseModel):
352
+ """Input for BrowsaExtractTool."""
353
+
354
+ url: str = Field(..., description="Full URL of the page to extract data from.")
355
+ prompt: str | None = Field(
356
+ default=None,
357
+ description="What to extract, in plain language, e.g. 'product name, price and stock status'.",
358
+ )
359
+ extraction_schema: dict[str, Any] | None = Field(
360
+ default=None,
361
+ description=(
362
+ "Optional JSON Schema of the fields to extract, e.g. "
363
+ '{"type": "object", "properties": {"price": {"type": "number"}}}. '
364
+ "Give this or prompt (the schema wins if both are given)."
365
+ ),
366
+ )
367
+
368
+
369
+ class BrowsaExtractTool(BrowsaBaseTool):
370
+ """Extract structured data from one page rendered in a Phantom cloud browser.
371
+
372
+ 1 credit per page. With ``llm_api_key`` (an Anthropic or
373
+ Anthropic-compatible key) or a saved ``llm_key_id``, Browsa runs the
374
+ extraction and the tool returns the extracted JSON; your provider bills
375
+ the tokens. Without a key, Browsa returns the page's clean text and the
376
+ schema, and the tool hands both to your crew's own model to fill in.
377
+
378
+ Args:
379
+ api_key: Browsa API key; defaults to ``BROWSA_API_KEY``.
380
+ llm_api_key: Anthropic(-compatible) key, used in memory for the call.
381
+ llm_key_id: An Anthropic key saved in the Browsa workspace.
382
+ llm: Model, e.g. ``"anthropic:claude-sonnet-5-5"``.
383
+ llm_base_url: Anthropic-compatible proxy base URL.
384
+ max_chars: Cap on page text returned when there is no key (30000).
385
+ wait_ms: Extra settle time after load, in milliseconds.
386
+ country: ISO-2 country.
387
+ """
388
+
389
+ name: str = "Browsa extract data"
390
+ description: str = (
391
+ "Extracts specific fields from one web page rendered in a real cloud "
392
+ "browser (Phantom, by Browsa), e.g. a product's name, price and "
393
+ "availability. Input: the URL plus a prompt describing the fields or a "
394
+ "JSON Schema. Returns JSON, or the page text and schema for you to "
395
+ "read the fields from."
396
+ )
397
+ args_schema: type[BaseModel] = BrowsaExtractToolSchema
398
+
399
+ llm_api_key: str | None = Field(default=None, repr=False, exclude=True)
400
+ llm_key_id: str | None = None
401
+ llm: str | None = None
402
+ llm_base_url: str | None = None
403
+ max_chars: int | None = 30000
404
+ wait_ms: int | None = Field(default=None, ge=0, le=60000)
405
+ country: str | None = None
406
+
407
+ def _run(
408
+ self,
409
+ url: str,
410
+ prompt: str | None = None,
411
+ extraction_schema: dict[str, Any] | None = None,
412
+ **_: Any,
413
+ ) -> Any:
414
+ if not prompt and not extraction_schema:
415
+ return failure(
416
+ "Give either prompt (what to extract) or extraction_schema (a JSON Schema).",
417
+ code="BAD_REQUEST",
418
+ )
419
+ opts: dict[str, Any] = {}
420
+ for key, value in {
421
+ "llm_api_key": self.llm_api_key,
422
+ "llm_key_id": self.llm_key_id,
423
+ "llm": self.llm,
424
+ "llm_base_url": self.llm_base_url,
425
+ "wait_ms": self.wait_ms,
426
+ "country": self.country,
427
+ }.items():
428
+ if value is not None:
429
+ opts[key] = value
430
+ try:
431
+ out = self.client.extract(url, schema=extraction_schema, prompt=prompt, **opts)
432
+ except BrowsaError as err:
433
+ return failure_from_error("extract", err)
434
+ if not isinstance(out, dict):
435
+ return failure("Browsa extract returned nothing.", details={"url": url})
436
+
437
+ if out.get("data") is not None:
438
+ return _dumps({"url": out.get("url") or url, "data": out["data"]})
439
+
440
+ # No model key: Browsa returns the clean text and the schema so the
441
+ # calling model can read the fields itself.
442
+ lines = [
443
+ f"URL: {out.get('url') or url}",
444
+ "Read the requested fields from the page text below.",
445
+ ]
446
+ if prompt:
447
+ lines.append(f"Requested: {prompt}")
448
+ if out.get("schema"):
449
+ lines.append("Schema:\n" + _dumps(out["schema"]))
450
+ lines.append("Page text:\n" + _truncate(str(out.get("text") or ""), self.max_chars))
451
+ return "\n".join(lines)
452
+
453
+ async def _arun(self, *args: Any, **kwargs: Any) -> Any:
454
+ return await asyncio.to_thread(self._run, *args, **kwargs)
455
+
456
+
457
+ # ── BrowsaScreenshotTool ───────────────────────────────────────────────────
458
+
459
+
460
+ class BrowsaScreenshotToolSchema(BaseModel):
461
+ """Input for BrowsaScreenshotTool."""
462
+
463
+ url: str = Field(..., description="Full URL of the page to capture.")
464
+ full_page: bool = Field(
465
+ default=True,
466
+ description="True for the full scrollable page, False for the visible viewport only.",
467
+ )
468
+
469
+
470
+ class BrowsaScreenshotTool(BrowsaBaseTool):
471
+ """Capture a PNG of a page in a Phantom cloud browser and save it to disk.
472
+
473
+ 1 credit per page. The PNG is written to ``output_dir`` and the tool
474
+ returns its path (a base64 image would fill the agent's context).
475
+
476
+ Args:
477
+ api_key: Browsa API key; defaults to ``BROWSA_API_KEY``.
478
+ output_dir: Folder for the PNG files (default ``browsa_screenshots``).
479
+ wait_ms: Extra settle time after load, in milliseconds.
480
+ country: ISO-2 country.
481
+ """
482
+
483
+ name: str = "Browsa screenshot page"
484
+ description: str = (
485
+ "Takes a PNG screenshot of a web page in a real cloud browser (Phantom, "
486
+ "by Browsa) and saves it to a file. Returns the file path. Use it when "
487
+ "you need an image of how a page looks. Input: the URL and whether to "
488
+ "capture the full page."
489
+ )
490
+ args_schema: type[BaseModel] = BrowsaScreenshotToolSchema
491
+
492
+ output_dir: str = "browsa_screenshots"
493
+ wait_ms: int | None = None
494
+ country: str | None = None
495
+
496
+ def _run(self, url: str, full_page: bool = True, **_: Any) -> Any:
497
+ opts: dict[str, Any] = {}
498
+ if self.wait_ms is not None:
499
+ opts["wait_ms"] = self.wait_ms
500
+ if self.country is not None:
501
+ opts["country"] = self.country
502
+ try:
503
+ out = self.client.screenshot(url, full_page=full_page, **opts)
504
+ except BrowsaError as err:
505
+ return failure_from_error("screenshot", err)
506
+ b64 = out.get("screenshot_png_b64") if isinstance(out, dict) else None
507
+ if not b64:
508
+ return failure("Browsa returned no screenshot.", details={"url": url})
509
+ try:
510
+ png = base64.b64decode(b64)
511
+ except ValueError:
512
+ return failure(
513
+ "Browsa returned a screenshot that is not valid base64.", details={"url": url}
514
+ )
515
+
516
+ folder = Path(self.output_dir)
517
+ folder.mkdir(parents=True, exist_ok=True)
518
+ slug = (
519
+ re.sub(r"[^A-Za-z0-9]+", "-", re.sub(r"^https?://", "", url)).strip("-")[:60] or "page"
520
+ )
521
+ path = folder / f"{slug}-{int(time.time() * 1000)}.png"
522
+ path.write_bytes(png)
523
+ return _dumps(
524
+ {
525
+ "url": out.get("url") or url,
526
+ "path": str(path.resolve()),
527
+ "bytes": len(png),
528
+ "full_page": full_page,
529
+ }
530
+ )
531
+
532
+ async def _arun(self, *args: Any, **kwargs: Any) -> Any:
533
+ return await asyncio.to_thread(self._run, *args, **kwargs)
534
+
535
+
536
+ __all__ = [
537
+ "BrowsaExtractTool",
538
+ "BrowsaExtractToolSchema",
539
+ "BrowsaScrapeTool",
540
+ "BrowsaScrapeToolSchema",
541
+ "BrowsaScreenshotTool",
542
+ "BrowsaScreenshotToolSchema",
543
+ "BrowsaTaskTool",
544
+ "BrowsaTaskToolSchema",
545
+ ]
@@ -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,9 @@
1
+ crewai_browsa/__init__.py,sha256=ojSOxmfM_fiLK_7X6fFm0o2fI4Bl0VBo8nfOp4Uv28o,951
2
+ crewai_browsa/_common.py,sha256=VtHh6Nt4QRLuYUnrleR0-Nhb8QzZN7RkgHgIRgIzIus,4469
3
+ crewai_browsa/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
4
+ crewai_browsa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
5
+ crewai_browsa/tools.py,sha256=pjeZYwC6Wl3qBJNmjLmu4XQ4qT__A2zL0t2PsI6UrWo,22267
6
+ crewai_browsa-0.1.0.dist-info/METADATA,sha256=85kKrtqbzavmgtXvc7S8bcMYpJqpQPrOOuI86mpvmGI,12317
7
+ crewai_browsa-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
8
+ crewai_browsa-0.1.0.dist-info/licenses/LICENSE,sha256=7YFYXLNvS542_L-8Jes5n9edZ3BvdBA3HX5GuZyl6jM,1080
9
+ crewai_browsa-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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.