langchain-browsa 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- langchain_browsa-0.1.0/LICENSE +21 -0
- langchain_browsa-0.1.0/PKG-INFO +276 -0
- langchain_browsa-0.1.0/README.md +241 -0
- langchain_browsa-0.1.0/langchain_browsa/__init__.py +27 -0
- langchain_browsa-0.1.0/langchain_browsa/_common.py +148 -0
- langchain_browsa-0.1.0/langchain_browsa/document_loaders.py +227 -0
- langchain_browsa-0.1.0/langchain_browsa/py.typed +0 -0
- langchain_browsa-0.1.0/langchain_browsa/toolkits.py +89 -0
- langchain_browsa-0.1.0/langchain_browsa/tools.py +609 -0
- langchain_browsa-0.1.0/langchain_browsa.egg-info/PKG-INFO +276 -0
- langchain_browsa-0.1.0/langchain_browsa.egg-info/SOURCES.txt +14 -0
- langchain_browsa-0.1.0/langchain_browsa.egg-info/dependency_links.txt +1 -0
- langchain_browsa-0.1.0/langchain_browsa.egg-info/requires.txt +10 -0
- langchain_browsa-0.1.0/langchain_browsa.egg-info/top_level.txt +1 -0
- langchain_browsa-0.1.0/pyproject.toml +60 -0
- langchain_browsa-0.1.0/setup.cfg +4 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Browsa Technologies LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: langchain-browsa
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: LangChain integration for Browsa: Phantom cloud browsers for AI agents (browsa.io)
|
|
5
|
+
Author-email: Browsa <support@browsa.io>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://browsa.io
|
|
8
|
+
Project-URL: Documentation, https://browsa.io/docs
|
|
9
|
+
Project-URL: Source, https://github.com/browsa-io/browsa/tree/main/integrations/langchain-browsa
|
|
10
|
+
Project-URL: Issues, https://github.com/browsa-io/browsa/issues
|
|
11
|
+
Keywords: langchain,langgraph,browsa,browser-automation,ai-agents,web-scraping,cloud-browser
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: browsa>=0.3.1
|
|
26
|
+
Requires-Dist: langchain-core<2.0.0,>=1.0.0
|
|
27
|
+
Requires-Dist: typing-extensions>=4.7
|
|
28
|
+
Provides-Extra: test
|
|
29
|
+
Requires-Dist: pytest>=8; extra == "test"
|
|
30
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
|
|
31
|
+
Requires-Dist: pytest-socket>=0.7; extra == "test"
|
|
32
|
+
Requires-Dist: langchain-tests==1.1.9; extra == "test"
|
|
33
|
+
Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "test"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# langchain-browsa
|
|
37
|
+
|
|
38
|
+
LangChain tools and a document loader for [Browsa](https://browsa.io), cloud browsers for AI agents. Every call runs in Phantom, Browsa's own browser, in the cloud: your agent gets a real browser without running one.
|
|
39
|
+
|
|
40
|
+
| Class | What it does | Browsa endpoint |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| `BrowsaTaskTool` | Runs a plain-language task: an agent clicks, types and reads pages until it has the answer | `POST /v1/tasks` |
|
|
43
|
+
| `BrowsaScrapeTool` | Returns one page as Markdown, HTML, text or links | `POST /v1/quick/scrape` |
|
|
44
|
+
| `BrowsaExtractTool` | Returns structured data from one page | `POST /v1/quick/extract` |
|
|
45
|
+
| `BrowsaScreenshotTool` | Returns a PNG of one page | `POST /v1/quick/screenshot` |
|
|
46
|
+
| `BrowsaLoader` | Loads pages as LangChain `Document`s (scrape, batch or crawl) | `/v1/quick/scrape`, `/batch`, `/crawl` |
|
|
47
|
+
| `BrowsaToolkit` | All four tools, sharing one client | |
|
|
48
|
+
|
|
49
|
+
Built on the official Python SDK, [`browsa`](https://pypi.org/project/browsa/). Full API docs: <https://browsa.io/docs>.
|
|
50
|
+
|
|
51
|
+
## Install
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install -U langchain-browsa
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Python 3.10 or newer. Get an API key (it starts with `agt_live_`) at <https://app.browsa.io/dashboard/keys>; new accounts get 100 free credits after email verification, with no card.
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
export BROWSA_API_KEY="agt_live_..."
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Every class reads `BROWSA_API_KEY`, or takes `api_key="agt_live_..."`.
|
|
64
|
+
|
|
65
|
+
## Quickstart: an agent with a browser
|
|
66
|
+
|
|
67
|
+
`create_agent` from `langchain` builds a LangGraph agent. Give it the Browsa tools:
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
# pip install -U langchain-browsa "langchain[anthropic]"
|
|
71
|
+
from langchain.agents import create_agent
|
|
72
|
+
from langchain_browsa import BrowsaToolkit
|
|
73
|
+
|
|
74
|
+
agent = create_agent(
|
|
75
|
+
model="claude-sonnet-4-6",
|
|
76
|
+
tools=BrowsaToolkit().get_tools(),
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
result = agent.invoke(
|
|
80
|
+
{"messages": [{"role": "user", "content": "What is the top story on news.ycombinator.com right now?"}]}
|
|
81
|
+
)
|
|
82
|
+
print(result["messages"][-1].content)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The browser task itself runs on Browsa's hosted model tier `browsa` by default, so you need no second LLM key for it. Your agent's own model (here Claude) only decides which tool to call.
|
|
86
|
+
|
|
87
|
+
## Tools
|
|
88
|
+
|
|
89
|
+
### BrowsaTaskTool
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
from langchain_browsa import BrowsaTaskTool
|
|
93
|
+
|
|
94
|
+
tool = BrowsaTaskTool()
|
|
95
|
+
out = tool.invoke({"task": "Open example.com and return the text of the H1 heading."})
|
|
96
|
+
|
|
97
|
+
print(out["outcome"], out["final_result"])
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Arguments the model fills: `task` (required) and `initial_url` (optional).
|
|
101
|
+
|
|
102
|
+
The result is a dict:
|
|
103
|
+
|
|
104
|
+
| Key | Meaning |
|
|
105
|
+
|---|---|
|
|
106
|
+
| `status` | The run ended: `completed`, `failed` or `cancelled` |
|
|
107
|
+
| `outcome` | How it ended: `completed`, `failed`, `step_limit_reached`, `budget_reached`, `timed_out`, `blocked_by_bot_check`, `never_started`, `stalled`, `cancelled_by_user` |
|
|
108
|
+
| `succeeded` | `True` only when `status` and `outcome` are both `completed` and the result is not partial |
|
|
109
|
+
| `final_result` | The agent's answer |
|
|
110
|
+
| `structured_output` | The answer as an object, when you set `output_schema` |
|
|
111
|
+
| `outcome_message`, `error_code`, `error_message`, `signals` | Why it ended the way it did, when there is something to say |
|
|
112
|
+
| `job_id`, `step_count`, `credits_charged`, `duration_ms` | Bookkeeping |
|
|
113
|
+
| `live_url` | The Phantom Live link of the run (see below) |
|
|
114
|
+
|
|
115
|
+
Read `outcome`, not only `status`. A job can be `completed` with outcome `failed`: the agent finished but could not do the task, and `final_result` says what stopped it. A task that a limit stopped can be `completed` with a partial result and outcome `step_limit_reached`.
|
|
116
|
+
|
|
117
|
+
`live_url` is a Phantom Live link to watch the browser. It works only while the task runs and opens once, so to watch a run, pass a callback:
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
tool = BrowsaTaskTool(on_live_url=lambda url: print("watch live:", url))
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Options (all optional):
|
|
124
|
+
|
|
125
|
+
| Option | Default | Meaning |
|
|
126
|
+
|---|---|---|
|
|
127
|
+
| `llm` | `"browsa"` | A hosted tier (`"browsa"`, `"browsa-fast"`, `"browsa-smart"`, no key needed) or a provider model such as `"anthropic:claude-sonnet-5-5"` |
|
|
128
|
+
| `llm_api_key` | | Your own Anthropic, OpenAI or Google key for this task. Browsa deletes it when the task ends |
|
|
129
|
+
| `llm_key_id` | | A key saved in your Browsa workspace instead |
|
|
130
|
+
| `llm_base_url` | | An Anthropic- or OpenAI-compatible endpoint for your own key |
|
|
131
|
+
| `reasoning` | | `"low"`, `"medium"` or `"high"` |
|
|
132
|
+
| `output_schema` | | JSON Schema (an object at the top level) for the answer; the answer comes back in `structured_output` |
|
|
133
|
+
| `max_steps` | API default 20 | Most agent steps (max 100) |
|
|
134
|
+
| `max_credits` | | Most credits the task may charge; it stops before going over |
|
|
135
|
+
| `allowed_domains` | | The only sites the agent may open, e.g. `["example.com", "*.example.com"]` |
|
|
136
|
+
| `task_options` | `{}` | Any other `browsa.Client.create_task` option, e.g. `country`, `proxy`, `proxy_id`, `secrets` |
|
|
137
|
+
| `wait_timeout` | `600` | Seconds to wait for the task; after that the tool raises a `ToolException` with the job id (the task keeps running) |
|
|
138
|
+
|
|
139
|
+
Structured output:
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
tool = BrowsaTaskTool(
|
|
143
|
+
llm="browsa-smart",
|
|
144
|
+
output_schema={
|
|
145
|
+
"type": "object",
|
|
146
|
+
"properties": {"title": {"type": "string"}, "points": {"type": "integer"}},
|
|
147
|
+
"required": ["title", "points"],
|
|
148
|
+
},
|
|
149
|
+
max_credits=20,
|
|
150
|
+
)
|
|
151
|
+
out = tool.invoke({"task": "Return the title and points of the top story on news.ycombinator.com"})
|
|
152
|
+
print(out["structured_output"])
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
The schema is stored on the tool as `task_output_schema`, because `output_schema` is already a LangChain `Runnable` property.
|
|
156
|
+
|
|
157
|
+
With your own model key:
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
import os
|
|
161
|
+
|
|
162
|
+
tool = BrowsaTaskTool(llm="anthropic:claude-sonnet-5-5", llm_api_key=os.environ["ANTHROPIC_API_KEY"])
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### BrowsaScrapeTool
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
from langchain_browsa import BrowsaScrapeTool
|
|
169
|
+
|
|
170
|
+
page = BrowsaScrapeTool().invoke({"url": "https://example.com"})
|
|
171
|
+
print(page["http_status"], page["markdown"][:200])
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Arguments: `url`, and `formats` (any of `markdown`, `html`, `text`, `links`; default `markdown`). Options: `formats`, `wait_ms`, `max_chars`, `country`, `block`, `scrape_options`. No LLM is involved. Check `http_status`: a site that answers 404 or 500 still returns a page.
|
|
175
|
+
|
|
176
|
+
### BrowsaExtractTool
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
from langchain_browsa import BrowsaExtractTool
|
|
180
|
+
|
|
181
|
+
tool = BrowsaExtractTool(llm_api_key="sk-ant-...")
|
|
182
|
+
out = tool.invoke({"url": "https://example.com", "prompt": "Return the page heading and the first link."})
|
|
183
|
+
print(out["data"])
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Arguments: `url`, and `prompt` or `json_schema`. The extraction model is Anthropic: give an Anthropic(-compatible) key with `llm_api_key`, or a saved key with `llm_key_id`, and the result has `data`. Without a key, the result has the page's clean `text` and the `schema`, so your own model can do the extraction. Options: `json_schema` (default schema), `llm`, `llm_base_url`, `wait_ms`, `country`, `block`, `extract_options`.
|
|
187
|
+
|
|
188
|
+
### BrowsaScreenshotTool
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
from langchain_browsa import BrowsaScreenshotTool
|
|
192
|
+
|
|
193
|
+
tool = BrowsaScreenshotTool()
|
|
194
|
+
msg = tool.invoke({"name": tool.name, "type": "tool_call", "id": "1", "args": {"url": "https://example.com"}})
|
|
195
|
+
png_b64 = msg.artifact["screenshot_png_b64"]
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Arguments: `url` and `full_page` (default `True`). The tool returns content and an artifact: the model gets a short text, and the PNG (base64) is in `ToolMessage.artifact`. Set `include_image=True` to also put the image in the content, for models that accept images in tool results.
|
|
199
|
+
|
|
200
|
+
### BrowsaLoader
|
|
201
|
+
|
|
202
|
+
```python
|
|
203
|
+
from langchain_browsa import BrowsaLoader
|
|
204
|
+
|
|
205
|
+
docs = BrowsaLoader("https://example.com").load()
|
|
206
|
+
|
|
207
|
+
docs = BrowsaLoader(["https://example.com", "https://example.org"], mode="batch").load()
|
|
208
|
+
|
|
209
|
+
docs = BrowsaLoader(
|
|
210
|
+
"https://docs.example.com",
|
|
211
|
+
mode="crawl",
|
|
212
|
+
max_pages=20,
|
|
213
|
+
max_depth=2,
|
|
214
|
+
include_regex=r"/guides/",
|
|
215
|
+
).load()
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`mode` is `"scrape"` (one call per URL), `"batch"` (up to 100 URLs as one job) or `"crawl"` (follow links from one start URL, up to `max_pages`). `page_content` is Markdown by default (`content_format="text"` or `"html"` to change it). Metadata: `source` (the URL the browser landed on), `requested_url`, `http_status`, `title` when known, `links` when you ask for the `links` format, `job_id` for batch and crawl, and `mode`. Pages that failed are skipped and logged. `lazy_load`, `load`, `alazy_load` and `aload` all work.
|
|
219
|
+
|
|
220
|
+
### BrowsaToolkit
|
|
221
|
+
|
|
222
|
+
```python
|
|
223
|
+
from langchain_browsa import BrowsaToolkit
|
|
224
|
+
|
|
225
|
+
tools = BrowsaToolkit(
|
|
226
|
+
task_kwargs={"llm": "browsa-smart", "max_credits": 30},
|
|
227
|
+
include_screenshot=False,
|
|
228
|
+
).get_tools()
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### Async
|
|
232
|
+
|
|
233
|
+
Every tool supports `ainvoke` and the loader supports `alazy_load` / `aload`, through `browsa.AsyncClient`.
|
|
234
|
+
|
|
235
|
+
### Errors
|
|
236
|
+
|
|
237
|
+
API errors (bad key, no credits, rate limit) raise `langchain_core.tools.ToolException` with Browsa's error code and request id. To hand them to the model as the tool's answer instead, set `handle_tool_error=True` on the tool. A task that ran but did not succeed is not an error: it comes back with its `outcome`.
|
|
238
|
+
|
|
239
|
+
## Costs
|
|
240
|
+
|
|
241
|
+
Browsa bills in prepaid credits that never expire. From <https://browsa.io/pricing>:
|
|
242
|
+
|
|
243
|
+
| What you run | Credits |
|
|
244
|
+
|---|---|
|
|
245
|
+
| Cloud browser | 1 per started 12 minutes it runs, 5 for a full hour |
|
|
246
|
+
| Quick scrape, extract or screenshot | 1 per page |
|
|
247
|
+
| Batch of URLs | 1 per URL |
|
|
248
|
+
| Agent task, your own LLM key | browser + 1 + 1 per 5 steps |
|
|
249
|
+
| Agent task on a hosted tier (`"llm": "browsa"`, `"browsa-fast"` or `"browsa-smart"`) | browser + 1 + 1 per 5 steps + 5 |
|
|
250
|
+
|
|
251
|
+
Worked examples from the pricing page: 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. 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.
|
|
252
|
+
|
|
253
|
+
The tier credits are a server setting and can change; `browsa.Client(...).models()` returns the live values. Use `max_credits` on `BrowsaTaskTool` to cap what one task may spend.
|
|
254
|
+
|
|
255
|
+
Credit packs: Starter $20 for 200 credits, Growth $100 for 1,200 credits, Pro $500 for 7,500 credits. New accounts get 100 free credits after email verification.
|
|
256
|
+
|
|
257
|
+
## Development
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
pip install -e ".[test]"
|
|
261
|
+
pytest tests/unit_tests # offline: the HTTP layer is faked and sockets are disabled
|
|
262
|
+
BROWSA_API_KEY=agt_live_... pytest tests/integration_tests # live API, spends credits
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
The unit tests include LangChain's standard tool tests (`langchain-tests`), run offline.
|
|
266
|
+
|
|
267
|
+
## Links
|
|
268
|
+
|
|
269
|
+
- Browsa docs: <https://browsa.io/docs>
|
|
270
|
+
- Python SDK: <https://pypi.org/project/browsa/>
|
|
271
|
+
- Source: <https://github.com/browsa-io/browsa>
|
|
272
|
+
- Support: <mailto:support@browsa.io>
|
|
273
|
+
|
|
274
|
+
## License
|
|
275
|
+
|
|
276
|
+
MIT
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
# langchain-browsa
|
|
2
|
+
|
|
3
|
+
LangChain tools and a document loader for [Browsa](https://browsa.io), cloud browsers for AI agents. Every call runs in Phantom, Browsa's own browser, in the cloud: your agent gets a real browser without running one.
|
|
4
|
+
|
|
5
|
+
| Class | What it does | Browsa endpoint |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| `BrowsaTaskTool` | Runs a plain-language task: an agent clicks, types and reads pages until it has the answer | `POST /v1/tasks` |
|
|
8
|
+
| `BrowsaScrapeTool` | Returns one page as Markdown, HTML, text or links | `POST /v1/quick/scrape` |
|
|
9
|
+
| `BrowsaExtractTool` | Returns structured data from one page | `POST /v1/quick/extract` |
|
|
10
|
+
| `BrowsaScreenshotTool` | Returns a PNG of one page | `POST /v1/quick/screenshot` |
|
|
11
|
+
| `BrowsaLoader` | Loads pages as LangChain `Document`s (scrape, batch or crawl) | `/v1/quick/scrape`, `/batch`, `/crawl` |
|
|
12
|
+
| `BrowsaToolkit` | All four tools, sharing one client | |
|
|
13
|
+
|
|
14
|
+
Built on the official Python SDK, [`browsa`](https://pypi.org/project/browsa/). Full API docs: <https://browsa.io/docs>.
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
pip install -U langchain-browsa
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Python 3.10 or newer. Get an API key (it starts with `agt_live_`) at <https://app.browsa.io/dashboard/keys>; new accounts get 100 free credits after email verification, with no card.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
export BROWSA_API_KEY="agt_live_..."
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Every class reads `BROWSA_API_KEY`, or takes `api_key="agt_live_..."`.
|
|
29
|
+
|
|
30
|
+
## Quickstart: an agent with a browser
|
|
31
|
+
|
|
32
|
+
`create_agent` from `langchain` builds a LangGraph agent. Give it the Browsa tools:
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
# pip install -U langchain-browsa "langchain[anthropic]"
|
|
36
|
+
from langchain.agents import create_agent
|
|
37
|
+
from langchain_browsa import BrowsaToolkit
|
|
38
|
+
|
|
39
|
+
agent = create_agent(
|
|
40
|
+
model="claude-sonnet-4-6",
|
|
41
|
+
tools=BrowsaToolkit().get_tools(),
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
result = agent.invoke(
|
|
45
|
+
{"messages": [{"role": "user", "content": "What is the top story on news.ycombinator.com right now?"}]}
|
|
46
|
+
)
|
|
47
|
+
print(result["messages"][-1].content)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The browser task itself runs on Browsa's hosted model tier `browsa` by default, so you need no second LLM key for it. Your agent's own model (here Claude) only decides which tool to call.
|
|
51
|
+
|
|
52
|
+
## Tools
|
|
53
|
+
|
|
54
|
+
### BrowsaTaskTool
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from langchain_browsa import BrowsaTaskTool
|
|
58
|
+
|
|
59
|
+
tool = BrowsaTaskTool()
|
|
60
|
+
out = tool.invoke({"task": "Open example.com and return the text of the H1 heading."})
|
|
61
|
+
|
|
62
|
+
print(out["outcome"], out["final_result"])
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Arguments the model fills: `task` (required) and `initial_url` (optional).
|
|
66
|
+
|
|
67
|
+
The result is a dict:
|
|
68
|
+
|
|
69
|
+
| Key | Meaning |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `status` | The run ended: `completed`, `failed` or `cancelled` |
|
|
72
|
+
| `outcome` | How it ended: `completed`, `failed`, `step_limit_reached`, `budget_reached`, `timed_out`, `blocked_by_bot_check`, `never_started`, `stalled`, `cancelled_by_user` |
|
|
73
|
+
| `succeeded` | `True` only when `status` and `outcome` are both `completed` and the result is not partial |
|
|
74
|
+
| `final_result` | The agent's answer |
|
|
75
|
+
| `structured_output` | The answer as an object, when you set `output_schema` |
|
|
76
|
+
| `outcome_message`, `error_code`, `error_message`, `signals` | Why it ended the way it did, when there is something to say |
|
|
77
|
+
| `job_id`, `step_count`, `credits_charged`, `duration_ms` | Bookkeeping |
|
|
78
|
+
| `live_url` | The Phantom Live link of the run (see below) |
|
|
79
|
+
|
|
80
|
+
Read `outcome`, not only `status`. A job can be `completed` with outcome `failed`: the agent finished but could not do the task, and `final_result` says what stopped it. A task that a limit stopped can be `completed` with a partial result and outcome `step_limit_reached`.
|
|
81
|
+
|
|
82
|
+
`live_url` is a Phantom Live link to watch the browser. It works only while the task runs and opens once, so to watch a run, pass a callback:
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
tool = BrowsaTaskTool(on_live_url=lambda url: print("watch live:", url))
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Options (all optional):
|
|
89
|
+
|
|
90
|
+
| Option | Default | Meaning |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `llm` | `"browsa"` | A hosted tier (`"browsa"`, `"browsa-fast"`, `"browsa-smart"`, no key needed) or a provider model such as `"anthropic:claude-sonnet-5-5"` |
|
|
93
|
+
| `llm_api_key` | | Your own Anthropic, OpenAI or Google key for this task. Browsa deletes it when the task ends |
|
|
94
|
+
| `llm_key_id` | | A key saved in your Browsa workspace instead |
|
|
95
|
+
| `llm_base_url` | | An Anthropic- or OpenAI-compatible endpoint for your own key |
|
|
96
|
+
| `reasoning` | | `"low"`, `"medium"` or `"high"` |
|
|
97
|
+
| `output_schema` | | JSON Schema (an object at the top level) for the answer; the answer comes back in `structured_output` |
|
|
98
|
+
| `max_steps` | API default 20 | Most agent steps (max 100) |
|
|
99
|
+
| `max_credits` | | Most credits the task may charge; it stops before going over |
|
|
100
|
+
| `allowed_domains` | | The only sites the agent may open, e.g. `["example.com", "*.example.com"]` |
|
|
101
|
+
| `task_options` | `{}` | Any other `browsa.Client.create_task` option, e.g. `country`, `proxy`, `proxy_id`, `secrets` |
|
|
102
|
+
| `wait_timeout` | `600` | Seconds to wait for the task; after that the tool raises a `ToolException` with the job id (the task keeps running) |
|
|
103
|
+
|
|
104
|
+
Structured output:
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
tool = BrowsaTaskTool(
|
|
108
|
+
llm="browsa-smart",
|
|
109
|
+
output_schema={
|
|
110
|
+
"type": "object",
|
|
111
|
+
"properties": {"title": {"type": "string"}, "points": {"type": "integer"}},
|
|
112
|
+
"required": ["title", "points"],
|
|
113
|
+
},
|
|
114
|
+
max_credits=20,
|
|
115
|
+
)
|
|
116
|
+
out = tool.invoke({"task": "Return the title and points of the top story on news.ycombinator.com"})
|
|
117
|
+
print(out["structured_output"])
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
The schema is stored on the tool as `task_output_schema`, because `output_schema` is already a LangChain `Runnable` property.
|
|
121
|
+
|
|
122
|
+
With your own model key:
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
import os
|
|
126
|
+
|
|
127
|
+
tool = BrowsaTaskTool(llm="anthropic:claude-sonnet-5-5", llm_api_key=os.environ["ANTHROPIC_API_KEY"])
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### BrowsaScrapeTool
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
from langchain_browsa import BrowsaScrapeTool
|
|
134
|
+
|
|
135
|
+
page = BrowsaScrapeTool().invoke({"url": "https://example.com"})
|
|
136
|
+
print(page["http_status"], page["markdown"][:200])
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Arguments: `url`, and `formats` (any of `markdown`, `html`, `text`, `links`; default `markdown`). Options: `formats`, `wait_ms`, `max_chars`, `country`, `block`, `scrape_options`. No LLM is involved. Check `http_status`: a site that answers 404 or 500 still returns a page.
|
|
140
|
+
|
|
141
|
+
### BrowsaExtractTool
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
from langchain_browsa import BrowsaExtractTool
|
|
145
|
+
|
|
146
|
+
tool = BrowsaExtractTool(llm_api_key="sk-ant-...")
|
|
147
|
+
out = tool.invoke({"url": "https://example.com", "prompt": "Return the page heading and the first link."})
|
|
148
|
+
print(out["data"])
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Arguments: `url`, and `prompt` or `json_schema`. The extraction model is Anthropic: give an Anthropic(-compatible) key with `llm_api_key`, or a saved key with `llm_key_id`, and the result has `data`. Without a key, the result has the page's clean `text` and the `schema`, so your own model can do the extraction. Options: `json_schema` (default schema), `llm`, `llm_base_url`, `wait_ms`, `country`, `block`, `extract_options`.
|
|
152
|
+
|
|
153
|
+
### BrowsaScreenshotTool
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
from langchain_browsa import BrowsaScreenshotTool
|
|
157
|
+
|
|
158
|
+
tool = BrowsaScreenshotTool()
|
|
159
|
+
msg = tool.invoke({"name": tool.name, "type": "tool_call", "id": "1", "args": {"url": "https://example.com"}})
|
|
160
|
+
png_b64 = msg.artifact["screenshot_png_b64"]
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Arguments: `url` and `full_page` (default `True`). The tool returns content and an artifact: the model gets a short text, and the PNG (base64) is in `ToolMessage.artifact`. Set `include_image=True` to also put the image in the content, for models that accept images in tool results.
|
|
164
|
+
|
|
165
|
+
### BrowsaLoader
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
from langchain_browsa import BrowsaLoader
|
|
169
|
+
|
|
170
|
+
docs = BrowsaLoader("https://example.com").load()
|
|
171
|
+
|
|
172
|
+
docs = BrowsaLoader(["https://example.com", "https://example.org"], mode="batch").load()
|
|
173
|
+
|
|
174
|
+
docs = BrowsaLoader(
|
|
175
|
+
"https://docs.example.com",
|
|
176
|
+
mode="crawl",
|
|
177
|
+
max_pages=20,
|
|
178
|
+
max_depth=2,
|
|
179
|
+
include_regex=r"/guides/",
|
|
180
|
+
).load()
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
`mode` is `"scrape"` (one call per URL), `"batch"` (up to 100 URLs as one job) or `"crawl"` (follow links from one start URL, up to `max_pages`). `page_content` is Markdown by default (`content_format="text"` or `"html"` to change it). Metadata: `source` (the URL the browser landed on), `requested_url`, `http_status`, `title` when known, `links` when you ask for the `links` format, `job_id` for batch and crawl, and `mode`. Pages that failed are skipped and logged. `lazy_load`, `load`, `alazy_load` and `aload` all work.
|
|
184
|
+
|
|
185
|
+
### BrowsaToolkit
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
from langchain_browsa import BrowsaToolkit
|
|
189
|
+
|
|
190
|
+
tools = BrowsaToolkit(
|
|
191
|
+
task_kwargs={"llm": "browsa-smart", "max_credits": 30},
|
|
192
|
+
include_screenshot=False,
|
|
193
|
+
).get_tools()
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Async
|
|
197
|
+
|
|
198
|
+
Every tool supports `ainvoke` and the loader supports `alazy_load` / `aload`, through `browsa.AsyncClient`.
|
|
199
|
+
|
|
200
|
+
### Errors
|
|
201
|
+
|
|
202
|
+
API errors (bad key, no credits, rate limit) raise `langchain_core.tools.ToolException` with Browsa's error code and request id. To hand them to the model as the tool's answer instead, set `handle_tool_error=True` on the tool. A task that ran but did not succeed is not an error: it comes back with its `outcome`.
|
|
203
|
+
|
|
204
|
+
## Costs
|
|
205
|
+
|
|
206
|
+
Browsa bills in prepaid credits that never expire. From <https://browsa.io/pricing>:
|
|
207
|
+
|
|
208
|
+
| What you run | Credits |
|
|
209
|
+
|---|---|
|
|
210
|
+
| Cloud browser | 1 per started 12 minutes it runs, 5 for a full hour |
|
|
211
|
+
| Quick scrape, extract or screenshot | 1 per page |
|
|
212
|
+
| Batch of URLs | 1 per URL |
|
|
213
|
+
| Agent task, your own LLM key | browser + 1 + 1 per 5 steps |
|
|
214
|
+
| Agent task on a hosted tier (`"llm": "browsa"`, `"browsa-fast"` or `"browsa-smart"`) | browser + 1 + 1 per 5 steps + 5 |
|
|
215
|
+
|
|
216
|
+
Worked examples from the pricing page: 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. 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.
|
|
217
|
+
|
|
218
|
+
The tier credits are a server setting and can change; `browsa.Client(...).models()` returns the live values. Use `max_credits` on `BrowsaTaskTool` to cap what one task may spend.
|
|
219
|
+
|
|
220
|
+
Credit packs: Starter $20 for 200 credits, Growth $100 for 1,200 credits, Pro $500 for 7,500 credits. New accounts get 100 free credits after email verification.
|
|
221
|
+
|
|
222
|
+
## Development
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
pip install -e ".[test]"
|
|
226
|
+
pytest tests/unit_tests # offline: the HTTP layer is faked and sockets are disabled
|
|
227
|
+
BROWSA_API_KEY=agt_live_... pytest tests/integration_tests # live API, spends credits
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
The unit tests include LangChain's standard tool tests (`langchain-tests`), run offline.
|
|
231
|
+
|
|
232
|
+
## Links
|
|
233
|
+
|
|
234
|
+
- Browsa docs: <https://browsa.io/docs>
|
|
235
|
+
- Python SDK: <https://pypi.org/project/browsa/>
|
|
236
|
+
- Source: <https://github.com/browsa-io/browsa>
|
|
237
|
+
- Support: <mailto:support@browsa.io>
|
|
238
|
+
|
|
239
|
+
## License
|
|
240
|
+
|
|
241
|
+
MIT
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""LangChain integration for Browsa (https://browsa.io): Phantom cloud browsers for AI agents."""
|
|
2
|
+
|
|
3
|
+
from importlib import metadata
|
|
4
|
+
|
|
5
|
+
from langchain_browsa.document_loaders import BrowsaLoader
|
|
6
|
+
from langchain_browsa.toolkits import BrowsaToolkit
|
|
7
|
+
from langchain_browsa.tools import (
|
|
8
|
+
BrowsaExtractTool,
|
|
9
|
+
BrowsaScrapeTool,
|
|
10
|
+
BrowsaScreenshotTool,
|
|
11
|
+
BrowsaTaskTool,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
try:
|
|
15
|
+
__version__ = metadata.version("langchain-browsa")
|
|
16
|
+
except metadata.PackageNotFoundError: # running from a source checkout
|
|
17
|
+
__version__ = ""
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"BrowsaExtractTool",
|
|
21
|
+
"BrowsaLoader",
|
|
22
|
+
"BrowsaScrapeTool",
|
|
23
|
+
"BrowsaScreenshotTool",
|
|
24
|
+
"BrowsaTaskTool",
|
|
25
|
+
"BrowsaToolkit",
|
|
26
|
+
"__version__",
|
|
27
|
+
]
|