HyperAgent is our open-source tool that supercharges playwright with AI. To view the full details on HyperAgent, check out the . Here, we will just go over using one of the features of HyperAgent which is being able to have it automatically execute tasks on your behalf on the web with just a simple call. You can do this using our Agents API so all you have to worry about is providing the task and some other optional parameters.
By default, HyperAgent tasks are handled in an asynchronous manner of first starting the task and then checking it's status until it is completed. However, if you don't want to handle the monitoring yourself, our SDKs provide a simple function that handles the whole flow and returns the data once the task is completed.
Installation
npm install @hyperbrowser/sdk
or
yarn add @hyperbrowser/sdk
pip install hyperbrowser
or
uv add hyperbrowser
Usage
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";
config();
const hbClient = new Hyperbrowser({
apiKey: process.env.HYPERBROWSER_API_KEY,
});
const main = async () => {
const result = await hbClient.agents.hyperAgent.startAndWait({
task: "What is the title of the first post on Hacker News today?",
});
console.log(`Output:\n\n${result.data?.finalResult}`);
};
main().catch((err) => {
console.error(`Error: ${err.message}`);
});
import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartHyperAgentTaskParams
from dotenv import load_dotenv
load_dotenv()
hb_client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))
def main():
resp = hb_client.agents.hyper_agent.start_and_wait(
StartHyperAgentTaskParams(
task="What is the title of the first post on Hacker News today?"
)
)
print(f"Output:\n\n{resp.data.final_result}")
if __name__ == "__main__":
try:
main()
except Exception as e:
print(f"Error: {e}")
Start HyperAgent task
curl -X POST https://app.hyperbrowser.ai/api/task/hyper-agent \
-H 'Content-Type: application/json' \
-H 'x-api-key: <YOUR_API_KEY>' \
-d '{
"task": "What is the title of the first post on Hacker News today?"
}'
curl -X PUT https://app.hyperbrowser.ai/api/task/hyper-agent/{jobId}/stop \
-H 'x-api-key: <YOUR_API_KEY>'
HyperAgent Task parameters
sessionId - An optional existing browser session ID to connect to instead of creating a new one.
maxSteps - The maximum number of steps HyperAgent can take before concluding the task.
keepBrowserOpen - When enabled, keeps the browser session open after task completion.
The agent may not complete the task within the specified maxSteps. If that happens, try increasing the maxSteps parameter.
Reuse Browser Session
You can pass in an existing sessionId to the HyperAgent task so that it can execute the task on an existing session. Also, if you want to keep the session open after executing the task, you can supply the keepBrowserOpen param.
In the examples below, the keepBrowserOpen field is not set to true in the second call to the AI Agent so it will close the browser session after execution, and the session is being closed at the end with the stop function to make sure it gets closed.
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";
config();
const hbClient = new Hyperbrowser({
apiKey: process.env.HYPERBROWSER_API_KEY,
});
const main = async () => {
const session = await hbClient.sessions.create();
try {
const result = await hbClient.agents.hyperAgent.startAndWait({
task: "What is the title of the first post on Hacker News today?",
sessionId: session.id,
keepBrowserOpen: true,
});
console.log(`Output:\n${result.data?.finalResult}`);
const result2 = await hbClient.agents.hyperAgent.startAndWait({
task: "Tell me how many upvotes the first post has.",
sessionId: session.id,
});
console.log(`\nOutput:\n${result2.data?.finalResult}`);
} catch (err) {
console.error(`Error: ${err}`);
} finally {
await hbClient.sessions.stop(session.id);
}
};
main().catch((err) => {
console.error(`Error: ${err.message}`);
});
import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartHyperAgentTaskParams
from dotenv import load_dotenv
load_dotenv()
hb_client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))
def main():
session = hb_client.sessions.create()
try:
resp = hb_client.agents.hyper_agent.start_and_wait(
StartHyperAgentTaskParams(
task="What is the title of the first post on Hacker News today?",
session_id=session.id,
keep_browser_open=True,
)
)
print(f"Output:\n{resp.data.final_result}")
resp2 = hb_client.agents.hyper_agent.start_and_wait(
StartHyperAgentTaskParams(
task="Tell me how many upvotes the first post has.",
session_id=session.id,
)
)
print(f"\nOutput:\n{resp2.data.final_result}")
except Exception as e:
print(f"Error: {e}")
finally:
hb_client.sessions.stop(session.id)
if __name__ == "__main__":
try:
main()
except Exception as e:
print(f"Error: {e}")
Session Configurations
The sessionOptions will only apply if creating a new session when no sessionId is provided.
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";
config();
const hbClient = new Hyperbrowser({
apiKey: process.env.HYPERBROWSER_API_KEY,
});
const main = async () => {
const result = await hbClient.agents.hyperAgent.startAndWait({
task: "What is the title of the top post on HackerNews today?",
sessionOptions: {
acceptCookies: true,
}
});
console.log(`Output:\n\n${result.data?.finalResult}`);
};
main().catch((err) => {
console.error(`Error: ${err.message}`);
});
import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartHyperAgentTaskParams, CreateSessionParams
from dotenv import load_dotenv
load_dotenv()
hb_client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))
def main():
resp = hb_client.agents.hyper_agent.start_and_wait(
StartHyperAgentTaskParams(
task="What is the title of the top post on HackerNews today?",
session_options=CreateSessionParams(
accept_cookies=True,
),
)
)
print(f"Output:\n\n{resp.data.final_result}")
if __name__ == "__main__":
try:
main()
except Exception as e:
print(f"Error: {e}")
curl -X POST https://app.hyperbrowser.ai/api/task/hyper-agent \
-H 'Content-Type: application/json' \
-H 'x-api-key: <YOUR_API_KEY>' \
-d '{
"task": "What is the title of the top post on HackerNews today?",
"sessionOptions": {
"acceptCookies": true
}
}'
Hyperbrowser's CAPTCHA solving and proxy usage features require being on a PAID plan.
Using proxy and solving CAPTCHAs will slow down the web navigation in the HyperAgent task so use it only if necessary.
HyperAgent tasks can be configured with a number of parameters. Some of them are described briefly here, but a list can be found in our .
llm - The language model (LLM) instance to use for executing the task. By default, HyperAgent will use gpt-4o. A complete list is available in the .
sessionOptions - .
For detailed usage/schema, check out the .
Additionally, the browser session used by the AI Agent will time out based on your team's default Session Timeout settings or the session's timeoutMinutes parameter if provided. You can adjust the default Session Timeout in the .
You can also provide configurations for the session that will be used to execute the HyperAgent task just as you would when creating a new session itself. These could include using a proxy or solving CAPTCHAs. To see the full list of session configurations, checkout the .
