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

# AI Agent Setup

> Configure AI agents for browser automation with Anthropic or OpenAI

To use AI features in Uplink, you need to create an AI agent and configure it with your preferred provider.

## Installation

First, install the AI package:

```bash theme={null}
npm install @uplink-code/ai
```

## Creating an Agent

Use the `ai.createAgent()` factory function to create an agent:

```typescript theme={null}
import ai from '@uplink-code/ai'

const agent = ai.createAgent({
  provider: 'anthropic',
  options: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
})
```

## Provider Configuration

### Anthropic (Claude)

Anthropic's Claude models are fully supported and recommended for browser automation.

```typescript theme={null}
import ai from '@uplink-code/ai'

const agent = ai.createAgent({
  provider: 'anthropic',
  model: 'claude-sonnet-4-5-20250929', // optional, this is the default
  maxTokens: 4096, // optional
  options: {
    apiKey: process.env.ANTHROPIC_API_KEY,
    // Additional Anthropic SDK options
    baseURL: 'https://api.anthropic.com', // optional
    defaultHeaders: {} // optional
  }
})
```

**Get an API key**: Sign up at [console.anthropic.com](https://console.anthropic.com) and create an API key.

**Available models**:

* `claude-sonnet-4-5-20250929` (default) - Best balance of speed and intelligence
* `claude-opus-4-5-20251101` - Most capable, slower and more expensive
* `claude-haiku-4-20241024` - Fastest and cheapest, less capable

### OpenAI (GPT)

<Warning>
  OpenAI support is coming soon and not yet available.
</Warning>

```typescript theme={null}
// Coming soon
const agent = ai.createAgent({
  provider: 'openai',
  model: 'gpt-4',
  maxTokens: 4096,
  options: {
    apiKey: process.env.OPENAI_API_KEY
  }
})
```

## Using the Agent

You can set the agent at two levels:

### Client-Level Agent (Recommended)

Set the agent when connecting to apply it to all browsers and pages:

```typescript theme={null}
import uplink from '@uplink-code/uplink'
import ai from '@uplink-code/ai'

const agent = ai.createAgent({
  provider: 'anthropic',
  options: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
})

// Agent applies to all browsers and pages
const session = await uplink.session('<project-api-key>', {
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session, { agent })
const browser = await client.launch()
const page = await browser.newPage()

// AI methods now available
await page.act('Click the login button')
```

### Page-Level Agent

Override the agent for a specific page:

```typescript theme={null}
const session = await uplink.session('<project-api-key>', {
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session)
const browser = await client.launch()
const page = await browser.newPage()

// Set agent on this page only
const agent = ai.createAgent({
  provider: 'anthropic',
  options: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
})

page.setAgent(agent)

// AI methods now available on this page
await page.act('Fill in the form')
```

## Environment Variables

Store API keys in environment variables for security:

```bash theme={null}
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
```

Access them in your code:

```typescript theme={null}
const agent = ai.createAgent({
  provider: 'anthropic',
  options: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
})
```

<Warning>
  Never commit API keys to version control. Use environment variables or a secrets manager.
</Warning>

## Complete Setup Example

Here's a complete example with environment variables and error handling:

```typescript theme={null}
import uplink from '@uplink-code/uplink'
import ai from '@uplink-code/ai'
import 'dotenv/config' // Load .env file

// Validate API key
if (!process.env.ANTHROPIC_API_KEY) {
  throw new Error('ANTHROPIC_API_KEY environment variable is required')
}

// Create agent
const agent = ai.createAgent({
  provider: 'anthropic',
  options: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
})

// Connect with agent
const session = await uplink.session('<project-api-key>', {
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session, { agent })

try {
  const browser = await client.launch()
  const page = await browser.newPage()

  await page.goto('https://example.com')
  await page.act('Click the get started button')

  await page.close()
  await browser.close()
} finally {
  await client.close()
}
```

## Cost Considerations

AI automation makes API calls to your chosen provider, which incurs costs:

* **Anthropic Claude**: \~\$3-15 per 1M input tokens depending on model
* **OpenAI GPT**: \~\$2.50-30 per 1M input tokens depending on model

Each `act()` or `extract()` call sends page context (usually 1-5K tokens) plus your instruction.

**Tips to reduce costs**:

* Use Haiku model for simple tasks
* Use `act()` sparingly for complex interactions only
* Combine multiple actions into one instruction when possible
* Cache results when extracting the same data repeatedly

## Next Steps

<CardGroup cols={2}>
  <Card title="Natural Language Actions" icon="wand-magic-sparkles" href="./act">
    Use page.act() to perform actions with AI
  </Card>

  <Card title="Data Extraction" icon="database" href="./extract">
    Extract structured data with page.extract()
  </Card>
</CardGroup>