AgentQL Tools

The agentql/tools module provides utility methods to help with data extraction and web automation.

• Use remote browser Create a remote browser session for browser automation.

Use remote browser

The following example demonstrates how to use the createBrowserSession method to create a remote browser session:

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

async function main() {
  const session = await createBrowserSession({ uaPreset: UserAgentPreset.WINDOWS }); 

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

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

  // Get streaming URL to view the page
  console.log(`View at: ${session.getPageStreamingUrl(0)}`);

  await browser.close();
}

main().catch(console.error);

Methods

createBrowserSession

Creates a new remote browser session that provides a Chrome DevTools Protocol (CDP) URL for connecting to a remote browser instance and streaming URLs for real-time page viewing.

Usage

const session = await createBrowserSession({ uaPreset: UserAgentPreset.MACOS });

Arguments

• options BrowserSessionOptions (optional)

  Configuration options for the browser session.

  Properties:

  • uaPreset UserAgentPreset (optional): User agent preset to simulate different operating systems
  • profile BrowserProfile (optional): Browser profile for anti-detection configuration
  • inactivityTimeoutSeconds number (optional): Inactivity timeout in seconds

Returns

• Promise<BrowserSession>

  Object containing CDP URL and methods for streaming page access.

Throws

• APIKeyError: If API key isn't set or invalid
• Error: If session creation fails

Types

BrowserSessionOptions

Configuration options for creating a browser session.

Properties

• uaPreset UserAgentPreset (optional)

  User agent preset to simulate different operating systems.

• profile BrowserProfile (optional)

  Browser profile preset for anti-detection configuration.

• inactivityTimeoutSeconds number (optional)

  Inactivity timeout in seconds for the remote browser session.

BrowserSession

Represents an allocated remote browser session with CDP access and streaming capabilities.

Properties

• cdpUrl string

  Chrome DevTools Protocol URL for connecting to the remote browser.

Methods

• getPageStreamingUrl(pageNum) → string

  Returns a streaming URL for viewing a specific page in real-time.

  Arguments:

  • pageNum number: Page number (0-indexed)

UserAgentPreset

Enum for user agent presets to simulate different operating systems:

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

BrowserProfile

Enum for browser profile presets:

• BrowserProfile.LIGHT: Basic browser profile with standard configurations
• BrowserProfile.STEALTH: Enhanced profile with advanced stealth measures for bot detection avoidance