AgentQL Quick Start

This guide shows you how to get started interacting with elements and extracting data from web pages using AgentQL queries. You will learn 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."

note

If you don't see the option, click the overflow menu button (») and select "AgentQL" from the list.

  1. Enter your API key when prompted.

  2. In the query panel, try this query:

{
    search_button
}
  1. 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 SDK

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

  1. In your project folder, install the AgentQL SDK and CLI:
terminal
npm install agentql
npm install -g agentql-cli
  1. Install dependencies by running the following command:
terminal
agentql init
  1. Set the AGENTQL_API_KEY environment variable with your API key.

To set the environment variable temporarily for your terminal session, in your terminal run

terminal
export AGENTQL_API_KEY=your-api-key
  1. Create a new JavaScript file, example_script.js.
  2. Add the following code:
example_script.js
js
const { wrap, configure } = require('agentql');
const { chromium } = require('playwright');

configure({ apiKey: process.env.AGENTQL_API_KEY });

async function main() {
    const browser = await chromium.launch({headless: false});
    const page = await wrap(await browser.newPage());
    await page.goto('https://docs.agentql.com/quick-start');

    // Find "Search" button using Smart Locator
    const searchButton = await page.getByPrompt('search button');
    // Interact with the button
    await searchButton.click();

    // Define a query for modal dialog's search input
    const SEARCH_BOX_QUERY = `
    {
        modal {
            search_box
        }
    }
    `

    // Get the modal's search input and fill it with "Quick Start"
    let response = await page.queryElements(SEARCH_BOX_QUERY);
    await response.modal.search_box.fill("Quick Start");

    // Define a query for the search results
    const SEARCH_RESULTS_QUERY = `
    {
        modal {
            search_box
            search_results {
                items[]
            }
        }
    }
    `

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


    // Used only for demo purposes. It allows you to see the effect of the script.
    await page.waitForTimeout(10000);

    await browser.close();
}

main();
  1. Run the script:
terminal
node example_script.js

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 SDK. This is the AgentQL workflow: optimizing and debugging queries with the extension before running them in the SDK.

Here are some next steps to explore:

Happy querying with AgentQL!