> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build your first HyperAgent automation in under a minute

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @hyperbrowser/agent
  ```

  ```bash yarn theme={null}
  yarn add @hyperbrowser/agent
  ```

  ```bash pnpm theme={null}
  pnpm add @hyperbrowser/agent
  ```
</CodeGroup>

## Choose Your LLM Provider

HyperAgent needs an LLM to power its AI capabilities. We recommend setting environment variables for your API keys.

<CodeGroup>
  ```bash OpenAI theme={null}
  export OPENAI_API_KEY="sk-..."
  ```

  ```bash Anthropic theme={null}
  export ANTHROPIC_API_KEY="sk-ant-..."
  ```

  ```bash Gemini theme={null}
  export GOOGLE_API_KEY="..."
  ```
</CodeGroup>

## Your First Automation

Create a file called `demo.ts`:

```typescript theme={null}
import { HyperAgent } from "@hyperbrowser/agent";

async function main() {
  // Initialize the agent
  const agent = new HyperAgent({
    llm: {
      provider: "openai",
      model: "gpt-5.1",
    },
  });

  // Create a new browser page
  const page = await agent.newPage();

  // Navigate and automate
  await page.goto("https://news.ycombinator.com");
  
  const result = await page.ai(
    "Find the top story and tell me the title and point count"
  );

  console.log(result.output);

  // Remember to close the agent when you're done, otherwise the session will stay open.
  await agent.closeAgent();
}

main();
```

Run it:

```bash theme={null}
npx tsx demo.ts
```

## CLI Mode

For quick one-off tasks, use the CLI:

```bash theme={null}
npx @hyperbrowser/agent -c "Go to google.com and search for 'best pizza in NYC'"
```

**CLI Options:**

| Flag                   | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `-c, --command <task>` | Natural language command to run                 |
| `-d, --debug`          | Enable debug mode with verbose output           |
| `--hyperbrowser`       | Use Hyperbrowser cloud instead of local browser |

## Get Started with 3 Core Methods

HyperAgent gives you three ways to interact with pages:

### 1. `page.ai()` — Complex Tasks

For multi-step workflows where AI makes decisions:

```typescript theme={null}
await page.ai("search for flights from Miami to LAX, select the cheapest option");
```

### 2. `page.perform()` — Single Actions

For fast, specific actions:

```typescript theme={null}
await page.perform("click the login button");
await page.perform("fill email with user@example.com");
```

### 3. `page.extract()` — Data Extraction

For pulling structured data:

```typescript theme={null}
import { z } from "zod";

const data = await page.extract(
  "get the product details",
  z.object({
    name: z.string(),
    price: z.number(),
    rating: z.number(),
  })
);
```

## Mix and Match

The real power comes from combining these methods:

```typescript theme={null}
const page = await agent.newPage();
await page.goto("https://amazon.com");

// Fast, single-action execution
await page.perform("click the search box");
await page.perform("type 'mechanical keyboard'");
await page.perform("press Enter");

// AI handles the complex part
await page.ai("search for keyboards under $100");

// Extract structured data
const product = await page.extract(
  "Select the first product from the search results",
  z.object({
    name: z.string(),
    price: z.number(),
    rating: z.number(),
  })
);

console.log(product);
```

## Scale to the Cloud

When you're ready to run at scale, switch to [Hyperbrowser](/sessions/create):

```typescript theme={null}
const agent = new HyperAgent({
  browserProvider: "Hyperbrowser", // That's it!
});
```

<Note>
  You'll need a `HYPERBROWSER_API_KEY`. Get one free at [app.hyperbrowser.ai](https://app.hyperbrowser.ai).
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="page.ai()" icon="brain" href="/hyperagent/page-ai">
    Deep dive into multi-step automation
  </Card>

  <Card title="page.perform()" icon="bolt" href="/hyperagent/page-perform">
    Learn about single-action execution
  </Card>

  <Card title="Data Extraction" icon="database" href="/hyperagent/extract">
    Extract structured data with schemas
  </Card>

  <Card title="Configuration" icon="gear" href="/hyperagent/llm-providers">
    Configure LLMs and browser settings
  </Card>
</CardGroup>