AgentQL Page

AgentQL Page is a wrapper around Playwright's Page that provides access to AgentQL's querying API.

The following example creates a Playwright's page, navigates it to a URL, and queries for WebElements using AgentQL:

const { chromium } = require('playwright');
const { wrap, configure } = require('agentql');

const QUERY = `
{
    search_box
    search_btn
}
`;

(async () => {
  // Configure the API key
  configure({ apiKey: process.env.AGENTQL_API_KEY });

  const browser = await chromium.launch({ headless: false });
  const page = await wrap(await browser.newPage()); // Wrapped to access AgentQL's query API's
  await page.goto('https://duckduckgo.com'); 

  const response = await page.queryElements(QUERY); 
  await response.search_box.type('AgentQL');
  await response.search_btn.click();

  // Used only for demo purposes. It allows you to see the effect of the script.
  await page.waitForTimeout(10000);

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

Methods

getByPrompt

Returns a single web element located by a natural language prompt (as opposed to an AgentQL query).

Usage

const searchBox = await page.getByPrompt('Search input field');

Arguments

• prompt string

  The natural language description of the element to locate.

• timeout number (optional)

  Timeout value in milliseconds for the connection with backend API service. Defaults to 60 seconds.

• waitForNetworkIdle boolean (optional)

  Whether to wait for network reaching full idle state before querying the page. If set to False, this method will only check for whether page has emitted load event. Default is True.

• includeHidden boolean (optional)

  Whether to include hidden elements on the page. Defaults to false.

• mode ResponseMode (optional)

  The mode of the query. It can be either 'standard' or 'fast'. Defaults to fast mode.

Returns

• Promise<Locator | null>

  Playwright Locator for the found element or null if no matching elements were found.

queryElements

Queries the web page for multiple web elements that match the AgentQL query.

Usage

const agentqlResponse = await page.queryElements(`
  {
    search_box
    search_btn
  }
`);
console.log(agentqlResponse.toData());

Arguments

• query string

  An AgentQL query in String format.

• timeout number (optional)

  Timeout value in milliseconds for the connection with the backend API service. Defaults to 60 seconds.

• waitForNetworkIdle boolean (optional)

  Whether to wait for network reaching full idle state before querying the page. If set to False, this method will only check for whether page has emitted load event. Default is True.

• includeHidden boolean (optional)

  Whether to include hidden elements on the page. Defaults to false.

• mode ResponseMode (optional)

  The mode of the query. It can be either 'standard' or 'fast'. Defaults to fast mode.

Returns

• Promise<AQLResponseProxy>

  The AgentQL response object with elements that match the query. Response provides access to requested elements via its fields.

queryData

Queries the web page for data that matches the AgentQL query, such as blocks of text or numbers.

Usage

const retrievedData = await page.queryData(`
  {
    products[] {
      name
      price
    }
  }
`);
console.log(retrievedData);

Arguments

• query string

  An AgentQL query in String format.

• timeout number (optional)

  Timeout value in milliseconds for the connection with backend API service. Defaults to 900 seconds.

• waitForNetworkIdle boolean (optional)

  Whether to wait for network reaching full idle state before querying the page. If set to False, this method will only check for whether page has emitted load event. Default is True.

• includeHidden boolean (optional)

  Whether to include hidden elements on the page. Defaults to true.

• mode ResponseMode (optional)

  The mode of the query. It can be either 'standard' or 'fast'. Defaults to fast mode.

Returns

• Promise<Record<string, any>>

  Data that matches the query.

waitForPageReadyState

Waits for the page to reach the "Page Ready" state, that is page has entered a relatively stable state and most main content is loaded. Might be useful before triggering an AgentQL query or any other interaction for slowly rendering pages.

Usage

await page.waitForPageReadyState();

Arguments

• waitForNetworkIdle boolean (optional)

  Whether to wait for network reaching full idle state. Defaults to true.

Returns

• Promise<void>

Types

ResponseMode

The ResponseMode type specifies the mode of querying for queryElements(), queryData(), and getByPrompt() methods. It expects the following two values:

• standard

  Executes the query in Standard Mode. Use this mode when your queries are complex or extensive data retrieval is necessary.

• fast

  Executes the query more quickly, potentially at the cost of response accuracy. This mode is useful in situations where speed is prioritized, and the query is straightforward.