agent-browser

概要

agent-browser とは？

agent-browser は、inference.sh プラットフォーム上で動作する AI エージェント向けに設計されたブラウザ自動化スキルです。内部では Playwright を利用しつつ、シンプルな JSON ベースのインターフェースを提供することで、エージェントが次のような操作を行えるようにします。

• 実ブラウザで Web ページを開いて遷移する
• 安定した @e リファレンスを使って要素を操作する
• クリック、文字入力、ドラッグ＆ドロップ、ファイルアップロードを行う
• スクレイピングやリサーチ用に構造化データを抽出する
• セッションのスクリーンショットや動画を取得する

Playwright のコードを手書きする代わりに、infsh CLI（または Bash コマンドを実行できるエージェント）から agent-browser を呼び出します。このスキルがブラウザセッションを管理し、ページの機械可読な記述を返し、エージェントがステップごとに操作を進められるようにします。

agent-browser は誰向け？

agent-browser は次のようなユーザーを想定しています。

• 実際の Web サイトに AI エージェントを接続したい 開発者
• 再現性のあるブラウザワークフローが必要な オートメーションエンジニア
• ターゲットを絞った Web スクレイピングや UI ベースの調査を行う データ／リサーチチーム
• inference.sh をオーケストレーションレイヤーとして使う ワークフロービルダー

すでに inference.sh を利用している、または利用を検討しており、ブラウザをエージェントから制御可能なツールとして扱いたい場合に特に適しています。

どんな課題を解決できる？

agent-browser は、典型的なブラウザ自動化タスクを効率よく処理するのに役立ちます。

• ログイン、ナビゲーション、フォーム送信などのワークフロー自動化
• 検索フォーム、フィルタ、ページネーションなどの操作が必要な構造化コンテンツのスクレイピング
• 本番サイトに対するエージェント主導の「テスト風」フローの実行
• 自動ブラウジングセッションの動画記録とレビュー

Playwright のスクリプトを直接書く代わりに、@e 要素リファレンスを用いた高レベルのアクションセットをエージェントに提供することで、複数ステップにまたがる安定した操作を実現します。

agent-browser が向いているケースは？

次のような場合に agent-browser の利用が適しています。

• inference.sh 経由でエージェントを動かしており、そのエージェントに Web を閲覧させたい
• Playwright の信頼性は欲しいが、Playwright のコードは書きたくない
• ページを開き、要素を操作し、結果を読み取るという流れが中心のフローである

一方で、次のような場合は 向いていない可能性があります。

• infsh CLI や Bash ライクなツールを利用できない
• スキルが公開している範囲を超える、非常にカスタムな Playwright 機能が必要
• そもそもブラウザを必要とせず、API ベースだけで完結するユースケース

ブラウザ内部や特定フレームワークをきめ細かく制御したい場合は、Playwright を直接使ったスクリプトの方が適しているかもしれません。一般的なエージェント主導の自動化であれば、agent-browser がよりシンプルで高レベルなインターフェースを提供します。

使い方

前提条件

agent-browser を使う前に、以下を準備してください。

• Bash コマンドを実行できる環境
• inference.sh CLI（infsh）のインストール
• CLI からログイン可能な inference.sh アカウント

このスキルのクイックスタートでは infsh CLI が必須です。リポジトリの公式手順に従ってインストールしてください。

• CLI インストールドキュメント: https://raw.githubusercontent.com/inference-sh/skills/refs/heads/main/cli-install.md

infsh をインストールし設定を済ませたら、ターミナルから、または infsh コマンドを実行できる任意のエージェントツールから agent-browser スキルを呼び出せます。

インストールとスキルの有効化

agent-browser は inferen-sh/skills リポジトリの一部として提供されています。多くの inference.sh ベースの環境では、個別に npm パッケージをインストールする必要はなく、スキルが利用可能であることを確認したうえで infsh 経由で呼び出すだけで使えます。

一般的なセットアップ手順は次のとおりです。

1. inference.sh CLI をインストール
   • リポジトリの cli-install.md に従ってセットアップします。
2. 認証
   • 次を実行します。

     infsh login
     

   • プロンプトに従って inference.sh へのログインを行います。
3. スキルの利用可否を確認
   • inferen-sh/skills リポジトリ内の tools/utilities/agent-browser にある agent-browser アプリ／スキルに、利用中の inference.sh 環境からアクセスできることを確認します。

より広い「skills」エコシステムと統合しており npx skills add をサポートしている場合は、このリポジトリをソースとして接続することも可能です。ただし、agent-browser の正規の利用フローは infsh app run を通じた実行です。

基本的なブラウザ自動化ワークフロー

スキルのドキュメントでは、一貫した 4 ステップパターンが紹介されています。

1. Open – ブラウザセッションを開始し、指定した URL に移動する。
2. Interact – 返却された @e 要素リファレンスを使ってクリック・入力・ドラッグ・アップロードを行う。
3. Re-snapshot – ナビゲーションや DOM 更新後に、新しい @e リファレンスを取得するため再スナップショットを要求する。
4. Close – セッションを終了し、レコーディングを有効にしていれば動画を取得する。

このパターンにより、エージェントはページ状態の「メンタルモデル」を維持できます。各呼び出しでは JSON 入力を渡し、構造化された JSON 出力を受け取り、それをエージェントの推論ループに渡していきます。

クイックスタート例

シンプルに 1 ページを開く例で agent-browser の動作を確認するには、リポジトリのクイックスタートパターンに従います。

infsh login

# ページを開き、操作可能な要素を取得
infsh app run agent-browser --function open --input '{"url": "https://example.com"}' --session new

このコマンドの意味:

• --function open は、指定した URL で新しいブラウザページを開くよう agent-browser に指示します。
• --session new は新規セッションを作成し、後続のアクションで同じブラウザ状態を再利用できるようにします。
• スキルは、要素の説明やエージェントが後続の interact 呼び出しで利用できる @e リファレンスを含む JSON を返します。

@e 要素リファレンスの扱い

agent-browser の中核機能が @e リファレンスです。CSS セレクタや XPath を指定させる代わりに、@e:button-1 のようなハンドル（正確な形式は実装に依存）と、人間が読める説明文をセットで返します。

エージェントは次のように動作します。

1. 利用可能な要素リストと、その説明を読み取る。
2. 目的に合う @e リファレンス（例: 「Search」とラベル付けされたボタン）を選択する。
3. 選択した @e を使って click や fill などのインタラクション関数を呼び出す。

この設計は、低レベルな DOM 詳細ではなく説明文をもとに推論する AI エージェントに最適化されています。また、説明が解釈可能である限り、内部のセレクタが変更されても操作が比較的壊れにくくなります。

例: open、click、そして resnapshot

典型的なマルチステップフローは次のようになります（あくまでパターン例なので、実際の関数名は環境に合わせて調整してください）。

# 1. セッションを開始してページを開く
OPEN_RESULT=$(infsh app run agent-browser \
  --function open \
  --session new \
  --input '{"url": "https://example.com"}')

# 2. エージェント側のロジックで OPEN_RESULT から @e リファレンス（例: @e:search-button）を選ぶ
# 3. 選んだ要素を操作
INTERACT_RESULT=$(infsh app run agent-browser \
  --function interact \
  --session "$INF_SH_SESSION" \
  --input '{"action": "click", "element": "@e:search-button"}')

# 4. click 後に再スナップショットを取得し、更新された要素を取得
SNAPSHOT_RESULT=$(infsh app run agent-browser \
  --function snapshot \
  --session "$INF_SH_SESSION" \
  --input '{}')

open 以外の関数名は実装によって異なる可能性があるため、常に最新の SKILL.md と tools/utilities/agent-browser 内のドキュメントを確認し、正確な関数シグネチャや入力スキーマを参照してください。

スクリーンショットと動画録画

agent-browser はブラウジングセッションのビジュアルを取得できます。

• スクリーンショット – エージェントの動作をデバッグしたり、画面状態の証跡を残したいときに便利です。
• 動画 – 録画を有効にした状態でセッションを終了すると、自動化フロー全体の動画ファイルを返却または参照リンクとして取得できます。

これらはスキルの入力オプションで設定します。録画の有効化方法や出力へのアクセス手順については、リポジトリ内の SKILL.md および tools/utilities/agent-browser 配下の追加ドキュメントを参照してください。

エージェント／ワークフロー統合のポイント

agent-browser を自動化やリサーチのワークフローで最大限活用するためのヒント:

• --session ID を保持する: 複数のアクションを同一ブラウザで実行するため、エージェント側でセッション ID を呼び出し間で保存してください。
• JSON 出力を厳密にパースする: 要素リストやメタデータはリッチになる可能性があるため、エージェント側ランタイムでは堅牢な JSON パース処理を行いましょう。
• 必要に応じて操作をスロットルする: ページが重い・動的な場合は、スキル側の設定で可能な範囲で待機を入れるなど、ステップ間で要素が出現するまで時間を考慮してください。
• 主要な操作をログに残す: open、interact、close の呼び出しログを残しておくと、エージェントのブラウジング挙動を監査・デバッグしやすくなります。

FAQ

agent-browser、inference.sh、Playwright の関係は？

agent-browser は inference.sh エコシステム内で動作するスキルです。infsh app run 経由で呼び出されると、内部で Playwright をブラウザ自動化エンジンとして利用します。Playwright を直接呼び出すのではなく、より高レベルなスキル関数と @e 要素リファレンスを通じて操作します。

agent-browser のインストール方法は？

agent-browser を単体のバイナリや npm パッケージとしてインストールする必要はありません。代わりに、次のステップを実行します。

1. 公式の cli-install.md に従って inference.sh CLI（infsh）をインストールします。
2. infsh login でログインします。
3. 利用環境から inferen-sh/skills リポジトリ内の tools/utilities/agent-browser 配下にある agent-browser スキルへアクセスできることを確認します。

この準備ができたら、すぐに infsh app run agent-browser でスキルを呼び出せます。

agent-browser の利用にプログラミング経験は必要？

基本的なコマンドライン操作と JSON の扱いには慣れていることをおすすめします。Playwright のスクリプトを書く必要はありませんが、次の点には慣れているとよいでしょう。

• infsh コマンドの実行
• --input に JSON を渡す
• エージェントやスクリプト側で JSON 出力をパースする

条件分岐やループ、エラーハンドリングなどを含む高度なワークフローを組む場合は、一般的なスクリプト／プログラミングの知識があると便利です。

inference.sh 以外の環境で agent-browser を使える？

このスキルは inference.sh 向けに特化しており、“Browser automation for AI agents via inference.sh” として設計されています。サポートされている実行方法は infsh CLI を通じた利用です。スタンドアロンのライブラリが必要な場合は、利用している言語で Playwright を直接使う方が適しているかもしれません。

agent-browser は大規模な Web スクレイピングにも向いている？

agent-browser は、特にインタラクションや JavaScript レンダリングが必要なページに対するターゲットを絞ったスクレイピングに利用できます。ただし、非常に大規模なスクレイピングを行う場合は、次の点を検討してください。

• inference.sh アカウントの制限や料金体系
• 対象サイトの利用規約や robots.txt への準拠
• パフォーマンス、並列実行数、レートリミット

エージェント内に組み込まれた小〜中規模、もしくは特定ワークフロー向けのスクレイピングであれば agent-browser は有力な選択肢です。一方、多数のサイトを横断するような大規模クローリングには、専用のスクレイピングスタックを検討した方がよい場合もあります。

セッション管理はどのように行う？

セッション管理は infsh app run 呼び出し時の --session フラグで制御します。一般的なパターンは次のとおりです。

• 初回に open を呼び出すときは --session new を指定
• その後の interact や snapshot 呼び出しでは、同じセッション ID を再利用
• セッション終了時に適切な close 関数を呼び出し、必要であれば動画を取得

セッション管理に関する具体的なオプションや出力内容については、常に最新の SKILL.md を参照してください。

利用可能な関数や入力仕様の完全なリファレンスはどこにある？

agent-browser の正確な仕様は、次のリポジトリ内ファイルに掲載されています。

• inferen-sh/skills リポジトリ直下の SKILL.md
• 実装詳細、サンプル、追加ドキュメントを含む tools/utilities/agent-browser ディレクトリ

これらのファイルを参照し、利用可能な関数一覧、期待される JSON 入力、出力フォーマットを確認したうえで、エージェントやスクリプトを設計してください。