Best Practices for AgentQL Queries

AgentQL queries allow users to retrieve the exact web page elements for interaction or data retrieval. Designed with flexibility in mind, AgentQL queries are schema-less, meaning query terms are free-form and not strongly typed. However, there are some syntax requirements as well as best practices for creating an AgentQL query.

AgentQL query syntax

The list below contains all syntax requirements for AgentQL Query:

• Enclose query with curly braces.
• Put new terms on new lines (i.e. one element per line).
• Do not separate terms with punctuation.
• A container should enclose its children terms with curly braces { ... }.
• Create a list term by adding closed brackets '[]' after the term.
• Provide extra descriptions in parentheses '()' after the term.

Query examples

This is an example of a Single Term Query that tries to retrieve one element (search box) on the web page:

{
    search_box
}

Query with extra contexts

This is an example of providing extra contexts to query. A short description about the query term could be provided in parentheses to help AgentQL better locate the desired web elements:

{
    login_btn(the one in header section)
    footer {
        social_media_links(The icons that lead to Facebook, Snapchat, etc.)[]
    }
}

Nested query

This is an example of a nested query that tries to get a "sign in" button from a page's header and an "about" button from its footer. In this case, <header /> and <footer /> elements serve as container elements that capture the hierarchical relationship of the desired elements.

{
    header {
        sign_in_btn
    }
    footer {
        about_btn
    }
}

Query that returns a list

This is an example of a list term query. This query tries to capture all the links on a web page. The AgentQL server returns an array of links for this query:

{
    links[]
}

Nesting and lists combined

This is another example of a list term query. However, the query is specifying the exact information wanted in every list item. In this case, AgentQL server returns an array. Each array item contains the price, the rating, and reviews of one product.

{
    products[] {
        price
        rating
        reviews[]
    }
}

Recommended practices for creating queries

AgentQL Query is designed to be flexible, but there are some recommended practices that may improve the response quality from AgentQL server:

• Use lowercase letters for all the terms in query.
• Use underscores (_) to separate words within a term (ie user_image).
• Append btn to the term to indicate the element is a clickable (ie search_btn).
• Append box to the name to indicate the element is inputtable (ie search_box).
• Indent children terms in accordance with their parent's indentation.
• Only use query_elements when you wish to interact with web elements. Use query_data to retrieve data.

How to find the exact element on the page

When there are multiple elements with the same or similar names on the web page, the AgentQL server may need further hints from your AgentQL query to find the exact element you are looking for. There are several things you can do with your query to help improve AgentQL's accuracy.

Provide detailed descriptions

Providing descriptions in parentheses is a powerful tool to get better query results. For instance, providing the description of "google sign-in button" to the sign-in term may help with targeting a specific button on a page.

{
    sign_in(google sign-in button)
}

Include hierarchy hints

Hierarchy hints reduce ambiguity. For example, if there are very similar buttons (f.i. “Sign In”) present on the web page, but one of them is positioned in the header and another one is in sign in form, you could try to specify such semantic information.

Consider the following example web page and queries:

Different containers (header and form) will convey different hierarchical information to AgentQL server and locate different sign-in buttons on this page.

{
    header_button
}

Use surrounding terms

Another way to reduce ambiguity is to specify surrounding terms, so its more clear where the element is located. For example, if you are trying to locate “Sign in” button, which is placed between other 2 buttons, it may help to specify those other 2 buttons as well (even if you are not planning to interact with them) to clarify element location.

{
    button_a
    sign_in_btn
    button_b
}

Examples

Here shows some examples of working with real web pages.

Retrieving Phone Model Button

In this example, the Agent query retrieves two buttons for different models by specifying their containing element.

{
    model_selector {
        iphone_15_pro_max_btn
        iphone_15_pro_btn
    }
}

Alternatively, you could query the model selector itself. The button information will be preserved in the response, so you could retrieve the buttons through parsing.

{
    model_selector
}

Retriving Amazon Product Information

This AgentQL query gets the name and price of each product on the Amazon product listing page.

{
    results {
        products[] {
            product_name
            prouct_price
        }
    }
}

If you want all the relevant information of each product, you could generalize the query above.

{
    results {
        products[]
    }
}