AQLResponseProxy

The AQLResponseProxy class is returned by AgentQL Page's query_elements() method. Not the actual data, AQLResponseProxy is a metadata that allows for intuitive access to web elements using dot notation. But this class can be converted into raw data as structured dictionary through its to_data() method.

To access desired web elements, users can directly use the names defined in queries as attributes of the response object. It returns desired elements as Playwright Locator objects, and users can interact with these elements, such as click or type, through Playwright Locator API.

The following example queries for web elements through query_elements() method, interacts with these elements through AQLResponseProxy objects, and converts AQLResponseProxy objects into raw data.

agentql_example.py
python
import agentql
from playwright.sync_api import sync_playwright

QUERY = """
{
    search_box
    header {
        search_btn
    }
}
"""

with sync_playwright() as playwright, playwright.chromium.launch(headless=False) as browser:
    page = agentql.wrap(browser.new_page())
    page.goto("https://duckduckgo.com")

    # Get AQLResponseProxy, which contains desired web elements
    aql_response = page.query_elements(QUERY)

    # Access the elements with dot notation and interact with them as Playwright Locator objects
    aql_response.search_box.type("AgentQL")

    # To access a nested elements in query, simply chain attributes together with dot notation
    aql_response.header.search_btn.click()

    # Convert response into raw data as structured dictionary with to_data() method
    raw_data_in_dict = aql_response.to_data()
    print(raw_data_in_dict)

    # Used only for demo purposes. It allows you to see the effect of the script.
    page.wait_for_timeout(10000)

Methods

to_data

Converts the response data into a structured dictionary based on the query tree.

Usage

agentql_example.py
python
aql_response = page.query_elements(QUERY)
aql_response.to_data()

Returns

A structured Python dictionary in the following format.

agentql_example.py
python
{
  "query_field": "text content of the corresponding web element"
}

__getattr__

If this method is called on an innermost node of the query, it returns the desired web element as a Playwright Locator object. Please check the Playwright API reference to see available methods in Locator class.

If called on a container node of the query, it returns another AQLResponseProxy object, which can be further interacted to get Playwright Locator object.

Usage

agentql_example.py
python
QUERY = """
{
    search_btn
    search_results[]
}
"""

aql_response = page.query_elements(QUERY)

# This invokes Playwright Locator object's click() method
aql_response.search_btn.click()

# This iterate through search result with AQLResponseProxy
for search_result in aql_response.search_results:
    print(search_result)

Arguments

The name of the attribute to retrieve.

Returns

__getitem__

Allows indexing into the response data if it's a list.

Usage

agentql_example.py
python
QUERY = """
{
    search_results[]
}
"""

aql_response = page.query_elements(QUERY)

# Get the second result in the list
second_result = aql_response.search_results[1]

Arguments

The index of the item in the list to retrieve.

Returns

The corresponding AQLResponseProxy list item.

__len__

Returns the number of items in the response data if it's a list.

Usage

agentql_example.py
python
QUERY = """
{
    search_results[]
}
"""

aql_response = page.query_elements(QUERY)

# Get the number of search results
result_count = len(aql_response.search_results)

Returns

Number of items in the list.

__str__

Returns a string representation of the response data in JSON format.

Usage

agentql_example.py
python
QUERY = """
{
    search_results[]
}
"""

aql_response = page.query_elements(QUERY)

# Convert results to a JSON string for display
result_in_json_string = print(aql_response.search_results)

Returns