agent-debugger

Chrome拡張向けブラウザ自動化ライブラリ。agent-browserのインターフェースを踏襲し、chrome.debugger API（CDP）を使用してブラウザ操作を抽象化。

Features

• Chrome DevTools Protocol（CDP）ベースのブラウザ操作
• アクセシビリティツリーベースのスナップショット機能
• Ref System（@e1, @e2）による要素の確実な特定
• TypeScript完全対応
• Chrome拡張（Manifest V3）対応

Installation

npm install agent-debugger

Usage

Chrome拡張のbackground scriptで使用:

import { AgentDebugger } from 'agent-debugger';

// インスタンス作成
const debugger = new AgentDebugger();

// 現在のタブにアタッチ
const tabs = await chrome.tabs.query({ active: true, currentWindow: true });
await debugger.attach(tabs[0].id);

// ページナビゲーション
await debugger.navigate('https://example.com');

// スナップショット取得（アクセシビリティツリー）
const snapshot = await debugger.snapshot();
console.log(snapshot.tree);
// - document [ref=e1]
//   - heading "Example Domain" [ref=e2]
//   - paragraph "This domain is for..." [ref=e3]
//   - link "More information..." [ref=e4]

// Refを使ってクリック
await debugger.click('@e4');

// フォーム入力
await debugger.fill('@e5', 'Hello World');

// スクリーンショット
const screenshot = await debugger.screenshot();

// デタッチ
await debugger.detach();

API

AgentDebugger

メインクラス。

class AgentDebugger {
  // タブにアタッチ
  async attach(tabId?: number): Promise<AttachData>

  // デタッチ
  async detach(): Promise<void>

  // コマンド実行
  async execute(command: Command | string): Promise<Response>

  // スナップショット取得
  async snapshot(options?: SnapshotOptions): Promise<SnapshotData>

  // 便利メソッド
  async navigate(url: string): Promise<void>
  async click(selector: string): Promise<void>
  async fill(selector: string, value: string): Promise<void>
  async type(text: string, options?: TypeOptions): Promise<void>
  async screenshot(options?: ScreenshotOptions): Promise<string>
  async evaluate<T>(expression: string): Promise<T>
  async waitFor(selector: string, timeout?: number): Promise<void>
  async getUrl(): Promise<string>
  async getTitle(): Promise<string>
  async getText(selector: string): Promise<string>
  async isVisible(selector: string): Promise<boolean>
}

Commands

サポートされているコマンド:

| Action | Description | |--------|-------------| | attach | タブにデバッガをアタッチ | | detach | デタッチ | | navigate | URLに遷移 | | click | 要素をクリック | | fill | input/textareaに値を設定 | | type | キー入力 | | snapshot | アクセシビリティツリー取得 | | screenshot | スクリーンショット取得 | | wait | 条件待機 | | scroll | スクロール | | evaluate | JavaScript実行 |

Selectors

セレクタ形式:

• @e1, @e2... - Ref ID（スナップショットから取得）
• CSS selectors - 標準のCSSセレクタ

Ref形式を推奨。アクセシビリティツリーから一意に要素を特定できる。

Examples

examples/ディレクトリにサンプル実装:

Chrome Extension (examples/extension/)

デバッグ用Chrome拡張のサンプル。

# 開発ビルド
cd examples/extension
npm install
npm run build

# Chromeにインストール
# 1. chrome://extensions を開く
# 2. 「デベロッパーモード」を有効化
# 3. 「パッケージ化されていない拡張機能を読み込む」
# 4. examples/extension/dist フォルダを選択

API Server (examples/api-server/)

WebSocket + LLM連携サーバー。

cd examples/api-server
npm install

# 環境変数設定
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

# 起動
npm start

機能:

• WebSocket経由でChrome拡張と通信
• OpenAI/Anthropic APIでLLM呼び出し
• セッション管理

UI (examples/ui/)

React + TypeScriptのデバッグUI。

cd examples/ui
npm install
npm run dev

機能:

• WebSocket接続管理
• スナップショットビューワー（クリック可能なRef表示）
• LLMチャットインターフェース
• コマンドログ

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Sample UI     │────▶│   API Server     │◀────│   LLM API   │
│   (React)       │     │   (WebSocket)    │     │(OpenAI等)   │
└─────────────────┘     └────────┬─────────┘     └─────────────┘
                                 │
                                 ▼
                        ┌──────────────────┐
                        │ Chrome Extension │
                        │  (agent-debugger)│
                        └────────┬─────────┘
                                 │ chrome.debugger API (CDP)
                                 ▼
                        ┌──────────────────┐
                        │   Chrome Tab     │
                        └──────────────────┘

Development

# インストール
npm install

# ビルド
npm run build

# テスト
npm test

Requirements

• Chrome 88+ (Manifest V3対応)
• Node.js 18+

Chrome Extension Permissions

manifest.jsonに必要な権限:

{
  "permissions": [
    "debugger",
    "tabs",
    "activeTab"
  ]
}

License

MIT

Credits

This project is based on agent-browser by Vercel Labs.