Browsegrab

browsegrab

韓国語ドキュメント · llms.txt

ローカル LLM 向けのトークン効率に優れたブラウザーエージェント — Playwright + アクセシビリティツリー + MarkGrab、MCP ネイティブ。

browsegrab は、ローカル LLM（8B〜35B パラメーター）向けに設計された軽量なブラウザー自動化ライブラリです。Playwright のアクセシビリティツリーと MarkGrab の HTML から Markdown への変換を組み合わせることで、browser-use などの代替手段と比べて、ステップあたりのトークン数を 5〜8 倍削減します。

特長

• トークン効率に優れています：ステップあたり約 500〜1,500 トークン（browser-use は 4,000〜10,000）
• ローカル LLM を優先：vLLM、Ollama、OpenAI 互換エンドポイント向けに最適化されています
• MCP ネイティブ：ブラウザー自動化ツールを 8 つ備えた組み込み MCP サーバー
• MarkGrab との統合：HTML → クリーンな Markdown に変換してコンテンツを抽出します
• アクセシビリティツリー + ref システム：ビジョンモデルを使わずに、安定した要素参照（e1、e2、...）を提供します
• 成功パターンのキャッシュ：ワークフローの繰り返し時に LLM 呼び出しが発生しません
• 5 段階 JSON パーサー：ローカル LLM の出力に対応する堅牢なアクション解析
• 最小限の依存関係：コアで使用するのは playwright + httpx のみです

インストール

pip install browsegrab
playwright install chromium

オプション機能を含める場合：

pip install browsegrab[mcp]      # MCP server support
pip install browsegrab[content]  # MarkGrab content extraction
pip install browsegrab[cli]      # CLI with rich output
pip install browsegrab[all]      # Everything

クイックスタート

Python API

from browsegrab import BrowseSession

async with BrowseSession() as session:
    # Navigate and get accessibility tree snapshot
    await session.navigate("https://example.com")
    snap = await session.snapshot()
    print(snap.tree_text)
    # - heading "Example Domain" [level=1]
    # - link "Learn more": [ref=e1]

    # Click using ref ID
    result = await session.click("e1")
    print(result.url)  # https://www.iana.org/help/example-domains

    # Type into search box
    await session.navigate("https://en.wikipedia.org")
    snap = await session.snapshot()
    await session.type("e4", "Python programming", submit=True)

    # Extract compressed content (AX tree + markdown)
    content = await session.extract_content()

CLI

# Accessibility tree snapshot
browsegrab snapshot https://example.com

# JSON output
browsegrab snapshot https://example.com -f json

# Extract content (AX tree + markdown)
browsegrab extract https://en.wikipedia.org/wiki/Python

# Agentic browse (requires LLM endpoint)
browsegrab browse https://example.com "Find the about page"

MCP サーバー

browsegrab-mcp  # Start MCP server (stdio)

Claude Desktop / Cursor / VS Code の設定：

{
  "mcpServers": {
    "browsegrab": {
      "command": "browsegrab-mcp"
    }
  }
}

8 つの MCP ツール：browser_navigate、browser_click、browser_type、browser_snapshot、browser_scroll、browser_extract_content、browser_go_back、browser_wait

仕組み

エージェントのブラウジングループ

flowchart LR
    A["🌐 URL + Goal"] --> B["Navigate"]
    B --> C["AX Tree Snapshot\n~200–500 tokens"]
    C --> D{"LLM\nDecision"}
    D -->|"click / type / scroll"| E["Execute Action"]
    E --> C
    D -->|"goal reached"| F["Extract Content\n(MarkGrab)"]
    F --> G["✅ Result"]

トークン効率

browsegrab は 構造（アクセシビリティツリー）とコンテンツ（MarkGrab Markdown）を分離し、LLM が必要とする情報だけを送信します。

flowchart TD
    A["Raw HTML"] --> B["Accessibility Tree"]
    A --> C["MarkGrab Markdown"]
    B --> D["Structure: ~200–500 tokens\nInteractive elements with ref IDs"]
    C --> E["Content: ~300–800 tokens\nClean markdown · on-demand"]
    D --> F["Combined: ~500–1,300 tokens/step\n⚡ 5–8× fewer than browser-use"]
    E --> F

トークン効率（測定値）

ページ	インタラクティブ要素	トークン数	browser-use 相当
example.com	1	約 60	約 500 以上
Wikipedia の記事	452	約 1,254	約 10,000 以上

アーキテクチャ

browsegrab/
├── config.py                 # Dataclass configs (env var loading)
├── result.py                 # Result types (ActionResult, BrowseResult, ...)
├── session.py                # BrowseSession orchestrator
├── browser/
│   ├── manager.py            # Playwright lifecycle (async context manager)
│   ├── snapshot.py           # Accessibility tree + ref system
│   ├── selectors.py          # 4-strategy selector resolver
│   └── actions.py            # navigate, click, type, scroll, go_back, wait
├── dom/
│   ├── ref_map.py            # ref ID ↔ element bidirectional mapping
│   └── compress.py           # AX tree + MarkGrab → compressed context
├── llm/
│   ├── base.py               # LLMProvider ABC
│   ├── provider.py           # vLLM, Ollama, OpenAI-compatible
│   ├── prompt.py             # System prompts (~400 tokens)
│   └── parse.py              # 5-stage JSON fallback parser
├── agent/
│   ├── history.py            # Sliding window history compression
│   ├── cache.py              # Domain-based success pattern cache
│   └── loop_guard.py         # Duplicate action detection
├── __main__.py               # CLI (click)
└── mcp_server.py             # FastMCP server (8 tools)

設定

すべての設定は環境変数（BROWSEGRAB_* プレフィックス）で行います。

# Browser
BROWSEGRAB_BROWSER_HEADLESS=true
BROWSEGRAB_BROWSER_TIMEOUT_MS=30000

# LLM (for agentic browse)
BROWSEGRAB_LLM_PROVIDER=vllm          # vllm | ollama | openai
BROWSEGRAB_LLM_BASE_URL=http://localhost:8000/v1
BROWSEGRAB_LLM_MODEL=Qwen/Qwen3.5-32B-AWQ

# Agent
BROWSEGRAB_AGENT_MAX_STEPS=10
BROWSEGRAB_AGENT_ENABLE_CACHE=true

QuartzUnit エコシステムの一部

ライブラリ	役割
markgrab	パッシブな抽出（URL → Markdown）
snapgrab	パッシブなキャプチャ（URL → スクリーンショット）
docpick	ドキュメント OCR → 構造化 JSON
browsegrab	アクティブな自動化（目標 → ブラウザー操作 → 結果）

開発

git clone https://github.com/QuartzUnit/browsegrab.git
cd browsegrab
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
playwright install chromium

# Unit tests (no browser needed)
pytest tests/ -m "not e2e"

# Full suite including E2E
pytest tests/ -v

ライセンス

MIT

---

_{QuartzUnit エコシステムの一部 — データ収集、抽出、検索、AI エージェントの安全性を支える、組み合わせて使える Python ライブラリ。}