SDK Quick Start

This page is a quick start using our official SDK. For complete documentation and advanced usage examples, visit our package repositories:

Node.js: anchorbrowser on npm
Python: anchorbrowser on PyPI

Fetch API Key

In Anchor UI, copy your API key

Install the SDK

npm install anchorbrowser

pip install anchorbrowser

Initialize the SDK

Set up the Anchor Browser client with your API key:

import AnchorClient from "anchorbrowser";

const anchorClient = new AnchorClient({
  apiKey: process.env.ANCHOR_API_KEY,
});

import os
from anchorbrowser import Anchorbrowser

anchor_client = Anchorbrowser(
    api_key=os.getenv("ANCHOR_API_KEY")
)

AI Agent Browser Automation

Use AI agents to automate browser tasks with natural language commands:

(async () => {
  // Simple navigation task
  const result = await anchorClient.agent.task(
    "go to news.ycombinator.com and get the title of the first story"
  );
  console.log("Task result:", result);
  
  // Task with execution step monitoring
  const executionStepLogs = [];
  const navigationResult = await anchorClient.agent.task(
    "go to news.ycombinator.com and get the title of the first story",
    {
      taskOptions: {
        onAgentStep: (executionStep) => {
          console.log("Agent step:", executionStep);
          executionStepLogs.push(executionStep);
        },
      },
    }
  );
  console.log("Navigation result:", navigationResult)
  console.log("Execution step logs count:", executionStepLogs.length)
  })();

# Simple navigation task
result = anchor_client.agent.task(
    "go to news.ycombinator.com and get the title of the first story"
)
print("Task result:", result)

# Task with execution step monitoring
execution_step_logs = []
def on_agent_step(execution_step):
    print("Agent step:", execution_step)
    execution_step_logs.append(execution_step)

navigation_result = anchor_client.agent.task(
    "go to news.ycombinator.com and get the title of the first story",
    task_options={
        "on_agent_step": on_agent_step
    }
)
print("Navigation result:", navigation_result)
print("Execution step logs count:", len(execution_step_logs))

Additional Usage

Structured Data Extraction

Extract structured data from webpages using schemas:

import { z } from "zod";

(async () => {

  // Define your data schema
  const extractionSchema = z.object({
    title: z.string(),
    description: z.string(),
    price: z.string().optional(),
  });
  
  // Extract structured data from product page
  const structuredResult = await anchorClient.agent.task(
    "Extract the product title, description, and price from this Amazon product page",
    {
      taskOptions: {
        outputSchema: z.toJSONSchema(extractionSchema),
        url: "https://www.amazon.com/dp/B0D7D9N7X3",
      },
    }
  );
  
  // agent.task returns { data: { result } }, where result is a JSON string.
  const rawResult = structuredResult.data.result;
  const parsedResult = JSON.parse(rawResult);

  // Validate the result against your schema
  const validatedData = extractionSchema.safeParse(parsedResult);
  if (validatedData.success) {
    console.log("Product title:", validatedData.data.title);
    console.log("Description:", validatedData.data.description);
    console.log("Price:", validatedData.data.price);
  } else {
    console.error("Validation failed:", validatedData.error);
  }
})();

from pydantic import BaseModel
from typing import Optional
import ast

# Define your data schema
class ProductSchema(BaseModel):
    title: str
    description: str
    price: Optional[str] = None

# Extract structured data from product page
structured_result = anchor_client.agent.task(
    "Extract the product title, description, and price from this Amazon product page",
    task_options={
        "output_schema": ProductSchema.model_json_schema(),
        "url": "https://www.amazon.com/dp/B0D7D9N7X3"
    }
)

# Validate the result
validated_data = ProductSchema.model_validate(ast.literal_eval(structured_result))   
print("Product title:", validated_data.title)
print("Description:", validated_data.description)
print("Price:", validated_data.price)

Screenshots

Capture screenshots of your current session view.

import fs from "fs/promises";

(async () => {
  // Create a session for screenshot
  const screenshotSession = await anchorClient.sessions.create();
  const screenshotBrowser = await anchorClient.browser.connect(screenshotSession.data.id);
  const screenshotPage = screenshotBrowser.contexts()[0].pages()[0];
  await screenshotPage.goto("https://example.com");

  // Capture screenshot from the session
  const screenshot = await anchorClient.tools.screenshotWebpage({
    sessionId: screenshotSession.data.id,
  });

  // Get screenshot data
  const buffer = await screenshot.arrayBuffer();
  console.log("Screenshot captured, size:", buffer.byteLength);

  // Save screenshot to file
  await fs.writeFile("screenshot.png", Buffer.from(buffer));
  console.log("Screenshot saved as screenshot.png");
})();

# Create a session for screenshot
screenshot_session = anchor_client.sessions.create()
with anchor_client.browser.connect(screenshot_session.data.id) as screenshot_browser:
    screenshot_page = screenshot_browser.contexts[0].pages[0]
    screenshot_page.goto("https://example.com")

# Capture screenshot from the session
screenshot = anchor_client.tools.screenshot_webpage(
    session_id=screenshot_session.data.id
)

# Get screenshot data
screenshot_data = screenshot.read()
print("Screenshot captured, size:", len(screenshot_data))

# Save screenshot to file
with open("screenshot.png", "wb") as f:
   f.write(screenshot_data)
   print("Screenshot saved as screenshot.png")

Advanced Configuration

Configure browser sessions with proxies, timeouts, and other options:

// Create session with advanced configuration
const sessionConfig = {
  session: {
    recording: {active: false}, // Disable session recording
    proxy: {
      active: true,
      country_code: "us",
    },
    timeout: {
      max_duration: 5, // 5 minutes
      idle_timeout: 1, // 1 minute
    }
  },
};

const configuredSession = await anchorClient.sessions.create(sessionConfig);
const result = await anchorClient.agent.task(
  "What is my IP address and where am I?",
  {
  sessionId: configuredSession.data.id,
});
console.log(result);

# Create session with advanced configuration
session_config = {
  "recording": {"active": False},  # Disable session recording
  "proxy": {
      "active": True,
      "country_code": "us"
  },
  "timeout": {
      "max_duration": 5,
      "idle_timeout": 1
  }
}

configured_session = anchor_client.sessions.create(session=session_config)
result = anchor_client.agent.task(
  session_options=configured_session,
  prompt="What is my IP address and where am I?"
  )
print(result)

From SDK to Browser: Run Extra Playwright Code

Standalone Browser Creation

Create a standalone browser instance:

(async () => {
// Create standalone browser
const standaloneBrowser = await anchorClient.browser.create();
const page = standaloneBrowser.contexts()[0].pages()[0];
await page.goto("https://httpbin.org/ip");

console.log("Current URL:", page.url());

// Disconnect (session keeps running)
standaloneBrowser.close();
})();

# Create standalone browser
with anchor_client.browser.create() as standalone_browser:
    page = standalone_browser.contexts[0].pages[0]
    page.goto("https://httpbin.org/ip")
    print("Current URL:", page.url)

Browser Task with Session Control

Use AI agents with direct browser control:

// browserTask starts the agent in the background and immediately returns the
// live Playwright browser for the same session.
const browserTask = await anchorClient.agent.browserTask(
  "go to github.com/trending and find the most popular JavaScript repository"
);

console.log("Session ID:", browserTask.sessionId);

// Let the agent finish its task BEFORE you drive the page yourself, otherwise
// your Playwright navigation and the agent fight over the same tab.
const taskResult = await browserTask.taskResultPromise;
console.log("Agent result:", taskResult.data.result);

// Now take manual control of the same session with Playwright.
const playwrightBrowser = browserTask.playwrightBrowser;
const page = playwrightBrowser.contexts()[0].pages()[0];
await page.goto("https://stackoverflow.com/");
console.log("Current URL:", page.url());

browserTask.playwrightBrowser.close();

# Browser task with session control
browser_task = anchor_client.agent.browser_task(
    "go to github.com/trending and find the most popular JavaScript repository"
)

print("Session ID:", browser_task["session_id"])

# Access the Playwright browser instance
playwright_browser = browser_task["playwright_browser"]
with playwright_browser as browser:
    page = browser.contexts[0].pages[0]

    # Direct Playwright manipulation
    page.goto("https://stackoverflow.com/")
    print("Current URL:", page.url)

    # Wait for task completion
    task_result = browser_task["task_result_task"]
    print("Final result:", task_result)

Manual Session Management

Create and manage browser sessions manually:

// Create session and connect it later
const sessionResponse = await anchorClient.sessions.create();
const sessionId = sessionResponse.data.id;

const browser = await anchorClient.browser.connect(sessionId);
const context = browser.contexts()[0];
const page = context.pages()[0];
await page.goto("https://reddit.com/r/programming");

console.log("Current URL:", page.url());

browser.close();

# Create session and connect it later
session_response = anchor_client.sessions.create()
session_id = session_response.data.id

with anchor_client.browser.connect(session_id) as browser:
    context = browser.contexts[0]
    page = context.pages[0]
    page.goto("https://reddit.com/r/programming")
    print("Current URL:", page.url)

Key SDK Benefits

The Anchor Browser SDK provides several advantages over direct API usage:

AI Agent Integration: Use natural language to automate complex browser tasks
Structured Data Extraction: Define schemas and extract data in a predictable format
Seamless Playwright Integration: Full access to Playwright’s powerful browser automation capabilities
Session Management: Easy creation and management of persistent browser sessions
Built-in Tools: Screenshot capture, proxy management, and more
Type Safety: Full TypeScript support with proper type definitions

Next Steps

Explore the API Reference for detailed documentation
Learn about Managed Authentication
Check out Advanced Proxy Configuration for location-specific browsing

Introduction

Platform

Integrations

Account

Additional Usage

Structured Data Extraction

Screenshots

Advanced Configuration

From SDK to Browser: Run Extra Playwright Code

Standalone Browser Creation

Browser Task with Session Control

Manual Session Management

Key SDK Benefits

Next Steps

​Additional Usage

​Structured Data Extraction

​Screenshots

​Advanced Configuration

​From SDK to Browser: Run Extra Playwright Code

​Standalone Browser Creation

​Browser Task with Session Control

​Manual Session Management

​Key SDK Benefits

​Next Steps

Additional Usage

Structured Data Extraction

Screenshots

Advanced Configuration

From SDK to Browser: Run Extra Playwright Code

Standalone Browser Creation

Browser Task with Session Control

Manual Session Management

Key SDK Benefits

Next Steps