AgentQL入門 - AIでWebスクレイピングが劇的に変わる、自然言語クエリの世界

はじめに

Webスクレイピング、やってますか。

正直なところ、スクレイピングって地味に面倒ですよね。CSSセレクタやXPathでDOM要素を指定して、サイトのHTML構造が変わったら動かなくなる。メンテナンスコストが馬鹿にならないという話、よく聞きます。

そんな中で最近注目を集めているのがAgentQLです。AIを活用したWebスクレイピング・自動化ツールで、自然言語でページ上の要素を指定できます。GitHubのスター数は1,100以上、MITライセンスで公開されています。

個人的には、AgentQLを触ってみて「これはスクレイピングの常識が変わるな」と感じました。今回はその理由を含めて、AgentQLの魅力を紹介していきます。

AgentQLとは

AgentQLは、「AI-powered query language for web scraping and automation」を謳うツール群です。tinyfish-io社が開発しており、AIやLLMをWebに接続するための機能を提供しています。

主な特徴は以下の通りです。

自然言語クエリ: CSSセレクタの代わりに、直感的な名前で要素を指定できる
構造化出力: クエリの形状に基づいて定義された出力形式を返す
UI変更への耐性: ページ構造の変化に対応した自己修復機能
クロスサイト互換性: 類似コンテンツを持つ異なるサイト間で同一クエリを使用可能
Playwright連携: Python・JavaScriptのSDKでPlaywrightと組み合わせて使える

特に「自己修復機能」は実務的に嬉しい。サイトのリニューアルでHTMLの構造が変わっても、AIが意味を理解して要素を見つけてくれます。

特徴・メリット

1. 自然言語で要素を指定できる

AgentQLの最大の特徴は、自然言語のようなクエリで要素を指定できることです。

従来のスクレイピングでは、こんな感じでCSSセレクタを書いていました。

// 従来の方法
const button = page.locator('.header-nav button.submit-btn');

AgentQLを使うと、こうなります。

// AgentQLの方法
const { search_button } = await page.queryElements(`{ search_button }`);

これ、意外と大きな違いなんですよね。CSSセレクタはHTMLの構造に強く依存しますが、AgentQLは「検索ボタン」という意味で要素を見つけてくれます。

2. UI変更に強い自己修復機能

サイトがリニューアルしてHTMLの構造が変わった経験、ありませんか。従来のスクレイピングだと、セレクタを全部書き直す必要がありました。

AgentQLはAIがページの内容を理解して要素を特定するので、多少のレイアウト変更では壊れません。これは運用コストの面で大きなメリットです。

3. 複数サイトで同じクエリが使える

ECサイトの価格比較とか、ニュースサイトの記事収集とか、複数サイトから同じ種類のデータを取りたいケースは多いです。

従来は各サイトごとにセレクタを書く必要がありましたが、AgentQLなら同じクエリで対応できることが多い。「商品名」「価格」といった意味でAIが要素を見つけてくれるからですね。

4. Playwrightとの連携が簡単

AgentQLはPlaywrightのページオブジェクトをラップして使います。Playwrightの機能（スクリーンショット、PDF生成、ネットワークインターセプトなど）をそのまま活用できるので、既存のPlaywright資産を活かせます。

インストール方法

Python版とJavaScript版があります。

Pythonの場合

pip3 install agentql
agentql init

JavaScriptの場合

npm install agentql
npm install -g agentql-cli
agentql init

APIキーの設定

AgentQLを使うにはAPIキーが必要です。AgentQL Developer Portalで無料で取得できます。

# Linux/macOS
export AGENTQL_API_KEY=your-api-key

# Windows (PowerShell)
$env:AGENTQL_API_KEY="your-api-key"

基本的な使い方

クエリの基本構文

AgentQLのクエリはシンプルです。

// 単一要素を取得
{ search_button }

// 複数要素を配列で取得
{ headings[] }

// ネストした構造
{ breadcrumbs { first_item last_item } }

Pythonでの基本的な例

import agentql
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = agentql.wrap(browser.new_page())

    page.goto("https://example.com")

    # 自然言語クエリで要素を取得
    response = page.query_elements("""
    {
        search_input
        search_button
    }
    """)

    # 要素を操作
    response.search_input.fill("AgentQL")
    response.search_button.click()

    browser.close()

JavaScriptでの基本的な例

const { wrap } = require('agentql');
const { chromium } = require('playwright');

(async () => {
    const browser = await chromium.launch({ headless: false });
    const page = wrap(await browser.newPage());

    await page.goto('https://example.com');

    // 自然言語クエリで要素を取得
    const { search_input, search_button } = await page.queryElements(`
    {
        search_input
        search_button
    }
    `);

    // 要素を操作
    await search_input.fill('AgentQL');
    await search_button.click();

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

getByPromptでシンプルに取得

単一の要素を取得したい場合はgetByPromptが便利です。

# Python
button = page.get_by_prompt("送信ボタン")
button.click()

// JavaScript
const button = await page.getByPrompt("submit button");
await button.click();

実践的なユースケース

ECサイトの商品情報を取得

import agentql
from playwright.sync_api import sync_playwright

QUERY = """
{
    products[] {
        product_name
        price
        rating
        review_count
    }
}
"""

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = agentql.wrap(browser.new_page())

    page.goto("https://example-shop.com/products")

    response = page.query_elements(QUERY)

    for product in response.products:
        print(f"商品名: {product.product_name.text_content()}")
        print(f"価格: {product.price.text_content()}")
        print(f"評価: {product.rating.text_content()}")
        print("---")

    browser.close()

ログインフローの自動化

import agentql
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = agentql.wrap(browser.new_page())

    page.goto("https://example.com/login")

    # ログインフォームの要素を取得
    login_form = page.query_elements("""
    {
        email_input
        password_input
        login_button
    }
    """)

    # フォームに入力
    login_form.email_input.fill("user@example.com")
    login_form.password_input.fill("password123")
    login_form.login_button.click()

    # ログイン後のダッシュボードを確認
    page.wait_for_url("**/dashboard")

    browser.close()

クッキーダイアログの処理

最近のWebサイトはクッキー同意ダイアログが多いですよね。AgentQLなら簡単に処理できます。

import agentql
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = agentql.wrap(browser.new_page())

    page.goto("https://example.com")

    # クッキーダイアログがあれば閉じる
    try:
        cookie_dialog = page.query_elements("""
        {
            accept_cookies_button
        }
        """, timeout=3000)
        cookie_dialog.accept_cookies_button.click()
    except:
        pass  # ダイアログがなければスキップ

    # メインのスクレイピング処理
    # ...

    browser.close()

REST APIでの利用

SDKを使わずにREST APIで直接データを取得することもできます。

curl -X POST https://api.agentql.com/v1/query \
  -H "Authorization: Bearer $AGENTQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "query": "{ main_heading product_list[] { name price } }"
  }'