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.
@@ -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
+ ]