AgentQL Playground: how do I prototype a query and export it to code?

Quick Answer: Use AgentQL Playground to interactively design and test your query on a live page, then export ready‑to‑run code snippets for the JavaScript/Python SDKs or the REST API. You define the JSON shape, refine it with fast feedback in the UI, and copy the generated code straight into your web automation or LLM grounding pipeline.

Why This Matters

If you’re still wiring Playwright or Selenium to fragile CSS/XPath selectors, every layout tweak turns into a fire drill. AgentQL Playground flips that workflow: you define the output schema once (query → JSON), let AgentQL’s AI analyze the page structure, and only ship code after you’ve seen real responses. This cuts trial‑and‑error in code, reduces hallucinations from raw HTML grounding, and gives you a reusable, self‑healing query that survives typical page changes.

Key Benefits:

• Faster prototyping: Build and validate queries visually before touching your scraper or agent code.
• Schema‑first reliability: Define the JSON contract up front and keep your Playwright flows selector‑free.
• Copy‑paste integration: Export language‑specific snippets (JS, Python, REST) so Playground experiments become production code in minutes.

Core Concepts & Key Points

Concept	Definition	Why it's important
Schema‑first query	An AgentQL query that specifies the exact JSON shape you want (fields, nested arrays, tables, etc.).	Turns web pages into stable “APIs” where you own the output contract instead of chasing DOM changes.
Playground	A browser UI where you attach AgentQL to any page, write a query, and see structured JSON results in real time.	Gives you a tight feedback loop for designing and debugging queries before exporting them to code.
Code export	Auto‑generated JavaScript, Python, or REST examples that embed your validated query.	Ensures the code you ship matches exactly what you tested, avoiding copy‑paste drift and subtle bugs.

How It Works (Step‑by‑Step)

At a high level, you’ll: open the Playground on a target page, draft a query that expresses your JSON shape, refine it until the response is correct, then export the snippet into your codebase.

1. Open the target page in Playground

You typically start from one of two surfaces:

• AgentQL IDE browser extension (Playground‑like experience):

  • Navigate to any URL (e.g., a product listing, Google Play Store app page, a Google Maps location, etc.).
  • Open the AgentQL panel (extension icon in your browser).
  • The page is now “connected” to AgentQL; you’ll see a query editor and results panel.

• Hosted Playground (browserless flow):

  • Paste a URL into the Playground.
  • AgentQL loads the page in a remote browser.
  • You interactively write queries and see JSON results without managing browser infrastructure.

Either way, you’re working against a live page, not a static HTML snapshot.

2. Define your schema‑first query

In the query editor, describe the shape of the data you want. Think in terms of JSON fields, not selectors.

Example: prototyping a Google Play Store query

{
  apps[] {
    name
    developer
    rating
    download_count
  }
}

AgentQL analyzes the page structure, finds the relevant elements, and returns structured JSON like:

{
  "apps": [
    {
      "name": "Fitness Tracker Pro",
      "developer": "Health Apps Inc",
      "rating": 4.7,
      "download_count": "1M+"
    }
  ]
}

You didn’t write a single CSS/XPath selector; AgentQL did the DOM analysis for you.

A few schema‑first patterns that tend to work well:

• Use arrays (items[], products[], apps[]) for lists.
• Use nested objects for complex structures (e.g., address, pricing, metadata).
• Add hints in field names or comments when you need something specific (e.g., product_price(include currency symbol)).

3. Refine using fast feedback

Now iterate until the JSON matches your real‑world need:

• Check for missing or noisy fields:

  • If rating is sometimes missing, decide whether to keep it nullable or adjust your query shape.
  • If download_count includes extra labels, tighten the field description.

• Rename fields for your downstream systems:

  • Change name to app_name or product_title to align with your internal schema.
  • Add nested structures if you know how this feeds into your data model.

Example revision:

{
  apps[] {
    app_name: name
    developer_name: developer
    rating
    download_count
  }
}

Result:

{
  "apps": [
    {
      "app_name": "Fitness Tracker Pro",
      "developer_name": "Health Apps Inc",
      "rating": 4.7,
      "download_count": "1M+"
    }
  ]
}

• Test across similar pages:
  • Navigate to another app or listing in the same site family.
  • Re‑run the query and confirm you still get consistent JSON.
  • This is where AgentQL’s “self‑healing” behavior pays off: the same query should work even if the page layout shifts slightly.

Keep iterating in Playground until:

• The JSON shape is exactly what your pipeline expects.
• The query is robust across representative pages (not just one lucky case).

4. Export the query to code

Once the query and output look right:

1. Open the Export or Code section in Playground / extension.
2. Choose your target surface:
   • JavaScript SDK (Playwright‑based)
   • Python SDK (Playwright‑based)
   • REST API (URL → JSON, no browser code needed)
3. Copy the generated snippet. It will embed your exact query string.

Example: JavaScript + Playwright (using agentql SDK)

npm install agentql

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

const client = new AgentQLClient({ apiKey: process.env.AGENTQL_API_KEY });

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto("https://play.google.com/store/apps/details?id=com.example");

  const query = `
    {
      apps[] {
        app_name: name
        developer_name: developer
        rating
        download_count
      }
    }
  `;

  const result = await client.query(page, query);

  console.log(JSON.stringify(result, null, 2));

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

You can paste this directly into your scraper or web agent, then iterate within your IDE instead of the Playground once you’re satisfied.

Example: Python + Playwright

pip3 install agentql

from playwright.sync_api import sync_playwright
from agentql import AgentQLClient
import os
import json

client = AgentQLClient(api_key=os.environ["AGENTQL_API_KEY"])

query = """
{
  apps[] {
    app_name: name
    developer_name: developer
    rating
    download_count
  }
}
"""

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://play.google.com/store/apps/details?id=com.example")

    result = client.query(page, query)
    print(json.dumps(result, indent=2))

    browser.close()

Example: Browserless REST API

For workflows where you’d rather call a hosted browser and just get back JSON:

POST https://api.agentql.com/v1/query
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://play.google.com/store/apps/details?id=com.example",
  "query": "{
    apps[] {
      app_name: name
      developer_name: developer
      rating
      download_count
    }
  }"
}

Response:

{
  "apps": [
    {
      "app_name": "Fitness Tracker Pro",
      "developer_name": "Health Apps Inc",
      "rating": 4.7,
      "download_count": "1M+"
    }
  ]
}

The core idea: the query you validated in Playground is exactly the one you embed in your production code.

Common Mistakes to Avoid

• Designing the query from code first:
  Jumping straight into Playwright and trying to guess a query slows you down and leads to trial‑and‑error runs.
  How to avoid it: Always prototype in Playground or the IDE extension first, validate JSON, then export to code.

• Over‑fitting the query to a single page:
  If you only test on one URL, you might inadvertently rely on layout quirks.
  How to avoid it: During prototyping, run the same query on several representative pages (different products, apps, locations) and confirm that the JSON remains consistent.

Real‑World Example

Say you’re building a marketplace intelligence pipeline and need consistent app metrics across Google Play Store:

1. Open an app page in AgentQL Playground.

2. Draft a schema‑first query:

   {
     apps[] {
       app_name: name
       developer_name: developer
       rating
       download_count
     }
   }
   

3. Refine field names and confirm the JSON is stable across multiple apps.

4. Export the validated query as a Python SDK snippet.

5. Drop the snippet into your ETL job that crawls app URLs and writes the JSON into your warehouse.

Because you invested a few minutes prototyping in Playground, your pipeline avoids brittle CSS/XPath selectors, handles minor layout changes with AgentQL’s self‑healing behavior, and produces clean JSON ready for downstream analysis or LLM grounding.

Pro Tip: Treat the query you build in Playground as an API contract. Once it’s stable across a sample set of pages, commit it to your repo as a versioned schema (e.g., google_play_app_v1.agentql) so any future changes are explicit and reviewable.

Summary

AgentQL Playground is your fastest way to move from “I need this data from the web” to “I have a robust query and production‑ready code.” You prototype against live pages, iterate on the schema until the JSON fits your pipeline, then export language‑specific snippets for the JS/Python SDKs or the REST API. That workflow replaces fragile selector hunting with query‑driven, self‑healing extraction that slots cleanly into your existing Playwright scripts or browserless data flows.

Next Step

Get Started