Intelligent Browser Automation with LLMs

Overview

Hyperagent is Playwright supercharged with AI. No more brittle scripts, just powerful natural language commands. Just looking for scalable headless browsers or scraping infra? Go to Hyperbrowser to get started for free!

Features

• 🤖 AI Commands: Simple APIs like page.ai(), page.extract() and executeTask() for any AI automation
• ⚡ Fallback to Regular Playwright: Use regular Playwright when AI isn't needed
• 🥷 Stealth Mode – Avoid detection with built-in anti-bot patches
• ☁️ Cloud Ready – Instantly scale to hundreds of sessions via Hyperbrowser
• 🔌 MCP Client – Connect to tools like Composio for full workflows (e.g. writing web data to Google Sheets)

Quick Start

Installation

# Using npm
npm install @hyperbrowser/agent
# Using yarn
yarn add @hyperbrowser/agent

CLI

$ npx @hyperbrowser/agent -c "Find a route from Miami to New Orleans, and provide the detailed route information."

The CLI supports options for debugging or using hyperbrowser instead of a local browser

-d, --debug Enable debug mode
-c, --command <task description> Command to run
--hyperbrowser Use Hyperbrowser for the browser provider

Library

import{HyperAgent}from"@hyperbrowser/agent";import{ChatOpenAI}from"@langchain/openai";import{z}from"zod";// Initialize the agentconstagent=newHyperAgent({llm: newChatOpenAI({openAIApiKey: process.env.OPENAI_API_KEY,modelName: "gpt-4o",}),});// Execute a taskconstresult=awaitagent.executeTask("Navigate to amazon.com, search for 'laptop', and extract the prices of the first 5 results");console.log(result.output);// Use page.ai and page.extractconstpage=awaitagent.newPage();awaitpage.goto("https://flights.google.com",{waitUntil: "load"});awaitpage.ai("search for flights from Rio to LAX from July 16 to July 22");constres=awaitpage.extract("give me the flight options",z.object({flights: z.array(z.object({price: z.number(),departure: z.string(),arrival: z.string(),})),}));console.log(res);// Clean upawaitagent.closeAgent();

☁️ Cloud

You can scale HyperAgent with cloud headless browsers using Hyperbrowser

1. Get a free api key from Hyperbrowser
2. Add it to your env as HYPERBROWSER_API_KEY
3. Set your browserProvider to "Hyperbrowser"

constagent=newHyperAgent({browserProvider: "Hyperbrowser",});constresponse=awaitagent.executeTask("Go to hackernews, and list me the 5 most recent article titles");console.log(response);awaitagent.closeAgent();

Usage Guide

Config Browser with playwright endpointURL

• endpointURL: A CDP WebSocket endpoint or HTTP URL to connect to. For example, http://localhost:9222/ or ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4.
• slowMo: Slows down operations by the specified number of milliseconds for debugging purposes.
• args: An array of custom arguments to pass to the browser instance.

These options provide flexibility for connecting to remote browsers or customizing the browser's behavior during automation.

import{HyperAgent}from"@hyperbrowser/agent";constagent=newHyperAgent({options: {endpointURL: "ws://localhost:3000",// or http://localhost:9222 Connect to a remote browserslowMo: 50,// Slow down operations for debugging},});// Use the agent as usualconstresult=awaitagent.executeTask("Navigate to example.com and extract the page title");console.log(result.output);// Clean upawaitagent.closeAgent();

Multi-Page Management

// Create and manage multiple pagesconstpage1=awaitagent.newPage();constpage2=awaitagent.newPage();// Execute tasks on specific pagesconstpage1Response=awaitpage1.ai("Go to google.com/travel/explore and set the starting location to New York. Then, return to me the first recommended destination that shows up. Return to me only the name of the location.");constpage2Response=awaitpage2.ai(`I want to plan a trip to ${page1Response.output}. Recommend me places to visit there.`);console.log(page2Response.output);// Get all active pagesconstpages=awaitagent.getPages();awaitagent.closeAgent();

Customization

Output Schema Definition

HyperAgent can extract data in a specified schema. The schema can be passed in at a per-task level

import{z}from"zod";constagent=newHyperAgent();constagentResponse=awaitagent.executeTask("Navigate to imdb.com, search for 'The Matrix', and extract the director, release year, and rating",{outputSchema: z.object({director: z.string().describe("The name of the movie director"),releaseYear: z.number().describe("The year the movie was released"),rating: z.string().describe("The IMDb rating of the movie"),}),});console.log(agentResponse.output);awaitagent.closeAgent();

{
"director": "Lana Wachowski, Lilly Wachowski",
"releaseYear": 1999,
"rating": "8.7/10"
}

Using Different LLM Providers

Hyperagent supports multiple LLM providers. A provider can be anything that extends to the Langchain BaseChatModel class.

// Using OpenAIconstagent=newHyperAgent({llm: newChatOpenAI({openAIApiKey: process.env.OPENAI_API_KEY,modelName: "gpt-4o",}),});// Using Anthropic's Claudeconstagent=newHyperAgent({llm: newChatAnthropic({anthropicApiKey: process.env.ANTHROPIC_API_KEY,modelName: "claude-3-7-sonnet-latest",}),});

MCP Support

HyperAgent functions as a fully functional MCP client. For best results, we recommend using gpt-4o as your LLM.

Here is an example which reads from wikipedia, and inserts information into a google sheet using the composio Google Sheet MCP. For the full example, see here

constagent=newHyperAgent({llm: llm,debug: true,});awaitagent.initializeMCPClient({servers: [{command: "npx",args: ["@composio/mcp@latest","start","--url","https://mcp.composio.dev/googlesheets/...",],env: {npm_config_yes: "true",},},],});constresponse=awaitagent.executeTask("Go to https://en.wikipedia.org/wiki/List_of_U.S._states_and_territories_by_population and get the data on the top 5 most populous states from the table. Then insert that data into a google sheet. You may need to first check if there is an active connection to google sheet, and if there isn't connect to it and present me with the link to sign in. ");console.log(response);awaitagent.closeAgent();

Custom Actions

HyperAgent's capabilities can be extended with custom actions. Custom actions require 3 things:

• type: Name of the action. Should be something descriptive about the action.
• actionParams: A zod object describing the parameters that the action may consume.
• run: A function that takes in a context, and the params for the action and produces a result based on the params.

Here is an example that performs a search using Exa

constexaInstance=newExa(process.env.EXA_API_KEY);exportconstRunSearchActionDefinition: AgentActionDefinition={type: "perform_search",actionParams: z.object({search: z.string().describe("The search query for something you want to search about. Keep the search query concise and to-the-point."),}).describe("Search and return the results for a given query.");,run: asyncfunction(ctx: ActionContext,params: z.infer<typeofsearchSchema>): Promise<ActionOutput>{constresults=(awaitexaInstance.search(params.search,{})).results.map((res)=>`title: ${res.title} || url: ${res.url} || relevance: ${res.score}`).join("\n");return{success: true,message: `Succesfully performed search for query ${params.search}. Got results: \n${results}`,};},};constagent=newHyperAgent({"Search about the news for today in New York",customActions: [RunSearchActionDefinition],});

Contributing

We welcome contributions to Hyperagent! Here's how you can help:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Support

• 📚 Documentation
• 💬 Discord Community
• 🐛 Issue Tracker
• 📧 Email Support