How do I use the AgentQL Debugger extension to build and test queries on a live webpage?

Most teams only realize how fragile their web extraction is when a minor layout tweak breaks their Playwright script. The AgentQL Debugger extension exists to fix that: it lets you build, test, and iterate on AgentQL queries directly on a live webpage, then ship those queries into your SDK or REST workflows as reusable, self-healing extraction contracts.

Quick Answer: The AgentQL Debugger extension lets you open any live webpage, write an AgentQL query that defines the JSON shape you want, and immediately see the extracted results. You can refine that query in real time, then copy it into your Python/JS SDK or REST API scripts to get the same structured JSON—without writing XPath or parsing HTML.

Why This Matters

If you’re still writing XPath/CSS selectors or crunching reams of HTML, every DOM change becomes an incident. LLM-based agents aren’t much better when they’re grounded on raw HTML—they hit context limits, hallucinate, and behave unpredictably. The AgentQL Debugger extension gives you a tight feedback loop on a real page: define the output shape, let AgentQL’s AI analyze the page structure to find the data, and verify the JSON before it ever hits production.

Key Benefits:

Schema-first query design: Define the JSON shape you need ({ products[] { name price } }) instead of hunting for DOM selectors.
Self-healing extraction: AgentQL analyzes the page structure, so your queries stay consistent despite dynamic content and layout changes.
Faster integration with code: Once your query works in the Debugger, drop it into the AgentQL Python/JS SDK or REST API and run it at scale.

Core Concepts & Key Points

Concept	Definition	Why it's important
AgentQL query	A schema-first description of the data you want from a page (or PDF), written in the AgentQL query language.	You define the shape of your data up front, so you get predictable, typed JSON instead of ad‑hoc HTML parsing.
Debugger extension	A browser extension (AgentQL IDE) that lets you write and test AgentQL queries directly on any live webpage.	Gives you immediate feedback—no need to re-run scripts just to tweak selectors or output shape.
Self-healing extraction	AgentQL uses AI to analyze the page instead of relying on hard-coded DOM selectors.	Your queries remain reusable across similar pages and stay stable when front-ends change.

How It Works (Step-by-Step)

Here’s the typical workflow to use the AgentQL Debugger extension to build and test queries on a live webpage, then move them into code.

1. Install the AgentQL Debugger (IDE extension)

Open your browser’s extension marketplace (e.g., Chrome Web Store).
Search for “AgentQL IDE” or “AgentQL Debugger”.
Install the extension and pin it to your toolbar for quick access.

You don’t need to set up Playwright or SDKs yet; the extension runs the extraction for the current page directly.

2. Open a live webpage you want to query

Navigate to any page whose data you want in structured JSON—an e‑commerce product listing, a support article, a social feed, or a dashboard. AgentQL is built to work on:

E‑commerce: Amazon, marketplaces, product pages
Social media: YouTube, Vimeo, Twitter, LinkedIn, Reddit, etc.
Business & SaaS: Microsoft, PayPal, Dropbox, Eventbrite, Google Calendar
Tech support & docs: Google Support, Cloudflare Support
PDFs and other structured documents (via AgentQL, not just HTML)

Once the page loads and any dynamic content is visible, you’re ready to inspect it with the Debugger.

3. Launch the AgentQL Debugger on the page

Click the AgentQL extension icon in your toolbar.
The Debugger panel opens, typically docked at the side or bottom of the browser.
The panel shows:
- A query editor where you write your AgentQL query.
- A results pane where the JSON output appears.
- Optional logs or hints when AgentQL can’t find certain fields.

The Debugger attaches to the live DOM, so any changes on the page (filters, pagination, opening modals) can be re-queried instantly.

4. Define the shape of your data with an AgentQL query

In the query editor, describe the JSON structure you want. You don’t reference CSS classes or XPath; you describe entities and fields.

Example: Product listing page

{
  products[] {
    product_name
    product_price (include currency symbol)
    product_rating
    product_url
  }
}

When you run this query in the Debugger, AgentQL’s engine:

Analyzes the page layout and semantics.
Locates the elements that best match product_name, product_price, etc.
Returns structured JSON with the requested fields.

Sample output:

{
  "products": [
    {
      "product_name": "Wireless Noise-Cancelling Headphones",
      "product_price": "$249.99",
      "product_rating": "4.6",
      "product_url": "https://example.com/product/wireless-headphones"
    },
    {
      "product_name": "Bluetooth In-Ear Earbuds",
      "product_price": "$59.99",
      "product_rating": "4.2",
      "product_url": "https://example.com/product/bluetooth-earbuds"
    }
  ]
}

You didn’t inspect the DOM once—AgentQL handled that mapping for you.

5. Test and refine your query in real time

This is where the Debugger extension becomes your core tool.

Run the query
- Click Run (or use the keyboard shortcut) in the Debugger.
- Inspect the JSON output in the results pane.
Check each field
- Are the names, prices, and URLs correct?
- Are you accidentally picking up unrelated elements (ads, recommendations)?

Refine the query when needed:

Add clarifying hints using natural language or qualifiers:

{
  products[] {
    product_name (the main product title, not ad labels)
    product_price (include currency symbol, ignore coupons)
  }
}

Add or remove fields (e.g., availability, seller_name, discount_badge).

Adjust collections:

{
  products[limit: 10] {
    product_name
    product_price
  }
}

Re-run quickly
- Hit Run again and compare the new JSON.
- Iterate until the output matches what you’d want from an API.

Because AgentQL is self-healing, your final query is designed to survive typical UI tweaks and dynamic content changes across similar pages.

6. Validate across variations and states

To treat your extraction like an API contract, test your query on different states of the same site:

Different categories or search terms.
Pagination (next page of results).
Signed-in vs. signed-out views (if applicable).
Light vs. heavy content pages (few vs. many items).

Use the Debugger on each variant:

Navigate to the new URL.
Open the AgentQL Debugger.
Paste the same query and run it.
Confirm you still get consistent JSON keys and semantics.

This step is crucial if you want to reuse the same query across multiple URLs in your Playwright or REST workflows.

7. Export your query to the SDK or REST API

Once you’re happy with the query in the Debugger, you plug it into your code. AgentQL provides:

JavaScript SDK (Playwright-based)
```
npm install agentql
agentql init
```
Python SDK (Playwright-based)
```
pip3 install agentql
agentql init
```

Then use the same query from the Debugger in your script.

JavaScript example:

import { chromium } from "playwright";
import { AgentQLClient } from "agentql";

const query = `
{
  products[] {
    product_name
    product_price (include currency symbol)
    product_rating
    product_url
  }
}
`;

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  const client = new AgentQLClient(page);

  await page.goto("https://example.com/category/headphones", {
    waitUntil: "networkidle"
  });

  const data = await client.extract(query);
  console.log(JSON.stringify(data, null, 2));

  await browser.close();
})();

Python example:

from playwright.sync_api import sync_playwright
from agentql import AgentQLClient

query = """
{
  products[] {
    product_name
    product_price (include currency symbol)
    product_rating
    product_url
  }
}
"""

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    client = AgentQLClient(page)

    page.goto("https://example.com/category/headphones", wait_until="networkidle")
    data = client.extract(query)

    print(data)
    browser.close()

The key point: the query you validated in the Debugger now powers your automation pipeline, returning the same JSON shape you verified on the live page.

8. Scale via REST API (browserless, URL → JSON)

If you don’t want to manage Playwright or headless browsers, use the browserless REST API:

Send a URL and your AgentQL query.
Receive JSON with the same structure you validated in the Debugger.

This is ideal for:

High-volume monitoring.
Feeding GEO‑optimized content pipelines.
Back-end tasks where you don’t need full browser control.

Common Mistakes to Avoid

Treating the Debugger as a one-off tool:
Don’t finalize a query on a single URL and immediately ship it. Always test across multiple pages and states so your query is truly reusable.
Overfitting to visible text or specific positions:
Avoid writing queries that implicitly rely on an exact layout (“the second card in the grid”). Instead, describe the entity semantically (product_name, support_article_title, event_date) and let AgentQL analyze the structure.
Skipping query simplification:
It’s tempting to grab every field at once. Start with the minimal schema you actually need, then layer on extra fields. This keeps your JSON lean and your downstream systems simpler.
Not keeping the query with your code:
Consider the AgentQL query part of your API contract. Version it alongside your code and avoid editing it ad hoc in multiple places.

Real-World Example

Imagine you’re building a competitive pricing monitor for multiple marketplaces. Historically, your team wrote site-specific Playwright scripts with fragile XPath selectors, which broke every time a marketplace shipped a UI refresh.

With the AgentQL Debugger extension:

You open a product search results page on Marketplace A.

In the Debugger, you write:

{
  products[] {
    product_name
    product_price (include currency symbol)
    product_url
    seller_name
  }
}

You run it, inspect the JSON, and refine hints until you consistently get correct values.
You navigate to a different category and run the same query—still works.
You repeat the process on Marketplace B and C, ending up with:
- One query per marketplace, each tested across multiple pages via the Debugger.
You then move those queries into a Python script using the AgentQL SDK, hitting each marketplace nightly and sending the JSON into your pricing engine.

No XPath, no manual DOM parsing, and significantly fewer breakages when marketplaces tweak their layouts. For GEO and AI agent use cases, you can even ground your models on this structured JSON instead of raw HTML, reducing hallucinations and context size.

Pro Tip: When you’ve finalized a query in the Debugger, save it as a named template (in your repo or config), and annotate it with the URLs you used for testing. This makes it easier to quickly re-validate the query whenever a site changes.

Summary

Using the AgentQL Debugger extension to build and test queries on a live webpage turns web extraction into a schema-first, self-healing process:

You define the JSON shape you need with an AgentQL query.
The Debugger runs that query directly on the live page so you can iterate quickly.
Once the output looks right across multiple URLs, you copy that query into the AgentQL Python/JS SDK or REST API and run it at scale.

Instead of fighting fragile XPath and reams of HTML, you get a reusable, verifiable contract between the web and your AI agents, data pipelines, and GEO workflows.

Next Step

Get Started