AgentQL Quick Start

This guide shows you how to get started with the basics of AgentQL queries, how to use the Chrome extension for debugging, and how to implement queries using AgentQL's Python SDK.

What's an AgentQL query?

AgentQL is a query language and a set of supporting developer tools designed to identify web elements and their data using natural language and return them in the shape you define.

Here is an AgentQL query you can use right now to locate the search button on this page:

{
    search_button
}

This query can return each heading on this page:

{
    headings[]
}

The following shows you how to execute queries to retrieve data and elements from web pages starting right here, with the page you are on now.

Get your API key

You need an API key to make AgentQL queries. Get a free API key on the AgentQL Developer Portal, and you'll be ready to go!

Query this page with the AgentQL Debugger Chrome extension

The AgentQL Debugger lets you write and test queries in real-time on web pages, without needing to spin up the Python SDK. It's perfect for debugging queries before putting them into production! Here's how to get started:

1. Install the AgentQL Debugger from the Chrome Web Store.

2. Come back to this page and open Chrome DevTools (Ctrl+Shift+I on Windows/Linux or Cmd+Opt+I on Mac).

3. In the top bar of the devtools panel, select "AgentQL."

4. Enter your API key when prompted.

5. In the query panel, try this query:

{
    search_button
}

7. Click "Fetch Web Elements" to run the query to return the search button element.

Look under the AgentQL tab to find an entry for the search button. Hovering over the entry highlights its element on the page.

Try it out!

The best way to learn how AgentQL works is to play around with it in the extension. Here are some things you can try:

• Click the eye icon to navigate to the element on the page.
• Click </> to navigate to the element in the devtools.
• Click "Fetch Data" to return the contents of the queried elements instead of the elements themselves (great for scraping).
• Use [] to return a list of items.
• Use () to add additional context to find the exact element:

{
    headings(all the headings inside the article)[]
}

Experiment with different queries to get a feel for how AgentQL works. For example, try this one out with "Fetch Data" to get a list of all the headings on this page:

{
    headings[]
}

You can even nest items:

{
    breadcrumbs {
        first_item
        last_item
    }
}

Perform the query with the AgentQL Python SDK

Now that you're familiar with writing queries, you can use the Python SDK to run the same query programmatically.

1. In you project folder, install the AgentQL SDK and initialize AgentQL:

pip3 install agentql
agentql init

2. Provide your API key.
3. Create a new Python file, example_script.py.
4. Add the following code:

import agentql
from playwright.sync_api import sync_playwright

# Initialise the browser
with sync_playwright() as playwright, playwright.chromium.launch(headless=False) as browser:
    page = agentql.wrap(browser.new_page())
    page.goto("https://docs.agentql.com/quick-start")

    # Find "Search" button using Smart Locator
    search_button = page.get_by_prompt("search button")
    # Interact with the button
    search_button.click()

    # Define a query for modal dialog's search input
    SEARCH_BOX_QUERY = """
    {
        modal {
            search_box
        }
    }
    """

    # Get the modal's search input and fill it with "Quick Start"
    response = page.query_elements(SEARCH_BOX_QUERY)
    response.modal.search_box.type("Quick Start")

    # Define a query for the search results
    SEARCH_RESULTS_QUERY = """
    {
        modal {
            search_box
            search_results {
                items[]
            }
        }
    }
    """

    # Execute the query after the results have returned then click on the first one
    response = page.query_elements(SEARCH_RESULTS_QUERY)
    response.modal.search_results.items[0].click()

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

5. Run the script:

python3 example_script.py

This script opens this site, docs.agentql.com, clicks the search button, fills in the search modal's input with "Quick Start," and clicks the first result—bringing you back to this page.

Next steps

Congratulations! You've now used AgentQL queries both in the Chrome extension and the Python SDK. This is the AgentQL workflow: optimizing and debugging queries with the extension before running them in Python scripts with the SDK.

Here are some next steps to explore:

• Learn more about AgentQL query syntax
• Explore best practices for writing queries
• Check out an example script for collecting YouTube comment data

Happy querying with AgentQL!