How to use remote browser with AgentQL

AgentQL provides powerful capabilities for allocating a remote browser to simplify browser automation. This allows you to run browser automation scripts on remote infrastructure while using the familiar AgentQL API.

Overview

Remote browsers in AgentQL are managed through browser sessions that provide:

  • CDP (Chrome DevTools Protocol) access for full browser control
  • Streaming URLs for real-time page viewing
  • User Agent presets for different operating systems
  • Automatic session management and cleanup

Quick start

remote_browser_example.js
js
import { wrap } from 'agentql';
import { createBrowserSession, UserAgentPreset } from 'agentql/tools';
import { chromium } from 'playwright';

async function main() {
  // Create a remote browser session
  const session = await createBrowserSession(UserAgentPreset.WINDOWS);

  // Connect to the remote browser
  const browser = await chromium.connectOverCDP(session.cdpUrl);
  const page = await browser.newPage();
  const wrappedPage = await wrap(page);

  // Use AgentQL as normal
  await wrappedPage.goto('https://example.com');

  // Query elements
  const response = await wrappedPage.queryElements(`
    {
      title
      main_content
    }
  `);

  console.log('Title:', await response.title.textContent());
}

main().catch(console.error);

Browser session management

Creating sessions

Use createBrowserSession() to create new remote browser sessions:

create_session.js
js
import { createBrowserSession, UserAgentPreset } from 'agentql/tools';

// Basic session
const session = await createBrowserSession();

// With user agent preset
const session = await createBrowserSession(UserAgentPreset.LINUX);

Session properties

The BrowserSession object provides:

  • cdp_url: Chrome DevTools Protocol URL for browser connection
  • get_page_streaming_url(page_num): Get streaming URL for viewing a specific page
session_properties.js
js
const session = await createBrowserSession();

console.log('CDP URL:', session.cdpUrl);
console.log('Streaming URL:', session.getPageStreamingUrl(0));

User agent presets

AgentQL supports different user agent presets to simulate various operating systems:

  • WINDOWS: Windows user agent and browser characteristics
  • MACOS: macOS user agent and browser characteristics
  • LINUX: Linux user agent and browser characteristics

Usage

user_agent_presets.js
js
import { createBrowserSession, UserAgentPreset } from 'agentql/tools';

// Create sessions with different presets
const windowsSession = await createBrowserSession(UserAgentPreset.WINDOWS);
const macosSession = await createBrowserSession(UserAgentPreset.MACOS);
const linuxSession = await createBrowserSession(UserAgentPreset.LINUX);

Page streaming

Remote browsers support real-time page streaming, allowing you to view what's happening in the browser:

session = await create_browser_session()

# Get streaming URL for the first page (index 0)
streaming_url = session.get_page_streaming_url(0)
print(f"View your browser at: {streaming_url}")

This is particularly useful for:

  • Debugging automation scripts
  • Monitoring long-running processes
  • Demonstrating browser automation to stakeholders

Best practices

Error handling

Always handle potential errors when creating browser sessions:

error_handling.js
js
import { APIKeyError } from 'agentql';
import { createBrowserSession } from 'agentql/tools';

try {
  const session = await createBrowserSession();
} catch (error) {
  if (error instanceof APIKeyError) {
    console.log('Please set your AgentQL API key');
  } else {
    console.log('Failed to create browser session:', error.message);
  }
}

Resource management

Ensure proper cleanup of browser resources:

automated_task.js
js
import { wrap } from 'agentql';
import { createBrowserSession } from 'agentql/tools';
import { chromium } from 'playwright';

async function automatedTask() {
  const session = await createBrowserSession();

  const browser = await chromium.connectOverCDP(session.cdpUrl);
  try {
    const page = await browser.newPage();
    const wrappedPage = await wrap(page);

    // Your automation logic here
    await wrappedPage.goto('https://example.com');

  } finally {
    await browser.close();
  }
}

Session reuse

Browser sessions can be reused for multiple pages within the same browser instance:

session = await create_browser_session()

async with async_playwright() as p:
    browser = await p.chromium.connect_over_cdp(session.cdp_url)

    # Create multiple pages in the same session
    page1 = await browser.new_page()
    page2 = await browser.new_page()

    wrapped_page1 = await agentql.wrap_async(page1)
    wrapped_page2 = await agentql.wrap_async(page2)

    # Use both pages
    await wrapped_page1.goto("https://site1.com")
    await wrapped_page2.goto("https://site2.com")

Complete example

Here's a complete example that demonstrates remote browser usage with error handling and cleanup:

complete_example.js
js
import { wrap } from 'agentql';
import { createBrowserSession, UserAgentPreset } from 'agentql/tools';
import { chromium } from 'playwright';

async function searchExample() {
  try {
    // Create remote browser session
    const session = await createBrowserSession(UserAgentPreset.WINDOWS);
    console.log(`Browser session created: ${session.cdpUrl}`);
    console.log(`Watch at: ${session.getPageStreamingUrl(0)}`);

    // Connect to remote browser
    const browser = await chromium.connectOverCDP(session.cdpUrl);

    try {
      const page = await browser.newPage();
      const wrappedPage = await wrap(page);

      // Navigate to search page
      await wrappedPage.goto('https://scrapeme.live/shop');

      // Query for search elements
      const searchResponse = await wrappedPage.queryElements(`
        {
          search_products_box
        }
      `);

      // Perform search
      await searchResponse.search_products_box.type('Charmander');
      await wrappedPage.keyboard.press('Enter');

      // Wait and get results
      await wrappedPage.waitForTimeout(2000);

      const results = await wrappedPage.queryData(`
        {
          number_in_stock
        }
      `);

      console.log('Search results:', results);

    } finally {
      await browser.close();
    }

  } catch (error) {
    console.error('Error:', error);
  }
}

searchExample().catch(console.error);

Getting help

If you encounter issues:

  1. Check the AgentQL documentation
  2. Join our Discord community
  3. Report bugs on GitHub

Related content