AgentQLPage is a wrapper around Playwright'sPage 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:

import agentqlfrom playwright.sync_apiimport sync_playwrightQUERY= """{    search_box    search_btn}"""with sync_playwright() as p, p.chromium.launch(headless=False) as browser:    page= agentql.wrap(browser.new_page()) # Wrapped to access AgentQL's query API's    page.goto("https://duckduckgo.com")    aql_response= page.query_elements(QUERY)    aql_response.search_box.type("AgentQL")    aql_response.search_btn.click()    # Used only for demo purposes. It allows you to see the effect of the script.    page.wait_for_timeout(10000)

Methods

get_by_prompt

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

Usage

search_box= page.get_by_prompt(prompt="Search input field")

Arguments

• promptstr

  The natural language description of the element to locate.

• timeoutint (optional)

  Timeout value in seconds for the connection with backend API service.

• wait_for_network_idlebool (optional)

  Whether to wait for network reaching full idle state before querying the page. If set toFalse, this method will only check for whether page has emittedload event. Default isTrue.

• include_hiddenbool (optional)

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

• modeResponseMode (optional): The mode of the query. It can be eitherstandard orfast. Defaults tofast mode.

• experimental_query_elements_enabledbool (optional)

  Whether to use the experimental implementation of the query elements feature. Defaults toFalse.

Returns

• Locator |None

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

query_elements

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

Usage

agentql_response= page.query_elements(        query="""            {                search_box                search_btn            }            """    )    print(agentql_response.to_data())

Arguments

• querystr

  AnAgentQL query in String format.

• timeoutint (optional)

  Timeout value in seconds for the connection with the backend API service.

• wait_for_network_idlebool (optional)

  Whether to wait for network reaching full idle state before querying the page. If set toFalse, this method will only check for whether page has emittedload event. Default isTrue.

• include_hiddenbool (optional)

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

• modeResponseMode (optional): The mode of the query. It can be eitherstandard orfast. Defaults tofast mode.

• experimental_query_elements_enabledbool (optional)

  Whether to use the experimental implementation of the query elements feature. Defaults toFalse.

Returns

• AQLResponseProxy

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

query_data

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

Usage

retrieved_data= page.query_data(        query="""            {                products[] {                  name                  price(integer)                }            }            """    )    print(retrieved_data)

Arguments

• querystr

  AnAgentQL query in String format.

• timeoutint (optional)

  Timeout value in seconds for the connection with backend API service.

• wait_for_network_idlebool (optional)

  Whether to wait for network reaching full idle state before querying the page. If set toFalse, this method will only check for whether page has emittedload event. Default isTrue.

• include_hiddenbool (optional)

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

• modeResponseMode (optional): The mode of the query. It can be eitherstandard orfast. Defaults tofast mode.

Returns

• dict

  Data that matches the query.

wait_for_page_ready_state

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

page.wait_for_page_ready_state()

Arguments

• wait_for_network_idlebool (optional)

  Whether to wait for network reaching full idle state. If set toFalse, this method will only check for whether page has emittedload event. Default isTrue.

Returns

• NoneType

enable_stealth_mode

Enables "stealth mode" with given configuration. To avoid being marked as a bot, parameters' values should match the real values used by your device.

Usage

page.enable_stealth_mode(        webgl_vendor=your_browser_vendor,        webgl_renderer=your_browser_renderer,        nav_user_agent=navigator_user_agent,    )

Arguments

• webgl_vendorstr (optional)

  The vendor of the GPU used by WebGL to render graphics, such asApple Inc.. After setting this parameter, your browser will emit this vendor information.

• webgl_rendererstr (optional)

  Identifies the specific GPU model or graphics rendering engine used by WebGL, such asApple M3. After setting this parameter, your browser will emit this renderer information.

• nav_user_agentstr (optional)

  Identifies the browser, its version, and the operating system, such asMozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36. After setting this parameter, your browser will send this user agent information to the website.

Returns

• NoneType

get_pagination_info

Returns pagination information and status of the current page.

Usage

pagination_info= page.get_pagination_info()

Arguments

• timeoutint (optional):

  Timeout value in seconds for the connection with backend API service for querying the pagination information.

• wait_for_network_idlebool (optional)

  Whether to wait for network reaching full idle state before querying the page for pagination information. If set toFalse, this method will only check for whether page has emittedload event. Default isTrue.

• include_hiddenbool (optional)

  Whether to include hidden elements on the page when querying for pagination information. Defaults toFalse.

• modeResponseMode (optional):

  The mode of the query for retrieving the pagination information. It can be eitherstandard orfast. Defaults tofast mode.

Returns

• PaginationInfo

  The PaginationInfo object provide access to the pagination availability and functionality to navigate to the next page.

get_last_query

Returns the last query executed by the AgentQL SDK on this page.

Usage

last_query= page.get_last_query()

Returns

• str

  The last query executed by the AgentQL SDK on this page.

get_last_response

Returns the last response generated by the AgentQL SDK on this page.

Usage

last_response= page.get_last_response()

Returns

• dict

  The last response generated by the AgentQL SDK on this page.

get_last_accessibility_tree

Returns the last accessibility tree generated by the AgentQL SDK on this page.

Usage

last_accessibility_tree= page.get_last_accessibility_tree()

Returns

• dict

  The last accessibility tree generated by the AgentQL SDK on this page.

Types

ResponseMode

TheResponseMode type specifies the mode of querying forquery_elements(),query_data(), andget_by_prompt() methods. It's expecting 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.