SupportDashboard

HyperAgent SDK

HyperAgent Class

The HyperAgent class provides an interface for running autonomous web agents. It manages browser instances, task execution, and integration with Model Context Protocol (MCP) servers.

Creating a HyperAgent Instance

import { HyperAgent } from "@/agent";
import { ChatOpenAI } from "@langchain/openai";

// Initialize with default settings (requires OPENAI_API_KEY env var)
const agent = new HyperAgent();

// Or, initialize with custom configuration
const agentWithConfig = new HyperAgent({
    llm: new ChatOpenAI({ 
        modelName: "gpt-4o",
        apiKey: process.env.OPENAI_API_KEY,
    }), // Specify the LLM
    browserProvider: "Hyperbrowser", // Can be Local or Hyperbrowser depending on the browser provider you want. Defaults to Local
    hyperbrowserConfig: { /* Hyperbrowser specific config if using Hyperbrowser browser provider */ },
    localConfig: { /* Playwright launch option if using the Local Browser Provider*/ }
    debug: true, // Enable debug logging
    customActions: [ /* Array of custom actions */ ],
});

Initializing

  • Description: Initializes a new instance of the HyperAgent. Configures the language model, browser provider (local or Hyperbrowser), debug mode, and custom actions.

  • Parameters:

    • params (HyperAgentConfig, optional): Configuration object.

      • llm (BaseChatModel, optional): The language model instance to use. Defaults to using GPT-4o if OPENAI_API_KEY environment variable is set.

      • browserProvider ("Hyperbrowser" | "Local", optional): Specifies whether to use Hyperbrowser's cloud browsers or a local Playwright instance. Defaults to Local.

      • hyperbrowserConfig (object, optional): Configuration for the Hyperbrowser provider. See more details in the types description.

      • localConfig (object, optional): Configuration for the local browser provider. See more details in the types description

      • customActions (AgentActionDefinition[], optional): An array of custom actions to register with the agent. You can read more about custom actions here.

      • debug (boolean, optional): Enables detailed logging if set to true. Defaults to false. Logs are dumped to ./debug directory.

  • Throws: HyperagentError if no LLM is provided and OPENAI_API_KEY env var is not set.

Browser and Page Management

List all current pages

async getPages(): Promise<HyperPage[]>

  • Description: Retrieves all currently open pages within the agent's browser context. Each page is enhanced with ai and aiAsync methods for task execution.

  • Returns: Promise<HyperPage[]> - An array of HyperPage objects.

  • Usage:

    const pages = await agent.getPages();
if (pages.length > 0) {
    await pages[0].ai("Summarize the content of this page.");
}

Creating a newPage

async newPage(): Promise<HyperPage>

  • Description: Creates and returns a new page (tab) in the agent's browser context. The returned page is enhanced with ai and aiAsync methods.

  • Returns: Promise<HyperPage> - A new HyperPage object.

  • Usage:

    const newPage = await agent.newPage();
await newPage.goto("https://example.com");
const summary = await newPage.ai("What is this website about?");
console.log(summary);

Get current page

async getCurrentPage(): Promise<Page>

  • Description: Gets the agent's currently active page. If no page exists or the current page is closed, it creates a new one. Note: This returns a standard Playwright Page object, not a HyperPage.

  • Returns: Promise<Page> - The current or a new Playwright Page.

  • Usage:

    const currentPage = await agent.getCurrentPage();
await currentPage.goto("https://google.com");

Close agent

async closeAgent(): Promise<void>

  • Description: Closes the agent, including the browser instance, browser context, and any active MCP connections. Cancels any tasks that are still running or paused.

  • Returns: Promise<void>

  • Usage:

    await agent.closeAgent();
console.log("Agent closed.");

Task Execution

Execute a task

async executeTask(task: string, params?: TaskParams, initPage?: Page): Promise<TaskOutput>

  • Description: Executes a given task instruction synchronously. The agent uses its LLM and configured actions to perform the task on a browser page. It waits for the task to complete (or fail) and returns the final output.

  • Parameters:

    • task (string): The natural language instruction for the task (e.g., "Find the contact email on this page").

    • params (TaskParams, optional): Additional parameters for the task, like outputSchema to specify the desired output format using a Zod schema, or maxSteps to control the number of steps. A full description can be found on the types page

    • initPage (Page, optional): A specific Playwright Page to start the task on. Defaults to the agent's currentPage.

  • Returns: Promise<TaskOutput> - The result of the task, typically a string summary or structured data if outputSchema was provided.

  • Throws: Rethrows any error encountered during task execution.

  • Usage:

    const page = await agent.newPage();
await page.goto("https://example.com");
const result = await agent.executeTask("Extract the main heading from www.example.com", { outputSchema: z.object({ heading: z.string() }) }, page);
console.log(result); // { heading: "Example Domain" }

Execute a task asynchronously

async executeTaskAsync(task: string, params?: TaskParams, initPage?: Page): Promise<Task>

  • Description: Executes a given task instruction asynchronously. It immediately returns a Task control object, allowing management (pause, resume, cancel) of the background task.

  • Parameters

    • task (string): The natural language instruction for the task (e.g., "Find the contact email on this page").

    • params (TaskParams, optional): Additional parameters for the task, like outputSchema to specify the desired output format using a Zod schema, or maxSteps to control the number of steps. A full description can be found on the types page

    • initPage (Page, optional): A specific Playwright Page to start the task on. Defaults to the agent's currentPage.

  • Returns: Promise<Task> - A Task control object with methods:

    • getStatus(): TaskStatus

    • pause(): TaskStatus

    • resume(): TaskStatus

    • cancel(): TaskStatus

  • Usage:

    const taskControl = await agent.executeTaskAsync("Go to news.google.com, and search for international news.");
console.log("Task started with status:", taskControl.getStatus());
// ... later
taskControl.pause();
// ... even later
taskControl.cancel();

Model Context Protocol (MCP) Integration

MCP allows extending the agent's capabilities by connecting to external servers that provide additional tools/actions.

Initialize a MCP client

async initializeMCPClient(config: MCPConfig): Promise<void>

  • Description: Initializes the MCP client and attempts to connect to all servers specified in the configuration. Actions provided by successfully connected servers are registered with the agent.

  • Parameters:

    • config (MCPConfig): Configuration object containing an array of servers (each with connection details like URL and ID).

  • Returns: Promise<void>

  • Usage:

    await agent.initializeMCPClient({
    servers: [
        { id: "server1", url: "ws://localhost:8080" },
        // ... other servers
    ]
});

Connect to a single MCP server

async connectToMCPServer(serverConfig: MCPServerConfig): Promise<string | null>

  • Description: Connects to a single MCP server at runtime. Registers actions provided by the server if the connection is successful.

  • Parameters:

    • serverConfig (MCPServerConfig): Configuration for the specific server to connect to.

  • Returns: Promise<string | null> - The server ID if connection was successful, otherwise null.

  • Usage:

    const serverId = await agent.connectToMCPServer({ id: "runtimeServer", url: "ws://localhost:8081" });
if (serverId) {
    console.log(`Connected to ${serverId}`);
}

Disconnect from a MCP server

disconnectFromMCPServer(serverId: string): boolean

  • Description: Disconnects from a specific MCP server identified by its ID. Note: This does not automatically unregister the actions provided by that server.

  • Parameters:

    • serverId (string): The ID of the server to disconnect from.

  • Returns: boolean - true if disconnection was successful or the server wasn't connected, false if an error occurred.

  • Usage:

    const success = agent.disconnectFromMCPServer("server1");
console.log("Disconnected:", success);

Check if a MCP server is connected

isMCPServerConnected(serverId: string): boolean

  • Description: Checks if the agent is currently connected to a specific MCP server.

  • Parameters:

    • serverId (string): The ID of the server to check.

  • Returns: boolean - true if connected, false otherwise.

  • Usage:

    if (agent.isMCPServerConnected("server1")) {
    console.log("Server1 is connected.");
}

List MCP server ids

getMCPServerIds(): string[]

  • Description: Retrieves the IDs of all currently connected MCP servers.

  • Returns: string[] - An array of connected server IDs.

  • Usage:

    const connectedServers = agent.getMCPServerIds();
console.log("Connected servers:", connectedServers);

Get MCP server info

getMCPServerInfo(): Array<{ id: string; toolCount: number; toolNames: string[]; }> | null

  • Description: Gets information about all connected MCP servers, including their IDs and the tools (actions) they provide.

  • Returns: Array<{ id: string; toolCount: number; toolNames: string[]; }> | null - An array of server info objects, or null if the MCP client isn't initialized.

  • Usage:

    const serverInfo = agent.getMCPServerInfo();
if (serverInfo) {
    serverInfo.forEach(info => {
        console.log(`Server: ${info.id}, Tools: ${info.toolNames.join(', ')}`);
    });
}

Utility Methods

Pretty print contents of an action output

pprintAction(action: ActionType): string

  • Description: Generates a human-readable string representation of an agent action, if a pretty-print function is defined for that action type. Useful for logging or debugging.

  • Parameters:

    • action (ActionType): The action object (containing type and params).

  • Returns: string - A formatted string representing the action, or an empty string if no specific pretty-print function exists for the action type.

  • Usage:

    // Assuming 'lastAction' is an action object from a task step
console.log(agent.pprintAction(lastAction));
// Example output: "Clicked element with selector '#submit-button'"
PreviousAbout HyperAgentNextHyperAgent Types

Last updated