AgentQL Page | AgentQL

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:

agentql_example.js

javascript

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

agentql_example.js

javascript

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

Arguments

prompt string

The natural language description of the element to locate.
options object (optional)

Optional parameters for the query.
- 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

agentql_example.js

javascript

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

Arguments

query string

An AgentQL query in String format.
options object (optional)

Optional parameters for the query.
- 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

agentql_example.js

javascript

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

Arguments

query string

An AgentQL query in String format.
options object (optional)

Optional parameters for the query.
- 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

agentql_example.js

javascript

await page.waitForPageReadyState();

Arguments

options object (optional)

Optional parameters for the query.
- 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.