Skip to content

Commit 9e383c7

Browse files
bboynton97bboynton97
authored
Merge pull request #346 from shrisukhani/feat-add-hyperbrowser-tools
Add hyperbrowser tools
2 parents 12f02c9 + ca0becd commit 9e383c7

File tree

4 files changed

+413
-1
lines changed

4 files changed

+413
-1
lines changed

‎agentstack/_tools/hyperbrowser/__init__.py

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
import os
2+
from typing import List
3+
4+
from hyperbrowser import Hyperbrowser
5+
from hyperbrowser.models import (
6+
BrowserUseTaskResponse,
7+
ClaudeComputerUseTaskResponse,
8+
CrawlJobResponse,
9+
CreateSessionParams,
10+
CuaTaskResponse,
11+
ExtractJobResponse,
12+
ScrapeFormat,
13+
ScrapeJobResponse,
14+
ScrapeOptions,
15+
StartBrowserUseTaskParams,
16+
StartClaudeComputerUseTaskParams,
17+
StartCrawlJobParams,
18+
StartCuaTaskParams,
19+
StartExtractJobParams,
20+
StartScrapeJobParams,
21+
)
22+
23+
hb = Hyperbrowser(api_key=os.getenv('HYPERBROWSER_API_KEY'))
24+
25+
26+
def scrape_webpage(
27+
url: str, use_proxy: bool = True, formats: list[ScrapeFormat] = ["markdown"]
28+
) -> ScrapeJobResponse:
29+
"""
30+
Scrapes content from a single webpage in specified formats.
31+
32+
This function initiates a scraping job for a given URL and waits for completion.
33+
It configures a browser session with proxy and stealth options for optimal scraping.
34+
35+
Args:
36+
url: The URL of the webpage to scrape
37+
use_proxy: Whether to use a proxy for the request (default: True)
38+
formats: List of formats to return the scraped content in (default: ["markdown"])
39+
Options include "markdown", "html", "links", "screenshot"
40+
41+
Returns:
42+
ScrapeJobResponse: The response containing the scraped content in requested formats
43+
"""
44+
return hb.scrape.start_and_wait(
45+
StartScrapeJobParams(
46+
url=url,
47+
session_options=CreateSessionParams(
48+
use_proxy=use_proxy,
49+
use_stealth=True,
50+
adblock=True,
51+
trackers=True,
52+
annoyances=True,
53+
),
54+
scrape_options=ScrapeOptions(
55+
formats=formats,
56+
),
57+
)
58+
)
59+
60+
61+
def crawl_website(
62+
starting_url: str,
63+
max_pages: int = 10,
64+
include_pattern: List[str] = [],
65+
exclude_pattern: List[str] = [],
66+
use_proxy: bool = True,
67+
) -> CrawlJobResponse:
68+
"""
69+
Crawls a website starting from a specific URL and collects content from multiple pages.
70+
71+
This function navigates through a website by following links from the starting URL,
72+
up to the specified maximum number of pages. It can filter pages to crawl based on
73+
include and exclude patterns.
74+
75+
Args:
76+
starting_url: The initial URL to start crawling from
77+
max_pages: Maximum number of pages to crawl (default: 10)
78+
include_pattern: List of patterns for URLs to include in the crawl (default: [])
79+
exclude_pattern: List of patterns for URLs to exclude from the crawl (default: [])
80+
use_proxy: Whether to use a proxy for the requests (default: True)
81+
82+
Returns:
83+
CrawlJobResponse: The response containing the crawled content from all visited pages
84+
"""
85+
return hb.crawl.start_and_wait(
86+
StartCrawlJobParams(
87+
url=starting_url,
88+
max_pages=max_pages,
89+
include_pattern=include_pattern,
90+
exclude_pattern=exclude_pattern,
91+
session_options=CreateSessionParams(
92+
use_proxy=use_proxy,
93+
use_stealth=True,
94+
adblock=True,
95+
trackers=True,
96+
annoyances=True,
97+
),
98+
)
99+
)
100+
101+
102+
def extract_data_from_webpages(
103+
urls: List[str],
104+
schema: str,
105+
prompt: str,
106+
system_prompt: str | None = None,
107+
use_proxy: bool = True,
108+
) -> ExtractJobResponse:
109+
"""
110+
Extracts structured data from multiple webpages based on a provided schema and prompt.
111+
112+
This function visits each URL in the list and extracts structured data according to the
113+
specified schema and guided by the provided prompt. It uses AI-powered extraction to
114+
transform unstructured web content into structured data.
115+
116+
Args:
117+
urls: List of URLs to extract data from
118+
schema: JSON schema that defines the structure of the data to extract
119+
prompt: Instructions for the extraction model on what data to extract
120+
system_prompt: Optional system prompt to further guide the extraction (default: None)
121+
use_proxy: Whether to use a proxy for the requests (default: True)
122+
123+
Returns:
124+
ExtractJobResponse: The response containing the extracted structured data from all URLs
125+
"""
126+
return hb.extract.start_and_wait(
127+
StartExtractJobParams(
128+
urls=urls,
129+
prompt=prompt,
130+
system_prompt=system_prompt,
131+
schema=schema,
132+
session_options=CreateSessionParams(
133+
use_proxy=use_proxy,
134+
use_stealth=True,
135+
adblock=True,
136+
),
137+
)
138+
)
139+
140+
141+
def run_browser_use_agent(
142+
task: str,
143+
max_steps: int = 10,
144+
use_vision: bool = False,
145+
use_vision_for_planner: bool = False,
146+
use_proxy: bool = True,
147+
) -> BrowserUseTaskResponse:
148+
"""
149+
Runs a lightweight browser automation agent to perform a specific task.
150+
151+
This function initiates a browser session and runs a specialized agent that
152+
performs the specified task with minimal overhead. This agent is optimized for
153+
speed and efficiency but requires explicit, detailed instructions.
154+
155+
Args:
156+
task: Detailed description of the task to perform
157+
max_steps: Maximum number of steps the agent can take (default: 10)
158+
use_vision: Whether to enable vision capabilities for the agent (default: False)
159+
use_vision_for_planner: Whether to use vision for planning steps (default: False)
160+
use_proxy: Whether to use a proxy for the browser session (default: True)
161+
162+
Returns:
163+
BrowserUseTaskResponse: The response containing the results of the task execution
164+
"""
165+
return hb.agents.browser_use.start_and_wait(
166+
StartBrowserUseTaskParams(
167+
task=task,
168+
max_steps=max_steps,
169+
use_vision=use_vision,
170+
use_vision_for_planner=use_vision_for_planner,
171+
session_options=CreateSessionParams(
172+
use_proxy=use_proxy,
173+
use_stealth=True,
174+
adblock=True,
175+
trackers=True,
176+
annoyances=True,
177+
),
178+
)
179+
)
180+
181+
182+
def run_claude_computer_use_agent(
183+
task: str,
184+
max_steps: int = 10,
185+
use_vision: bool = False,
186+
use_vision_for_planner: bool = False,
187+
use_proxy: bool = True,
188+
) -> ClaudeComputerUseTaskResponse:
189+
"""
190+
Runs a Claude-powered browser automation agent to perform complex tasks.
191+
192+
This function initiates a browser session with Anthropic's Claude model as the
193+
driving intelligence. The agent is capable of sophisticated reasoning and handling
194+
complex, nuanced tasks that require understanding context and making decisions.
195+
196+
Args:
197+
task: Description of the task to perform
198+
max_steps: Maximum number of steps the agent can take (default: 10)
199+
use_vision: Whether to enable vision capabilities for the agent (default: False)
200+
use_vision_for_planner: Whether to use vision for planning steps (default: False)
201+
use_proxy: Whether to use a proxy for the browser session (default: True)
202+
203+
Returns:
204+
ClaudeComputerUseTaskResponse: The response containing the results of the task execution
205+
"""
206+
return hb.agents.claude_computer_use.start_and_wait(
207+
StartClaudeComputerUseTaskParams(
208+
task=task,
209+
max_steps=max_steps,
210+
use_vision=use_vision,
211+
use_vision_for_planner=use_vision_for_planner,
212+
session_options=CreateSessionParams(
213+
use_proxy=use_proxy,
214+
use_stealth=True,
215+
adblock=True,
216+
trackers=True,
217+
annoyances=True,
218+
),
219+
)
220+
)
221+
222+
223+
def run_openai_cua_agent(
224+
task: str,
225+
max_steps: int = 10,
226+
use_vision: bool = False,
227+
use_vision_for_planner: bool = False,
228+
use_proxy: bool = True,
229+
) -> CuaTaskResponse:
230+
"""
231+
Runs an OpenAI-powered browser automation agent to perform general-purpose tasks.
232+
233+
This function initiates a browser session with OpenAI's model as the driving
234+
intelligence. The agent provides balanced performance and reliability for a wide range
235+
of browser automation tasks with moderate complexity.
236+
237+
Args:
238+
task: Description of the task to perform
239+
max_steps: Maximum number of steps the agent can take (default: 10)
240+
use_vision: Whether to enable vision capabilities for the agent (default: False)
241+
use_vision_for_planner: Whether to use vision for planning steps (default: False)
242+
use_proxy: Whether to use a proxy for the browser session (default: True)
243+
244+
Returns:
245+
CuaTaskResponse: The response containing the results of the task execution
246+
"""
247+
return hb.agents.cua.start_and_wait(
248+
StartCuaTaskParams(
249+
task=task,
250+
max_steps=max_steps,
251+
use_vision=use_vision,
252+
use_vision_for_planner=use_vision_for_planner,
253+
session_options=CreateSessionParams(
254+
use_proxy=use_proxy,
255+
use_stealth=True,
256+
adblock=True,
257+
trackers=True,
258+
annoyances=True,
259+
),
260+
)
261+
)

‎agentstack/_tools/hyperbrowser/config.json

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "hyperbrowser",
3+
"url": "https://hyperbrowser.ai/",
4+
"category": "browsing",
5+
"env": {
6+
"HYPERBROWSER_API_KEY": null
7+
},
8+
"dependencies": ["hyperbrowser>=0.39.0"],
9+
"tools": [
10+
"scrape_webpage",
11+
"crawl_website",
12+
"extract_data_from_webpages",
13+
"run_browser_use_agent",
14+
"run_claude_computer_use_agent",
15+
"run_openai_cua_agent"
16+
],
17+
"cta": "Get your free API key at https://hyperbrowser.ai/"
18+
}

‎docs/tools/community.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ description: 'AgentStack tools from community contributors'
1313

1414
[//]: # (- [Browserbase](/tools/tool/browserbase))
1515
- [Firecrawl](/tools/tool/firecrawl)
16+
- [Hyperbrowser](/tools/tool/hyperbrowser)
1617

1718
## Search
1819
- [Perplexity](/tools/tool/perplexity)
@@ -46,4 +47,4 @@ description: 'AgentStack tools from community contributors'
4647
>
4748
Default tools in AgentStack
4849
</Card>
49-
</CardGroup>
50+
</CardGroup>

0 commit comments

Comments
 (0)