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.
- crewai_browsa/__init__.py +38 -0
- crewai_browsa/_common.py +136 -0
- crewai_browsa/_version.py +1 -0
- crewai_browsa/py.typed +0 -0
- crewai_browsa/tools.py +545 -0
- crewai_browsa-0.1.0.dist-info/METADATA +277 -0
- crewai_browsa-0.1.0.dist-info/RECORD +9 -0
- crewai_browsa-0.1.0.dist-info/WHEEL +4 -0
- crewai_browsa-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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
|
+
]
|
crewai_browsa/_common.py
ADDED
|
@@ -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,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.
|