ax

ax — Web スクレイピングと抽出のための AI 時代の Curl

バージョン 1.0.0
Yusuke Bebé & Contributors
AI 駆動のフェッチ、探索、抽出フレームワーク

---

概要

ax は、AI エージェントが Web ページをフェッチし、その構造を探索して、構造化データを抽出するために特化したコマンドラインツールです。従来の curl → parse → regex のループを、決定論的でトークン効率の高い単一のコマンドに置き換えます。

ax を使用する場面

• エージェントにページをフェッチさせ、構造化データを抽出させる必要がある場合
• 生の HTML を出力せずにページを探索（--outline）したい場合
• CSS セレクター（--row、--table）で複数フィールドの行を抽出する場合
• トークンに合わせた出力（上限付き、予算管理可能）が必要な場合
• 繰り返し実行できる Web スクレイピングのエージェントタスクを構築する場合
• エージェントのコード内で curl | grep | awk のパイプラインを使うのにうんざりしている場合

ax を使用しない場面

• 対象サイトでクライアント側の JavaScript によるレンダリングが必要な場合（代わりに Playwright または Puppeteer を使用してください）
• リアルタイムのブラウザー自動化や複数ステップの操作が必要な場合
• ヘッダーでは解決できない認証の背後にコンテンツがある場合（代わりに直接 API を使用してください）
• ビジュアルテスト用のヘッドレスブラウザーが必要な場合

---

クイックスタート

ax をインストールする

# System-wide install (via shell script)
curl -fsSL https://ax.yusuke.run/install | sh

# Or via Homebrew (macOS/Linux)
brew install yusukebe/tap/ax

# Or via npm (if Node.js available)
npm install -g ax-cli

基本的な使い方

# Fetch and show full response
ax https://api.example.com/users

# Discover page structure
ax https://example.com --outline

# Extract rows with custom selectors
ax https://example.com '.item' --row 'title=a, href=a@href'

# Read docs as markdown
ax https://docs.example.com --md --budget 800

# Extract table to JSON
ax https://example.com 'table' --table --json

エージェントのワークフローに統合する

# Run with agent context (shows optimized flags for LLMs)
ax agent-context

# Use in agentic script
ITEMS=$(ax https://shop.example.com '.product' \
  --row 'name=h2, price=.price' \
  --where 'price < 100' \
  --json)

---

基本概念

1. フェッチモード — 完全なコンテキストを含むライブデータ

コマンド： ax <url>

JSON 構造のレスポンス { status, ok, ms, headers, body } を返します。出力なしで終了することはありません。

• すべてのリクエストはライブです（デフォルトではキャッシュしません）
• 本文が空でも完全なレポートを生成します
• JSON レスポンスは自動的に解析されます
• 従来の curl のように標準出力へパイプする場合は --body を使用します
• 通常のレイテンシーは 100ms 以上です。SSL 検証をスキップする場合は --no-check を使用してください（開発時のみ）

ax https://api.github.com/repos/yusukebe/ax
# Output:
# {
#   "status": 200,
#   "ok": true,
#   "ms": 142,
#   "headers": { "content-type": "application/json", ... },
#   "body": { "name": "ax", "stars": 450, ... }
# }

2. 解析モード — キャッシュされた HTML の探索

フラグ： --outline、--locate、--md

URL をフェッチすると、以降のプローブを高速化するため、HTML がローカルにキャッシュされます（約 2 分間）。

• --outline：繰り返し現れる DOM 構造を表示します（出力に生のマークアップは含まれません）
• --locate 'text'：指定したテキストを含む CSS セレクターを検索します
• --md：HTML を読みやすい Markdown に変換します
• キャッシュがヒットするたびに stderr に通知します
• --fresh は再フェッチを強制します。--no-cache はディスクキャッシュを完全に無効にします

ax https://news.example.com --outline
# Output:
# main
#   article (×12)
#     h2.headline (×1)
#     p.summary (×1)
#     a.read-more (×1)

3. 抽出モード — 構造化データの行

フラグ： --row、--table、--where

複数フィールドの行を単一のコマンドで取得し、安全な式言語でフィルタリングします。

# Custom row format
ax https://shop.example.com '.item' \
  --row 'name=h2, price=.price, rating=.stars' \
  --where 'price > 50'

# Table extraction (auto-detects <table>)
ax https://data.example.com --table --json

# Output format: TSV by default (header once), --json for JSON array

• --row 'field1=selector, field2=selector@attr'：フィールドと CSS セレクターを定義します
• @attr：属性を抽出します（例：a@href）。デフォルトは .textContent です
• --where 'expr'：行をフィルタリングします。安全な式言語を使用します（コードは実行されません）
• --json：TSV の代わりに JSON を出力します
• --limit 50：結果の行数を制限します（デフォルトは 50）

4. トークン予算管理 — AI コンテキストの最適化

フラグ： --budget <tokens>

LLM のコンテキストウィンドウに合わせて結果を整形します。

• デフォルトでは出力を約 50 行に制限します（stderr に通知します）
• --budget 800 は出力を推定約 800 トークンに制限します
• 結果には必ず行数と切り捨てに関する注記が含まれます
• TSV 形式はトークン効率が高く、JSON は構造化データの解析に柔軟に対応できます

ax https://catalog.example.com '.product' \
  --row 'name=h2, price=.price' \
  --budget 500
# If 200 rows match, shows first ~40 to fit token budget
# stderr: "Truncated to 40 of 200 rows (token budget: 500)"

---

エージェント向けの使用パターン

パターン 1：ページの探索（コード不要、質問を通じて探索）

エージェントがページ構造を把握していない場合は、--outline を使ってエージェントが質問できるようにします。

ax https://docs.example.com --outline
# Agent reads structure, asks targeted follow-up
# ax https://docs.example.com 'h2' --md --budget 300

パターン 2：行の一括抽出

エージェントが繰り返し構造から表形式のデータを必要としている場合：

ax https://items.example.com '.item' \
  --row 'title=h2, url=a@href, price=.price' \
  --json

# Output: JSON array of objects, agent iterates
# Use in script: `jq '.[] | select(.price < 50)' | ...`

パターン 3：Markdown ドキュメントの抽出

エージェントが人間に読みやすいドキュメントを必要としている場合：

ax https://guide.example.com/intro --md --budget 2000
# Returns markdown-formatted text, preserves headers, links, structure

パターン 4：ライブ API の監視

エージェントが JSON API エンドポイントを繰り返し確認する場合：

# No cache (live every time)
ax https://api.status.example.com/incident-count

パターン 5：フィルタリングと変換

エージェントが行を抽出してフィルタリングし、後続の処理に渡す場合：

ax https://store.example.com '.sale-item' \
  --row 'name=h2, old_price=.old-price, discount=.discount' \
  --where 'discount > 30' \
  --json | jq '.[] | {name, savings: (.old_price * .discount / 100)}'

---

エージェントスキルとの統合

deep-agents-core との連携

カスタムエージェントツールで ax を使用します。

from deep_agents import tool

@tool("scrape_page")
async def scrape_page(url: str, selector: str = None, extract_mode: str = "outline"):
    """Fetch and parse web pages with ax."""
    cmd = f"ax {url}"
    if extract_mode == "outline":
        cmd += " --outline"
    elif extract_mode == "rows" and selector:
        cmd += f" '{selector}' --row 'content=*' --json"
    
    result = await run_shell(cmd)
    return result

react-grab との連携

React 要素を対象にする前に、ax で HTML 構造を抽出します。

# Get page outline to understand React component tree
ax https://app.example.com --outline

# Then use react-grab to capture specific component
react-grab --selector '.user-card'

research との連携（並列探索）

複数の URL に対して ax を並行実行します。

# Wrapper script: parallel-discover.sh
for url in $(cat urls.txt); do
  ax "$url" --outline --budget 300 &
done | wait

---

よくあるタスク

タスク：ページからすべてのリンクを抽出する

ax https://example.com --row 'text=a, href=a@href' --json

タスク：特定のセクションを見つける

ax https://docs.example.com --locate 'Installation' --md

タスク：API エンドポイントを監視する

ax https://api.example.com/status | jq '.body | select(.status == "ok")'

タスク：テーブルを抽出して CSV に変換する

ax https://data.example.com 'table.report' --table --json | \
  jq -r '.[] | [.col1, .col2, .col3] | @csv'

タスク：エージェント主導の探索フロー

# Step 1: Outline (cheap, informs next step)
ax https://site.example.com --outline

# Step 2: Extract (targeted, uses agent's observations)
ax https://site.example.com '.observed-selector' --row 'field=selector' --json

---

ベストプラクティス

1. まずは必ず --outline を使う

セレクターを書く前に、--outline を使ってページ構造を把握してください。トークンは消費しますが、解析を何度も繰り返す手間を大幅に減らせます。

# Right: Agent learns structure first
ax https://example.com --outline

# Then: Targeted extraction
ax https://example.com '.item' --row 'name=h2'

# Wrong: Guessing selectors and failing
ax https://example.com 'div.product-card' --row 'price=.cost'  # Oops, wrong selector

2. クライアント側のフィルタリングには --where を使う

すべての行を抽出してエージェントのコードで絞り込むのではなく、取得元でフィルタリングしてください。

# Right: Server-side filter
ax https://shop.example.com '.item' \
  --row 'name=h2, price=.price' \
  --where 'price > 50 && price < 200'

# Wasteful: Extract all, filter in agent
ax https://shop.example.com '.item' --row 'name=h2, price=.price' --json
# Agent: "if row.price > 50 and row.price < 200: ..."

3. レート制限と robots.txt を遵守する

• スクレイピングを自動化する前に、robots.txt を確認してください
• リクエスト間には適切な間隔を設けてください（利用できる場合は --delay <ms> を使用します）
• 可能な場合は、User-Agent ヘッダーでエージェントを識別してください
• --no-cache の使用は必要最小限にとどめ、キャッシュヒットを活用して負荷を減らしてください

4. 大規模なデータセットのトークン予算

データセットの規模が不明な場合は、必ず結果数に上限を設定してください。

# Right: Safe upper bound
ax https://catalog.example.com '.item' --budget 500

# Risky: No limit, may blow context window
ax https://catalog.example.com '.item' --json

5. 空のレスポンス／エラーレスポンスへの対処

ax はエラーを黙って無視することはなく、常にレスポンスのメタデータを出力します。

ax https://down.example.com
# Output:
# {
#   "status": 503,
#   "ok": false,
#   "ms": 1200,
#   "headers": { "retry-after": "60" },
#   "body": ""
# }

エージェントは、本文を解析する前に ok フラグと status を確認してください。

---

パフォーマンスとベンチマーク

コスト削減（実際の Opus 4.8 セッション）

タスク	ax なし	ax あり	削減率
2 ページ間のマークアップの差異	$0.458	$0.150	−67%
60 項目のカタログ抽出	$0.296 (24s)	$0.104 (14s)	−65%
おとり要素のあるライブウェブサイト	$0.248	$0.191	−23%
マークアップの差異（初回使用時）	$0.664	$0.282	−58%

詳細な手法については、ax リポジトリの bench/RESULTS.md をご覧ください。

なぜ速く、安くなるのか？

1. トークン効率： 構造化された出力と予算上限の設定により、リクエストあたりのトークン数を削減します
2. 生の HTML を使用しない： --outline はマークアップ全体を出力するよりも、はるかに少ないトークンで済みます
3. 再試行が少ない： 決定的な抽出により、「うまくいかなかったので、もう一度試す」ことがなくなります
4. ネイティブ CLI： タスクの途中でエージェントがシェルスクリプトを書いてデバッグする必要がありません

---

トラブルシューティング

問題：「Empty body」または「selector found 0 matches」

原因： セレクターがページ構造に一致していないか、コンテンツがクライアント側でレンダリングされています。

対処方法：

1. ax <url> --outline を実行して構造を確認します
2. ax <url> --locate 'visible text' を使って適切なセレクターを見つけます
3. outline の後も空の場合、コンテンツは JS でレンダリングされている可能性があります → 代わりに Playwright を試してください

問題：レート制限またはブロック

原因： リクエストが多すぎるか、User-Agent が設定されていません。

対処方法：

1. キャッシュを有効にします：ax <url>（フェッチモードではデフォルトでキャッシュが有効です）
2. スクリプト内でリクエスト間に --delay <ms> を使用します
3. robots.txt を確認し、crawl-delay を遵守します
4. User-Agent ヘッダーを追加します：ax <url> -H 'User-Agent: MyAgent/1.0'

問題：「Truncated to N of M rows」

原因： 結果がトークン予算を超えています。

対処方法：

1. 重要なデータが切り捨てられている場合は、--budget を増やします
2. または、--where フィルターを絞り込んで返される行数を減らします
3. または、複数の小さなクエリに分割します

---

他のスキルへのルーティング

必要なこと	スキル	理由
複雑なページ操作、複数ステップのフロー	Playwright を使った deep-agents-core	ブラウザー自動化が必要です
抽出後の React コンポーネントの検査	react-grab	ax による探索と要素の取得を組み合わせます
多数のサイトの並列スクレイピング	research（マルチエージェント）	ax 呼び出しを並行して調整します
トークン予算の最適化	react-best-practices	LLM のコンテキストに収まるよう出力を構成します
抽出したマークアップのアクセシビリティ検証	accessible-markup	スクレイピングしたコンテンツを WCAG に照らして検証します

---

比較：ax と代替ツール

機能	curl	htmlq	Firecrawl	ax
URL の取得	✓	✗	✓	✓
構造の把握（--outline）	✗	✗	△	✓
複数フィールドの抽出	✗	△（N 回実行）	✓	✓
Markdown の抽出（--md）	✗	✗	✓	✓
トークン予算に応じた出力	✗	✗	✗	✓
タスクごとのコードが不要	✗	△（パイプ処理が煩雑）	✓	✓
キャッシュ済みの解析（無料の調査）	✗	✗	✗	✓
安全なフィルタリング（--where）	✗	✗	△	✓

---

参考情報

• 公式サイト： https://ax.yusuke.run
• GitHub： https://github.com/yusukebe/ax
• エージェント向けコンテキストとフラグ： ax agent-context（https://ax.yusuke.run/llms.txt も参照）
• ベンチマーク： https://github.com/yusukebe/ax/blob/main/bench/RESULTS.md
• 使用技術： Bun（単一ファイルのバイナリ）＋ linkedom（DOM 解析）

---

ルーティングの概要（エージェントの応答用）

エージェントのタスクから ax を呼び出す際は、次の内容を使用してください。

ax（取得、構造の把握、抽出）→ ヘッドレスブラウザーを使わずにエージェントがウェブデータを必要とする場合に使用します。無料で構造を把握するには ax <url> --outline を実行し、その後 ax <url> 'selector' --row で抽出します。トークン予算と安全なフィルタリングが組み込まれています。インタラクションが必要な場合は Playwright にルーティングし、複数 URL の並列処理には research スキルにルーティングしてください。

---

ライセンス

ax はオープンソースです（ライセンスはリポジトリをご確認ください）。複数のインストール方法（シェルスクリプト、Homebrew、npm）を利用できます。

---

最終更新： 2026 年 7 月 — ax v1.1 以降の機能を反映しています