Hyperbrowser Agents

https://www.hyperbrowser.ai/docs/agents/
Admin
Hyperbrowser Agents enable users to automate browser tasks and create agentic workflows using...
Tokens:43,155
Snippets:132
Trust Score:7.9
Update:10 months ago
Show doc for...
Tokens:
Raw
### Async Task Management (Gemini Computer Use)

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

This section explains how to use the asynchronous pattern to start an AI task, poll for its completion status, and retrieve the final results. It provides examples in Node.js and Python.

```APIDOC
## Async Pattern

When you need more control, use the async pattern to start a task and poll for results:

### Node.js Example

```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  try {
    // Start the task
    const task = await client.agents.geminiComputerUse.start({
      task: "What is the title of the first post on Hacker News today?",
      maxSteps: 20,
    });

    console.log(`Task started: ${task.jobId}`);
    console.log(`Watch live: ${task.liveUrl}`);

    // Poll for completion
    let result;
    while (true) {
      result = await client.agents.geminiComputerUse.getStatus(task.jobId);
      console.log(`Status: ${result.status}`);

      if (result.status === "completed" || result.status === "failed") {
        break;
      }

      await new Promise((resolve) => setTimeout(resolve, 5000)); // Wait 5s
    }

    const fullResult = await client.agents.geminiComputerUse.get(task.jobId);

    if (fullResult.status === "completed") {
      console.log("Result:", fullResult.data?.finalResult);
      console.log("Steps taken:", fullResult.data?.steps?.length);
    } else {
      console.error("Task failed:", fullResult.error);
    }
  } catch (err) {
    console.error(`Error: ${err.message}`);
  }
}

main();
```

### Python Example

```python
import asyncio
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models import StartGeminiComputerUseTaskParams
from dotenv import load_dotenv
import os

load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    try:
        # Start the task
        task = await client.agents.gemini_computer_use.start(
            params=StartGeminiComputerUseTaskParams(
                task="What is the title of the first post on Hacker News today?",
                max_steps=20,
            )
        )

        print(f"Task started: {task.job_id}")
        print(f"Watch live: {task.live_url}")

        # Poll for completion
        while True:
            result = await client.agents.gemini_computer_use.get_status(task.job_id)
            print(f"Status: {result.status}")

            if result.status in ["completed", "failed"]:
                break

            await asyncio.sleep(5)  # Wait 5s

        full_result = await client.agents.gemini_computer_use.get(task.job_id)

        if full_result.status == "completed":
            print("Result:", full_result.data.final_result)
            print(
                "Steps taken:",
                len(full_result.data.steps) if full_result.data.steps else 0,
            )
        else:
            print("Task failed:", full_result.error)
    except Exception as e:
        print(f"Error: {e}")


if __name__ == "__main__":
    asyncio.run(main())
```
```

--------------------------------

### Async Pattern for AI Agent Tasks

Source: https://www.hyperbrowser.ai/docs/agents/claude-computer-use

This section details how to use the asynchronous pattern to start an AI agent task and poll for its results. It provides examples in Node.js and Python.

```APIDOC
## POST /api/agents/{agentName}/start

### Description
Starts an asynchronous task using a specified AI agent. This method returns a job ID that can be used to track the task's progress.

### Method
POST

### Endpoint
/api/agents/{agentName}/start

### Parameters
#### Path Parameters
- **agentName** (string) - Required - The name of the AI agent to use.

#### Request Body
- **task** (string) - Required - The description of the task to be performed by the AI agent.
- **llm** (string) - Required - The language model to use for the task.
- **maxSteps** (integer) - Optional - The maximum number of steps the agent can take to complete the task.

### Request Example (Node.js)
```javascript
await client.agents.claudeComputerUse.start({
  task: "What is the title of the first post on Hacker News today?",
  llm: "claude-sonnet-4-5",
  maxSteps: 20,
});
```

### Request Example (Python)
```python
from hyperbrowser.models import StartClaudeComputerUseTaskParams

await client.agents.claude_computer_use.start(
    params=StartClaudeComputerUseTaskParams(
        task="What is the title of the first post on Hacker News today?",
        llm="claude-sonnet-4-5",
        max_steps=20,
    )
)
```

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier for the started task.
- **liveUrl** (string) - A URL to monitor the task's progress in real-time.

#### Response Example
```json
{
  "jobId": "job-12345",
  "liveUrl": "https://hyperbrowser.ai/monitor/job-12345"
}
```

## GET /api/agents/{agentName}/{jobId}/status

### Description
Retrieves the current status of an ongoing AI agent task using its job ID.

### Method
GET

### Endpoint
/api/agents/{agentName}/{jobId}/status

### Parameters
#### Path Parameters
- **agentName** (string) - Required - The name of the AI agent.
- **jobId** (string) - Required - The unique identifier of the task.

### Response
#### Success Response (200)
- **status** (string) - The current status of the task (e.g., "running", "completed", "failed").

#### Response Example
```json
{
  "status": "running"
}
```

## GET /api/agents/{agentName}/{jobId}

### Description
Retrieves the complete results of a completed or failed AI agent task using its job ID.

### Method
GET

### Endpoint
/api/agents/{agentName}/{jobId}

### Parameters
#### Path Parameters
- **agentName** (string) - Required - The name of the AI agent.
- **jobId** (string) - Required - The unique identifier of the task.

### Response
#### Success Response (200)
- **status** (string) - The final status of the task (e.g., "completed", "failed").
- **data** (object) - Contains the task results if completed.
  - **finalResult** (any) - The final outcome of the task.
  - **steps** (array) - An array of steps taken by the agent.
- **error** (string) - An error message if the task failed.

#### Response Example (Completed)
```json
{
  "status": "completed",
  "data": {
    "finalResult": "The title of the first post on Hacker News today is 'New study reveals...', "
    "steps": [
      // ... array of steps ...
    ]
  }
}
```

#### Response Example (Failed)
```json
{
  "status": "failed",
  "error": "An unexpected error occurred during execution."
}
```
```

--------------------------------

### Run Gemini Computer Use Task (cURL)

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Initiate and manage a Gemini Computer Use task using cURL commands. This demonstrates the asynchronous pattern: first, start the task with a POST request to get a jobId, then poll its status, and finally retrieve the complete results. Replace YOUR_API_KEY with your actual API key.

```bash
# Start the task
curl -X POST https://api.hyperbrowser.ai/api/task/gemini-computer-use \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "task": "Go to Hacker News and tell me the title of the top post",
    "maxSteps": 20
  }'

# Response: {"jobId": "abc123", "liveUrl": "https://..."}

# Check status
curl https://api.hyperbrowser.ai/api/task/gemini-computer-use/abc123/status \
  -H "x-api-key: YOUR_API_KEY"

# Get full results
curl https://api.hyperbrowser.ai/api/task/gemini-computer-use/abc123 \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Start Browser Task with Session Options (cURL)

Source: https://www.hyperbrowser.ai/docs/agents/browser-use

Initiates a browser task via a cURL request to the Hyperbrowser API, specifying session options like cookie acceptance. This command-line example sends a POST request with JSON payload, including the task description and session configuration.

```bash
curl -X POST https://api.hyperbrowser.ai/api/task/browser-use \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <YOUR_API_KEY>' \
  -d '{
    "task": "go to Hacker News and summarize the top 5 posts of the day",
    "sessionOptions": {
        "acceptCookies": true
    }
}'
```

--------------------------------

### Async Pattern - Start and Poll for Task Results

Source: https://www.hyperbrowser.ai/docs/agents/hyperagent

This section details how to use the asynchronous pattern to start an AI agent task and poll for its completion. It includes examples in Node.js and Python, showing how to initiate a task, log its job ID and live URL, periodically check its status, and retrieve the final result or error information.

```APIDOC
## POST /api/agents/hyperAgent/start

### Description
Starts an asynchronous AI agent task. You will receive a `jobId` and a `liveUrl` to monitor the task's progress.

### Method
POST

### Endpoint
/api/agents/hyperAgent/start

### Parameters
#### Request Body
- **task** (string) - Required - The description of the task to be performed by the AI agent.
- **llm** (string) - Required - The language model to use for the task (e.g., "gpt-4o").
- **maxSteps** (integer) - Optional - The maximum number of steps the agent can take to complete the task.

### Request Example (Node.js)
```javascript
await client.agents.hyperAgent.start({
  task: "What is the title of the first post on Hacker News today?",
  llm: "gpt-4o",
  maxSteps: 20
});
```

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier for the started task.
- **liveUrl** (string) - A URL to monitor the task's progress in real-time.

#### Response Example
```json
{
  "jobId": "some-job-id",
  "liveUrl": "https://hyperbrowser.ai/live/some-job-id"
}
```

## GET /api/agents/hyperAgent/{jobId}/status

### Description
Retrieves the current status of an ongoing AI agent task.

### Method
GET

### Endpoint
/api/agents/hyperAgent/{jobId}/status

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the task to get the status for.

### Response
#### Success Response (200)
- **status** (string) - The current status of the task (e.g., "running", "completed", "failed").

#### Response Example
```json
{
  "status": "running"
}
```

## GET /api/agents/hyperAgent/{jobId}

### Description
Retrieves the final result and details of a completed or failed AI agent task.

### Method
GET

### Endpoint
/api/agents/hyperAgent/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the task to get the results for.

### Response
#### Success Response (200)
- **status** (string) - The final status of the task (e.g., "completed", "failed").
- **data** (object) - Contains the result details if the task was completed.
  - **finalResult** (any) - The final output of the task.
  - **steps** (array) - An array of steps taken by the agent.
- **error** (string) - An error message if the task failed.

#### Response Example (Completed)
```json
{
  "status": "completed",
  "data": {
    "finalResult": "The first post on Hacker News today is titled 'Example Title'.",
    "steps": [
      { "action": "Open Hacker News", "result": "Success" },
      { "action": "Read first post title", "result": "'Example Title'" }
    ]
  }
}
```

#### Response Example (Failed)
```json
{
  "status": "failed",
  "error": "An unexpected error occurred."
}
```
```

--------------------------------

### Start and Poll Hyperbrowser AI Agent Task (Async Pattern)

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

This snippet demonstrates the async pattern for interacting with Hyperbrowser AI agents. It shows how to start a task, poll its status periodically, and retrieve the final result or error. It requires the Hyperbrowser SDK and dotenv for API key management. The input is a task description and optional parameters, and the output is the task status, live URL, and eventually the final result or error message.

```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  try {
    // Start the task
    const task = await client.agents.geminiComputerUse.start({
      task: "What is the title of the first post on Hacker News today?",
      maxSteps: 20,
    });

    console.log(`Task started: ${task.jobId}`);
    console.log(`Watch live: ${task.liveUrl}`);

    // Poll for completion
    let result;
    while (true) {
      result = await client.agents.geminiComputerUse.getStatus(task.jobId);
      console.log(`Status: ${result.status}`);

      if (result.status === "completed" || result.status === "failed") {
        break;
      }

      await new Promise((resolve) => setTimeout(resolve, 5000)); // Wait 5s
    }

    const fullResult = await client.agents.geminiComputerUse.get(task.jobId);

    if (fullResult.status === "completed") {
      console.log("Result:", fullResult.data?.finalResult);
      console.log("Steps taken:", fullResult.data?.steps?.length);
    } else {
      console.error("Task failed:", fullResult.error);
    }
  } catch (err) {
    console.error(`Error: ${err.message}`);
  }
}

main();

```

```python
import asyncio
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models import StartGeminiComputerUseTaskParams
from dotenv import load_dotenv
import os

load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    try:
        # Start the task
        task = await client.agents.gemini_computer_use.start(
            params=StartGeminiComputerUseTaskParams(
                task="What is the title of the first post on Hacker News today?",
                max_steps=20,
            )
        )

        print(f"Task started: {task.job_id}")
        print(f"Watch live: {task.live_url}")

        # Poll for completion
        while True:
            result = await client.agents.gemini_computer_use.get_status(task.job_id)
            print(f"Status: {result.status}")

            if result.status in ["completed", "failed"]:
                break

            await asyncio.sleep(5)  # Wait 5s

        full_result = await client.agents.gemini_computer_use.get(task.job_id)

        if full_result.status == "completed":
            print("Result:", full_result.data.final_result)
            print(
                "Steps taken:",
                len(full_result.data.steps) if full_result.data.steps else 0,
            )
        else:
            print("Task failed:", full_result.error)
    except Exception as e:
        print(f"Error: {e}")


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Start CUA Task with Session Options

Source: https://www.hyperbrowser.ai/docs/agents/openai-cua

This endpoint allows you to start a CUA task and customize the browser session settings. You can specify options such as accepting cookies. Note that `sessionOptions` are only applied when a new session is created; they are ignored if a `sessionId` is provided.

```APIDOC
## POST /api/task/cua

### Description
Starts a CUA task with customizable session options.

### Method
POST

### Endpoint
/api/task/cua

### Parameters
#### Query Parameters
None

#### Request Body
- **task** (string) - Required - The task description for CUA.
- **sessionOptions** (object) - Optional - Options to configure the browser session.
  - **acceptCookies** (boolean) - Optional - Whether to accept cookies. Defaults to false.
- **sessionId** (string) - Optional - The ID of an existing session to reuse. If provided, `sessionOptions` are ignored.

### Request Example
```json
{
  "task": "What is the title of the first post on Hacker News today?",
  "sessionOptions": {
    "acceptCookies": true
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the result of the CUA task.
  - **finalResult** (string) - The final output from the CUA agent.

#### Response Example
```json
{
  "data": {
    "finalResult": "The title of the first post on Hacker News today is ..."
  }
}
```

### Errors
- 400 Bad Request: Invalid input parameters.
- 401 Unauthorized: Invalid API key.
- 500 Internal Server Error: An error occurred on the server.
```

--------------------------------

### Start Browser Task with Session Options (Python)

Source: https://www.hyperbrowser.ai/docs/agents/browser-use

Executes a browser task and waits for the result using the Hyperbrowser Python client. This example demonstrates setting session options like accepting cookies. It utilizes the 'hyperbrowser' and 'python-dotenv' libraries for API key management and client instantiation.

```python
import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartBrowserUseTaskParams, CreateSessionParams
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def main():
    resp = client.agents.browser_use.start_and_wait(
        StartBrowserUseTaskParams(
            task="go to Hacker News and summarize the top 5 posts of the day",
            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}")
```

--------------------------------

### Async Pattern for Browser Use Tasks

Source: https://www.hyperbrowser.ai/docs/agents/browser-use

This section outlines the asynchronous pattern for starting and monitoring browser use tasks. It demonstrates how to initiate a task, poll for its completion status, and retrieve the final results or error information.

```APIDOC
## POST /api/task/browser-use/start

### Description
Starts a new browser use task asynchronously. You can monitor its progress by polling its status.

### Method
POST

### Endpoint
/api/task/browser-use/start

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your Hyperbrowser API key.

#### Request Body
- **task** (string) - Required - The instruction or query for the AI agent.
- **llm** (string) - Required - The language model to use (e.g., "gemini-2.0-flash").
- **maxSteps** (integer) - Optional - The maximum number of steps the agent can take.

### Request Example
```json
{
  "task": "What is the title of the first post on Hacker News today?",
  "llm": "gemini-2.0-flash",
  "maxSteps": 20
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier for the started task.
- **liveUrl** (string) - A URL to monitor the task's progress live.

#### Response Example
```json
{
  "jobId": "some-job-id",
  "liveUrl": "https://hyperbrowser.ai/task/some-job-id"
}
```

## GET /api/task/browser-use/{jobId}/status

### Description
Retrieves the current status of a running or completed browser use task.

### Method
GET

### Endpoint
/api/task/browser-use/{jobId}/status

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the task to check.

#### Query Parameters
- **apiKey** (string) - Required - Your Hyperbrowser API key.

### Response
#### Success Response (200)
- **status** (string) - The current status of the task (e.g., "pending", "running", "completed", "failed").

#### Response Example
```json
{
  "status": "running"
}
```

## GET /api/task/browser-use/{jobId}

### Description
Retrieves the final result of a completed browser use task.

### Method
GET

### Endpoint
/api/task/browser-use/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the task to retrieve.

#### Query Parameters
- **apiKey** (string) - Required - Your Hyperbrowser API key.

### Response
#### Success Response (200)
- **status** (string) - The final status of the task.
- **data** (object) - Contains the task results if completed successfully.
  - **finalResult** (string) - The final outcome of the task.
  - **steps** (array) - An array detailing the steps taken by the agent.
- **error** (string) - An error message if the task failed.

#### Response Example (Success)
```json
{
  "status": "completed",
  "data": {
    "finalResult": "The title of the first post is 'New Feature: AI-powered Search'.",
    "steps": [
      {"action": "open", "url": "https://news.ycombinator.com/"},
      {"action": "extract_text", "element": "a.title"}
    ]
  }
}
```

#### Response Example (Failure)
```json
{
  "status": "failed",
  "error": "Failed to fetch the page content."
}
```
```

--------------------------------

### POST /api/task/cua - Start CUA Task (Synchronous)

Source: https://www.hyperbrowser.ai/docs/agents/openai-cua

Starts an AI agent task using OpenAI's CUA and waits for the result. This method blocks until the task completes.

```APIDOC
## POST /api/task/cua

### Description
Executes an AI agent task using OpenAI's Computer-Using Agent (CUA) and waits for the task to complete before returning the result. This is suitable for tasks that are expected to finish in a reasonable amount of time.

### Method
POST

### Endpoint
/api/task/cua

### Parameters
#### Query Parameters
None

#### Request Body
- **task** (string) - Required - A description of the task the AI agent should perform.
- **maxSteps** (integer) - Optional - The maximum number of steps the agent can take to complete the task. Defaults to a reasonable value if not provided.

### Request Example
```json
{
  "task": "Go to Hacker News and tell me the title of the top post",
  "maxSteps": 20
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier for the started task.
- **liveUrl** (string) - A URL to monitor the task's progress in real-time.
- **data** (object) - Contains the final result of the task upon completion.
  - **finalResult** (string) - The outcome of the executed task.

#### Response Example
```json
{
  "jobId": "abc123",
  "liveUrl": "https://app.hyperbrowser.ai/task/abc123",
  "data": {
    "finalResult": "The title of the top post is 'New AI Model Announced'"
  }
}
```

#### Error Handling
- **400 Bad Request**: Invalid request payload or parameters.
- **401 Unauthorized**: Invalid or missing API key.
- **500 Internal Server Error**: An unexpected error occurred on the server.
```

--------------------------------

### POST /api/task/claude-computer-use - Start and Wait Task

Source: https://www.hyperbrowser.ai/docs/agents/claude-computer-use

Initiates a Claude Computer Use task and waits for its completion. This method is suitable for tasks where you need the result immediately upon completion.

```APIDOC
## POST /api/task/claude-computer-use

### Description
Initiates a Claude Computer Use task and waits for its completion. This method is suitable for tasks where you need the result immediately upon completion.

### Method
POST

### Endpoint
https://api.hyperbrowser.ai/api/task/claude-computer-use

### Parameters
#### Query Parameters
None

#### Request Body
- **task** (string) - Required - The natural language instruction for the task to be performed.
- **llm** (string) - Required - The language model to use (e.g., "claude-sonnet-4-5").
- **maxSteps** (integer) - Optional - The maximum number of steps the agent can take to complete the task.

### Request Example
```json
{
  "task": "Go to Hacker News and tell me the title of the top post",
  "llm": "claude-sonnet-4-5",
  "maxSteps": 20
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier for the initiated task.
- **liveUrl** (string) - A URL to monitor the task's progress.
- **data** (object) - Contains the final result of the task when completed.
  - **finalResult** (string) - The outcome of the executed task.

#### Response Example
```json
{
  "jobId": "abc123",
  "liveUrl": "https://...",
  "data": {
    "finalResult": "The title of the top post on Hacker News is ..."
  }
}
```
```

--------------------------------

### Start a Gemini Computer Use Task

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Initiates an AI agent task using a Gemini model to accomplish a specified goal within a browser environment. Supports session management and advanced configuration.

```APIDOC
## POST /websites/hyperbrowser_ai_agents

### Description
Starts an AI agent task with a Gemini model to perform a natural language-defined task. This endpoint allows for detailed configuration of the AI agent's behavior, including model selection, step limits, session management, and API key usage.

### Method
POST

### Endpoint
/websites/hyperbrowser_ai_agents

### Parameters
#### Request Body
- **task** (string) - Required - Natural language description of what you want Gemini to accomplish. Be specific for best results.
- **llm** (string) - Optional - Gemini model to use. Defaults to `gemini-2.5-computer-use-preview-10-2025`.
- **maxSteps** (number) - Optional - Maximum number of actions Gemini can take. Defaults to 20.
- **maxFailures** (number) - Optional - Maximum consecutive failures before the task is aborted. Defaults to 3.
- **sessionId** (string) - Optional - ID of an existing browser session to reuse.
- **keepBrowserOpen** (boolean) - Optional - Keep the browser session alive after task completion. Defaults to false.
- **useComputerAction** (boolean) - Optional - Allow the agent to interact by executing actions on the actual computer. Defaults to false.
- **sessionOptions** (object) - Optional - Session configuration (proxy, stealth, captcha solving, etc.). Only applies when creating a new session.
- **useCustomApiKeys** (boolean) - Optional - Use your own Google API key instead of consuming Hyperbrowser credits. Defaults to false.
- **apiKeys** (object) - Optional - API key for `google`. Required when `useCustomApiKeys` is true.
  ```typescript
  {
    google: "..."
  }
  ```

### Request Example
```json
{
  "task": "Summarize the content of the current webpage and save it to a file named summary.txt",
  "maxSteps": 50,
  "keepBrowserOpen": true
}
```

### Response
#### Success Response (200)
- **taskId** (string) - ID of the initiated task.
- **sessionId** (string) - ID of the browser session used or created.

#### Response Example
```json
{
  "taskId": "task_abc123",
  "sessionId": "session_xyz789"
}
```

### Notes
- Increasing `maxSteps` may help complete complex tasks.
- Browser sessions have a default timeout, which can be adjusted in settings or via `sessionOptions`.
- `useComputerAction` enhances agent interaction by allowing direct computer primitive actions, useful for elements not accessible via Playwright.
```

--------------------------------

### POST /api/task/cua - Start and Wait for CUA Task

Source: https://www.hyperbrowser.ai/docs/agents/openai-cua

Initiates a 'Create, Understand, Act' (CUA) task and waits for its completion. This endpoint allows for reusing existing browser sessions and optionally keeping them open after task execution.

```APIDOC
## POST /api/task/cua

### Description
Starts a Create, Understand, Act (CUA) task and waits for the result. You can specify an existing `sessionId` to reuse a browser session and `keepBrowserOpen` to prevent the session from closing after the task.

### Method
POST

### Endpoint
/api/task/cua

### Parameters
#### Request Body
- **task** (string) - Required - The task to be executed by the AI agent.
- **sessionId** (string) - Optional - The ID of an existing browser session to reuse.
- **keepBrowserOpen** (boolean) - Optional - If true, the browser session will remain open after the task completes. Defaults to false.
- **useCustomApiKeys** (boolean) - Optional - If true, allows using custom API keys for LLM calls.
- **apiKeys** (object) - Optional - An object containing custom API keys. 
  - **openai** (string) - Optional - Your OpenAI API key.

### Request Example
```json
{
  "task": "What is the title of the first post on Hacker News today?",
  "sessionId": "existing_session_id",
  "keepBrowserOpen": true
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the task results.
  - **finalResult** (string) - The final output of the CUA task.

#### Response Example
```json
{
  "data": {
    "finalResult": "The title of the first post on Hacker News today is '...'"
  }
}
```
```

--------------------------------

### TypeScript API Keys Configuration

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Example of how to configure custom API keys for Google, specifically for the 'google' service. This is required when `useCustomApiKeys` is set to true and allows the agent to use your own API key instead of Hyperbrowser credits.

```typescript
{
  google: "..."
}
```

--------------------------------

### POST /api/task/gemini-computer-use

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Starts a Gemini Computer Use task. This endpoint initiates a task that allows Gemini to interact with your computer, such as moving the cursor, clicking, typing, and navigating the web. It returns a jobId for tracking.

```APIDOC
## POST /api/task/gemini-computer-use

### Description
Starts a Gemini Computer Use task that allows Gemini to interact with your computer to perform actions like moving the cursor, clicking, typing, and navigating the web. This is useful for automating complex, multi-step workflows.

### Method
POST

### Endpoint
https://api.hyperbrowser.ai/api/task/gemini-computer-use

### Parameters
#### Query Parameters
None

#### Request Body
- **task** (string) - Required - The description of the task Gemini should perform.
- **maxSteps** (integer) - Optional - The maximum number of steps Gemini should take to complete the task.

### Request Example
```json
{
  "task": "Go to Hacker News and tell me the title of the top post",
  "maxSteps": 20
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier for the task.
- **liveUrl** (string) - A URL to monitor the task's progress (if applicable).

#### Response Example
```json
{
  "jobId": "abc123",
  "liveUrl": "https://..."
}
```
```

--------------------------------

### Run Gemini Computer Use Task (Python)

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Perform a Gemini Computer Use task using the Hyperbrowser Python SDK. This example utilizes the 'start_and_wait' method for synchronous execution and result retrieval. Ensure your HYPERBROWSER_API_KEY is loaded from environment variables using python-dotenv.

```python
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartGeminiComputerUseTaskParams
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.gemini_computer_use.start_and_wait(
    params=StartGeminiComputerUseTaskParams(
        task="Go to Hacker News and tell me the title of the top post",
        max_steps=20
    )
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### GET /api/task/cua/{jobId}/status - Check CUA Task Status

Source: https://www.hyperbrowser.ai/docs/agents/openai-cua

Retrieves the current status of a previously started CUA task using its unique job ID.

```APIDOC
## GET /api/task/cua/{jobId}/status

### Description
Checks the current status of an ongoing or completed AI agent task initiated via the CUA API. This is useful for long-running tasks when using the asynchronous pattern.

### Method
GET

### Endpoint
/api/task/cua/{jobId}/status

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The unique identifier of the task to check.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl https://api.hyperbrowser.ai/api/task/cua/abc123/status \
  -H "x-api-key: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the job (e.g., 'processing', 'completed', 'failed').
- **progress** (integer) - The percentage of task completion.

#### Response Example
```json
{
  "status": "processing",
  "progress": 50
}
```

#### Error Handling
- **404 Not Found**: The specified jobId does not exist.
- **401 Unauthorized**: Invalid or missing API key.
- **500 Internal Server Error**: An unexpected error occurred on the server.
```

--------------------------------

### Run Gemini Computer Use Task (Node.js)

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Execute a Gemini Computer Use task using the Hyperbrowser SDK in Node.js. This example demonstrates the 'startAndWait' method, which simplifies the process by blocking until the task is complete and returning the result. It requires setting the HYPERBROWSER_API_KEY environment variable.

```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  const result = await client.agents.geminiComputerUse.startAndWait({
    task: "Go to Hacker News and tell me the title of the top post",
    maxSteps: 20,
  });

  console.log(`Output:\n${result.data?.finalResult}`);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});
```

--------------------------------

### Configure Gemini Computer Use Session with Options (Node.js, Python, cURL)

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Demonstrates how to start a Gemini Computer Use agent task with custom session options, such as accepting cookies. This applies when creating a new session; options are ignored if a sessionId is provided. Dependencies include the Hyperbrowser SDK and dotenv.

```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const result = await client.agents.geminiComputerUse.startAndWait({
    task: "What is the title of the first post on Hacker News today?",
    sessionOptions: {
      acceptCookies: true,
    }
  });

  console.log(`Output:\n\n${result.data?.finalResult}`);
};

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});
```

```python
import os
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartGeminiComputerUseTaskParams, CreateSessionParams
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

def main():
    resp = client.agents.gemini_computer_use.start_and_wait(
        StartGeminiComputerUseTaskParams(
            task="What is the title of the first post on Hacker News 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}")
```

```bash
curl -X POST https://api.hyperbrowser.ai/api/task/gemini-computer-use \
  -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?",
      "sessionOptions": {
          "acceptCookies": true
      }
  }'
```

--------------------------------

### Start and Wait for Browser-Use Agent Task (Node.js)

Source: https://www.hyperbrowser.ai/docs/agents/overview

Initiates a Browser-Use agent task and waits for its completion. Requires the Hyperbrowser SDK and dotenv for API key management. It takes a task description, LLM model, and maximum steps as input, returning the final result of the task.

```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  const result = await client.agents.browserUse.startAndWait({
    task: "Go to Hacker News and tell me the title of the top post",
    llm: "gemini-2.0-flash",
    maxSteps: 20,
  });

  console.log(`Output:\n${result.data?.finalResult}`);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});
```

--------------------------------

### Execute CUA Task via cURL (Async Pattern)

Source: https://www.hyperbrowser.ai/docs/agents/openai-cua

Demonstrates initiating and monitoring an AI agent task using OpenAI's CUA via cURL requests. It includes steps to start a task, check its status, and retrieve the final results. Requires a valid API key.

```bash
# Start the task
curl -X POST https://api.hyperbrowser.ai/api/task/cua \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "task": "Go to Hacker News and tell me the title of the top post",
  "maxSteps": 20
}'

# Response: {"jobId": "abc123", "liveUrl": "https://..."}

# Check status
curl https://api.hyperbrowser.ai/api/task/cua/abc123/status \
  -H "x-api-key: YOUR_API_KEY"

# Get full results
curl https://api.hyperbrowser.ai/api/task/cua/abc123 \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Install HyperAgent SDK

Source: https://www.hyperbrowser.ai/docs/agents/hyperagent

Installs the HyperAgent SDK and dotenv package for managing environment variables. Available for npm, yarn, pip, and uv.

```bash
npm install @hyperbrowser/sdk dotenv
```

```bash
yarn add @hyperbrowser/sdk dotenv
```

```bash
pip install hyperbrowser python-dotenv
```

```bash
uv add hyperbrowser python-dotenv
```

--------------------------------

### Stop a Running Task

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

This section provides instructions and examples for stopping a running AI task before it completes. It includes examples for Node.js, Python, and cURL.

```APIDOC
## Stop a Running Task

Stop a task before it completes:

### Node.js Example

```typescript
await client.agents.geminiComputerUse.stop("job-id");
```

### Python Example

```python
client.agents.gemini_computer_use.stop("job-id")
```

### cURL Example

```bash
curl -X PUT https://api.hyperbrowser.ai/api/task/gemini-computer-use/job-id/stop \
  -H "x-api-key: YOUR_API_KEY"
```
```

--------------------------------

### POST /api/agents/geminiComputerUse/startAndWait (Reuse Browser Sessions)

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Initiates the Gemini Computer Use task, allowing for the reuse of an existing browser session via `sessionId` and optionally keeping the session open after completion with `keepBrowserOpen`.

```APIDOC
## POST /api/agents/geminiComputerUse/startAndWait

### Description
Initiates the Gemini Computer Use task, allowing for the reuse of an existing browser session via `sessionId` and optionally keeping the session open after completion with `keepBrowserOpen`.

### Method
POST

### Endpoint
/api/agents/geminiComputerUse/startAndWait

### Parameters
#### Request Body
- **task** (string) - Required - The task to be executed by the agent.
- **sessionId** (string) - Optional - The ID of an existing browser session to reuse.
- **keepBrowserOpen** (boolean) - Optional - If true, the browser session will remain open after the task completes. Defaults to false.

### Request Example (Node.js)
```javascript
const result = await client.agents.geminiComputerUse.startAndWait({
  task: "What is the title of the first post on Hacker News today?",
  sessionId: session.id,
  keepBrowserOpen: true,
});
```

### Request Example (Python)
```python
resp = client.agents.gemini_computer_use.start_and_wait(
    StartGeminiComputerUseTaskParams(
        task="What is the title of the first post on Hacker News today?",
        session_id=session.id,
        keep_browser_open=True,
    )
)
```

### Response
#### Success Response (200)
- **data** (object) - Contains the result of the task execution.
  - **finalResult** (string) - The final output of the agent's task.

#### Response Example
```json
{
  "data": {
    "finalResult": "The title of the first post on Hacker News today is 'Some Title'."
  }
}
```
```

--------------------------------

### GET /api/task/cua/{jobId} - Get Full CUA Task Results

Source: https://www.hyperbrowser.ai/docs/agents/openai-cua

Retrieves the complete results of a CUA task once it has finished execution, using its job ID.

```APIDOC
## GET /api/task/cua/{jobId}

### Description
Retrieves the full details and results of a completed AI agent task. This endpoint should be called after confirming the task status is 'completed'.

### Method
GET

### Endpoint
/api/task/cua/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The unique identifier of the completed task.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl https://api.hyperbrowser.ai/api/task/cua/abc123 \
  -H "x-api-key: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier for the task.
- **status** (string) - The final status of the job (e.g., 'completed', 'failed').
- **data** (object) - Contains the final result of the task.
  - **finalResult** (string) - The outcome of the executed task.
- **logs** (array) - An array of log entries from the task execution.

#### Response Example
```json
{
  "jobId": "abc123",
  "status": "completed",
  "data": {
    "finalResult": "The top post on Hacker News is titled 'OpenAI Releases New Agent Capabilities'."
  },
  "logs": [
    {
      "timestamp": "2023-10-27T10:00:00Z",
      "message": "Navigating to Hacker News..."
    },
    {
      "timestamp": "2023-10-27T10:00:05Z",
      "message": "Extracted top post title."
    }
  ]
}
```

#### Error Handling
- **404 Not Found**: The specified jobId does not exist or the task has not completed yet.
- **401 Unauthorized**: Invalid or missing API key.
- **500 Internal Server Error**: An unexpected error occurred on the server.
```
Tokens:
Raw