qz-browser-agentとは？
qz-browser-agent（轻舟、英語で「light boat」とも呼ばれます）は、ウェブリサーチ、ブラウザー自動化、構造化データ抽出に対応したローカルファーストのChrome拡張機能です。独自のモデルプロバイダーを接続し、ブラウザーのサイドパネルからウェブサイトを操作したり、再利用可能なSkillsやTypeScript機能でエージェントを拡張したりできます。
セッション、Skills、収集したデータはブラウザーに保存されます。モデルへのリクエストには、プロンプトに加えて、タスクのコンテキストに追加したページやファイルの内容が含まれる場合があります。SkillsやMCP接続では、設定したサービスとデータを交換することがあります。外部サービスを利用する前に、プロジェクトの権限とデータフローのドキュメントを確認してください。
主な機能
- ブラウザー自動化：DOM要素やスクリーンショットを操作し、フォームに入力し、デスクトップまたはモバイルのビューポートで複数のタブを横断して作業できます。
- サブタスクの並列実行：タスクを同時に実行し、処理中に中断、方向転換、コンテキストの追加を行えます。
- 構造化データ：表、メディア、ページコンテンツをローカルコレクションに抽出し、サイドパネルから結果をプレビュー、編集、エクスポートできます。
- Skills：手順、スクリプト、ツール、カスタムサイドパネルUIを再利用可能なワークフローとしてパッケージ化できます。条件に一致するウェブサイトでの任意の自動有効化にも対応します。
- モデルの選択：ローカルモデルサーバーを含め、互換性のあるAPIプロトコルとツール呼び出しに対応するプロバイダーを接続できます。
- TypeScript機能：エージェントツール、パネルビュー、設定ページ、モデルプロバイダーを追加できます。
- MCPブリッジ：必要に応じて、ローカルMCPブリッジを通じてブラウザーツールやタスク制御を外部エージェントに公開できます。
Chrome拡張機能をインストールする
最新リリースを使用する
- qz-browser-agentの最新リリースをダウンロードします。
- ダウンロードしたZIPアーカイブを展開します。
- Chromeで
chrome://extensionsを開きます。 - デベロッパーモードを有効にします。
- パッケージ化されていない拡張機能を読み込むをクリックし、展開した
qz-browser-agent-extensionフォルダーを選択します。
ソースからビルドする
qzをローカルでビルドするには、Node.js 24 LTSとnpmをインストールしてから、リポジトリをクローンまたはダウンロードします。プロジェクトディレクトリで依存関係をインストールし、拡張機能のビルドを作成します。
npm ci
npm run buildビルドが完了したら、chrome://extensionsに戻り、パッケージ化されていない拡張機能を読み込むを選択して、生成されたdist/extension/ディレクトリを指定します。
モデルプロバイダーを設定する
- 拡張機能ツールバーからqzのサイドパネルを開きます。
- 設定を開きます。
- モデルプロバイダーを選択し、認証情報を入力します。
- カスタムエンドポイントを使用する場合は、そのURLと対応プロトコルを指定します。
- モデルを選択して設定を保存します。
qzは、対応するAPIプロトコルとツール呼び出しを公開するプロバイダーで動作するよう設計されています。環境に応じて、互換性のあるホステッドプロバイダーまたはローカルモデルサーバーを利用できます。
最初のブラウザータスクを実行する
プロバイダーを設定したら、簡単なリサーチと抽出のリクエストから始めます。
example.comを開き、メイン見出しを表に抽出してください。エージェントは指定されたページに移動してコンテンツを調査し、抽出した結果をローカルコレクションに保存できます。サイドパネルで収集データをプレビューまたは編集し、コレクションの準備ができたらエクスポートしてください。
より複雑なリサーチでは、複数のページやタブにわたって作業するようqzに指示できます。タスクに独立した作業が含まれる場合は、サブタスクを並列実行すると同時に処理できます。実行中のタスクを中断したり、方向転換させたり、追加のコンテキストを与えたりすることもできます。
Skillsでqzを拡張する
Skillsは、繰り返し実行するワークフローのための再利用可能なパッケージです。Skillには、手順、JavaScriptによる自動化、ツール、サイドパネル内のカスタムインタラクティブウィジェットを組み合わせられます。Site Skillsは、条件に一致するウェブサイトで有効になるよう設定することもできます。
Skillsはqzのインターフェースから管理するか、Gitリポジトリからインストールできます。特定のサイトから情報を収集したり、カスタムパネルコンポーネントで結果を表示したりするなど、繰り返し行うリサーチで一貫した動作が必要な場合にSkillsを使用してください。
TypeScript機能を追加する
TypeScript機能を使うと、開発者は拡張機能に新しい機能を追加できます。エージェントツール、ツール結果のレンダラー、設定ページ、パネルビュー、モデルプロバイダーを提供できます。
始めるには、プロジェクトの機能サンプルをsrc/capabilities/にコピーし、登録名を変更して、機能に必要な貢献だけを残します。最小構成のエントリーファイルでは、次のようにツールとレンダラーをエクスポートできます。
// src/capabilities/<your-feature>/index.ts
export { default as tools } from "./tools.js";
export { default as renderers } from "./renderers.js";ビルドはこれらの宣言を自動的に検出します。ツールハンドラーはバックグラウンドサービスワーカーで実行され、アクティブなタブにアクションやスクリプト実行を委任できます。レンダラーはサイドパネルにインタラクティブな結果カードを表示します。
SDKの詳細と現在の拡張機能コントラクトについては、Capabilityガイドとプロジェクトのコントリビューター向けドキュメントを参照してください。これらのAPIは実験的なものなので、拡張機能を構築する際は変更の可能性を考慮してください。
開発ワークフロー
コマンドとビルドオプションのドキュメントに従って、プロジェクトのテスト環境をセットアップしてください。主な開発コマンドは次のとおりです。
npm run dev # ソース変更時に再ビルド
npm test # デフォルトのテストスイートを実行
npm run verify # 型チェックとカバレッジ付きの自動テストスイートを実行再ビルド後、chrome://extensionsから拡張機能を再読み込みし、qzサイドパネルを開き直してください。これにより、Chromeで最新の生成済み拡張機能ファイルが実行されます。
高度な使用方法のヒント
- 構造化されたプロンプトを使用する: 対象ページ、収集するフィールド、希望する出力形式を説明し、抽出データを有用なコレクションとして整理できるようにします。
- 適切な操作モードを選択する: DOMベースの操作はページ要素やフォームに便利です。一方、スクリーンショットベースの操作は、視覚的なコンテキストが重要な場合に役立ちます。
- 繰り返し可能なワークフローを分離する: 繰り返し使用する指示やスクリプトは、すべてのプロンプトに記述する代わりにSkillsにまとめます。
- 並列処理は慎重に使用する: 独立した調査タスクを同時に委任し、その後サイドパネルで統合された結果を確認します。
- 適切な場合はローカルサービスを優先する: qzはローカルモデルサーバーをサポートしているため、モデルとの通信を管理下のインフラ内に維持できます。
- データ接続を確認する: ページのコンテンツ、ファイル、Skills、MCP統合は、リクエストに含められたり、設定済みのサービスと交換されたりする可能性があります。機密情報を扱う前に権限を確認してください。
- ソース変更後は再読み込みする: ビルドが成功しても拡張機能は自動的に更新されません。テスト前にChromeで再読み込みしてください。
任意のMCP統合
任意で使用できるローカルMCPブリッジは、ブラウザツールとタスク制御機能を外部エージェントに公開します。別のMCP互換エージェントやアプリケーションからqzを制御する必要がある場合に使用してください。MCP接続は設定済みのサービスとデータを交換する可能性があるため、有効化する前にブリッジのドキュメントとデータフローへの影響を確認してください。
まとめ
qz-browser-agentは、Chromeサイドパネル、モデル駆動型のブラウザ自動化、構造化されたローカルコレクション、並列サブタスク、そしてSkillsとTypeScriptによる拡張性を組み合わせています。手早く始めるにはリリース版をインストールし、互換性のあるモデルプロバイダーを設定して、対象を絞った抽出プロンプトを試してください。カスタムワークフローや統合が必要な場合は、ソースからビルドし、Skills、capabilities、または任意のMCPブリッジでプロジェクトを拡張してください。