Usage

AgentQL wraps a Playwright page with wrap(). After wrapping, the page gains two new methods:

• queryElements(QUERY) - finds interactive elements (buttons, inputs, links) for clicking or filling
• queryData(QUERY) - extracts structured data from the page into a Python/JS object

The query syntax uses curly braces with plain-language field names. AgentQL resolves them semantically.

JavaScript example

This script navigates to a demo shop, locates the search box by natural language query, fills it, and submits.

// example_script.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();
    const page = await wrap(await browser.newPage());
    await page.goto('https://scrapeme.live/shop');

    const QUERY = `
    {
        search_box
    }
    `;

    const response = await page.queryElements(QUERY);

    await response.search_box.fill('fish');
    await page.keyboard.press('Enter');

    // Pause to observe the result before closing
    await page.waitForTimeout(10000);

    await browser.close();
}

main();

Python example

# example_script.py
import asyncio
import agentql
from playwright.async_api import async_playwright

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = agentql.wrap(await browser.new_page())
        await page.goto('https://scrapeme.live/shop')

        QUERY = """
        {
            search_box
        }
        """

        response = await page.query_elements(QUERY)

        await response.search_box.fill('fish')
        await page.keyboard.press('Enter')

        await page.wait_for_timeout(10000)
        await browser.close()

asyncio.run(main())

Data extraction example

Use queryData (JS) or query_data (Python) to pull structured content from the page:

const QUERY = `
{
    products[] {
        name
        price
    }
}
`;

const data = await page.queryData(QUERY);
console.log(data.products);
// => [{ name: 'Clownfish', price: '$12.50' }, ...]

Query language notes

• Field names are plain English. AgentQL resolves them using AI-powered semantic matching.
• Arrays use [] notation: products[] collects all matching items.
• Nesting is supported: { product { name price image } }.
• The query language works identically in Python and JavaScript.

25+ real examples

The official GitHub repository includes a full examples folder with scripts for e-commerce scraping, login flows, Google Maps, YouTube comments, and more:
https://github.com/tinyfish-io/agentql/tree/main/examples