@uplink-code/ai

AI agent plugin for Uplink browser automation. This package provides AI-powered methods (act and extract) for natural language browser automation.

Installation

npm install @uplink-code/ai

Note: This package has a peer dependency on @uplink-code/uplink. The zod package is included as a dependency, so you don't need to install it separately.

Usage

Basic Setup

import uplink from '@uplink-code/uplink'
import ai from '@uplink-code/ai'

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

// Connect to uplink with agent support
const client = await uplink.client.connect('ws://localhost:8080', { agent })
const browser = await client.launch()
const page = await browser.newPage()

// Now you can use AI-powered methods
await page.goto('https://example.com')

Act - Natural Language Actions

Execute browser actions using natural language instructions:

// Single action
await page.act('click the sign in button')

// Multiple actions
await page.act('fill in the email field with "[email protected]" and click submit')

// Get typed results from complex workflows
const result = await page.act('search for "TypeScript" and click the first result')
console.log(result.success, result.actions, result.reasoning)

// TypeScript automatically knows the result structure:
// - result.success: boolean
// - result.actions: Array<{ type: string, params: unknown[], result?: unknown, error?: string }>
// - result.reasoning?: string

Extract - Structured Data Extraction

Extract data from pages with optional schema validation:

import { z } from 'zod'

// Extract without schema - returns unstructured string
const textResult = await page.extract('extract the product name and price')
// textResult.data is typed as { extraction: string } | undefined
if (textResult.success && textResult.data) {
  console.log(textResult.data.extraction)
}

// Extract with Zod schema - automatic type inference!
const productSchema = z.object({
  name: z.string(),
  price: z.number(),
  inStock: z.boolean()
})

const productResult = await page.extract('extract product details', productSchema)
// TypeScript automatically infers productResult.data type from the schema!
// productResult.data is typed as { name: string, price: number, inStock: boolean } | undefined

if (productResult.success && productResult.data) {
  // No type assertions needed - TypeScript knows the exact shape
  console.log(productResult.data.name)      // string
  console.log(productResult.data.price)     // number
  console.log(productResult.data.inStock)   // boolean
}

// Extract arrays of structured data
const accountSchema = z.array(
  z.object({
    routing: z.string(),
    account: z.string()
  })
)

const accountResult = await page.extract('extract all account details', accountSchema)
// accountResult.data is automatically typed as Array<{ routing: string, account: string }> | undefined
if (accountResult.success && accountResult.data) {
  accountResult.data.forEach(account => {
    console.log(`Routing: ${account.routing}, Account: ${account.account}`)
  })
}

Configuration

Anthropic (Claude)

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: 'your-api-key',
    dangerouslyAllowBrowser: true // optional, defaults to true
  }
})

Configuration options:

• provider: Must be 'anthropic'
• model (optional): Model to use. Default: 'claude-sonnet-4-5-20250929'
• maxTokens (optional): Maximum tokens for responses
• options: Accepts all Anthropic SDK ClientOptions:
  • apiKey (optional): Your Anthropic API key. Can also use ANTHROPIC_API_KEY env var
  • dangerouslyAllowBrowser (optional): Allow browser usage. Default: false
  • All other Anthropic SDK options (baseURL, timeout, etc.)

OpenAI (Coming Soon)

import ai from '@uplink-code/ai'

const agent = ai.createAgent({
  provider: 'openai',
  model: 'gpt-4', // optional
  options: {
    apiKey: 'your-api-key'
  }
})

Why a Separate Package?

The @uplink-code/ai package is separate from the core @uplink-code/uplink package to:

• Reduce bundle size: The AI dependencies (@anthropic-ai/sdk and zod) add ~580KB. Users who don't need AI features don't pay this cost.
• Optional functionality: AI features are opt-in. Install this package only when you need them.
• Plugin architecture: The core @uplink-code/uplink package defines the Agent interface, and this package implements it. Clean separation of concerns.
• Lightweight core: Keep the core automation API focused and lightweight (~44KB).

Type Safety

This package provides full TypeScript support with automatic type inference for extracted data:

• With Zod schema: TypeScript automatically infers the exact type from your schema - no manual type annotations or assertions needed
• Without schema: Returns { extraction: string } for unstructured text extraction
• Zero boilerplate: The return type is inferred directly from the schema parameter using TypeScript's advanced type system

License

Proprietary