Skip to main content
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: 
npm install @uplink-code/ai

​
Creating an Agent

Use the ai.createAgent() factory function to create an agent: 
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. 
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 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)

OpenAI support is coming soon and not yet available.
// 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: Set the agent when connecting to apply it to all browsers and pages: 
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('<organization-api-key>', {
  projectId: '<project-id>',
  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: 
const session = await uplink.session('<organization-api-key>', {
  projectId: '<project-id>',
  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: 
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
Access them in your code: 
const agent = ai.createAgent({
  provider: 'anthropic',
  options: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
})
Never commit API keys to version control. Use environment variables or a secrets manager.

​
Complete Setup Example

Here’s a complete example with environment variables and error handling: 
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('<organization-api-key>', {
  projectId: '<project-id>',
  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

Natural Language Actions

Use page.act() to perform actions with AI

Data Extraction

Extract structured data with page.extract()