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

> ## Agent Instructions
> Anchor Browser is cloud browser infrastructure for AI agents and automation: browser sessions you control over CDP or REST, natural-language web tasks, versioned automation tasks, managed authentication into third-party web apps (identities with MFA), persistent volumes and profiles, recordings, live view, batch sessions, webhooks, and network options including residential proxies, extra stealth, and captcha solving for sites that block standard browsers. AI agents should start at https://docs.anchorbrowser.io/for-agents, then get an API key with Agent Access at https://docs.anchorbrowser.io/quickstart/agent-access — no dashboard account required. Read those two pages before authentication or API calls.

# 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](https://www.npmjs.com/package/anchorbrowser)
* **Python**: [anchorbrowser on PyPI](https://pypi.org/project/anchorbrowser/)

<Steps>
  <Step title="Fetch API Key">
    In [Anchor UI](https://app.anchorbrowser.io/api-keys), copy your API key
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash node.js theme={null}
      npm install anchorbrowser
      ```

      ```bash python theme={null}
      pip install anchorbrowser
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize the SDK">
    Set up the Anchor Browser client with your API key:

    <CodeGroup>
      ```javascript node.js theme={null}
      import { client } from "anchorbrowser";

      client.setConfig({ auth: () => process.env.ANCHOR_API_KEY });
      ```

      ```python python theme={null}
      import os
      from anchorbrowser import Anchorbrowser

      anchor_client = Anchorbrowser(
          api_key=os.getenv("ANCHOR_API_KEY")
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="AI Agent Browser Automation">
    Use AI agents to automate browser tasks with natural language commands:

    <CodeGroup>
      ```javascript node.js theme={null}
      import { agentTask } from "anchorbrowser";

      (async () => {
        // Simple navigation task
        const result = await agentTask(
          "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 agentTask(
          "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)
        })();
      ```

      ```python python theme={null}
      # 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))
      ```
    </CodeGroup>
  </Step>
</Steps>

## Additional Usage

### Structured Data Extraction

Extract structured data from webpages using schemas:

<CodeGroup>
  ```javascript node.js theme={null}
  import { z } from "zod";
  import { agentTask } from "anchorbrowser";

  (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 agentTask(
      "Extract the product title, description, and price from this Amazon product page",
      {
        taskOptions: {
          outputSchema: z.toJSONSchema(extractionSchema),
          url: "https://www.amazon.com/dp/B0D7D9N7X3",
        },
      }
    );
    
    // agentTask 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);
    }
  })();
  ```

  ```python python theme={null}
  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)
  ```
</CodeGroup>

### Screenshots

Capture screenshots of your current session view.

<CodeGroup>
  ```javascript node.js theme={null}
  import fs from "fs/promises";
  import { Sessions, Tools, connectBrowser } from "anchorbrowser";

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

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

    // 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");
  })();
  ```

  ```python python theme={null}
  # Create a session for screenshot
  screenshot_session = anchor_client.sessions.create_session()
  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")
  ```
</CodeGroup>

### Advanced Configuration

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

<CodeGroup>
  ```javascript node.js theme={null}
  import { Sessions, agentTask } from "anchorbrowser";

  // 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 Sessions.createSession({ body: sessionConfig });
  const result = await agentTask(
    "What is my IP address and where am I?",
    {
    sessionId: configuredSession.data.id,
  });
  console.log(result);
  ```

  ```python python theme={null}
  # 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=session_config)
  result = anchor_client.agent.task(
    session_options=configured_session,
    prompt="What is my IP address and where am I?"
    )
  print(result)
  ```
</CodeGroup>

## From SDK to Browser: Run Extra Playwright Code

### Standalone Browser Creation

Create a standalone browser instance:

<CodeGroup>
  ```javascript node.js theme={null}
  import { createBrowser } from "anchorbrowser";

  (async () => {
  // Create standalone browser
  const { browser: standaloneBrowser } = await createBrowser();
  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();
  })();
  ```

  ```python python theme={null}
  # 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)
  ```
</CodeGroup>

### Browser Task with Session Control

Use AI agents with direct browser control:

<CodeGroup>
  ```javascript node.js theme={null}
  import { agentBrowserTask } from "anchorbrowser";

  // browserTask starts the agent in the background and immediately returns the
  // live Playwright browser for the same session.
  const browserTask = await agentBrowserTask(
    "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();
  ```

  ```python python theme={null}
  # 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 (a concurrent.futures.Future)
      task_result = browser_task["task_result_task"].result()
      print("Final result:", task_result.data.result)
  ```
</CodeGroup>

### Manual Session Management

Create and manage browser sessions manually:

<CodeGroup>
  ```javascript node.js theme={null}
  import { Sessions, connectBrowser } from "anchorbrowser";

  // Create session and connect it later
  const sessionResponse = await Sessions.createSession();
  const sessionId = sessionResponse.data.id;

  const browser = await connectBrowser(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();
  ```

  ```python python theme={null}
  # Create session and connect it later
  session_response = anchor_client.sessions.create_session()
  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)
  ```
</CodeGroup>

## 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

## Retries

The Node.js client retries status `408`, `409`, `429`, and any `5xx`, plus connection failures and request timeouts, up to 2 more times (`maxRetries` defaults to `2`). The default timeout is 1 hour. It does not send an `Idempotency-Key`. Pass `maxRetries: 0` to turn retries off for a call.

A retried `5xx`, `409`, or timeout on session create can start a second session, because the server may still be provisioning. A `429` from the per-minute session-create limiter is safe to retry.

## Next Steps

* Explore the [API Reference](/api-reference) for detailed documentation
* Learn about [Managed Authentication](/essentials/managed-authentication)
* Check out [Advanced Proxy Configuration](/advanced/proxy) for location-specific browsing


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.