#🦜 HuBrowser agent: 技術詳細 🛠️

HuBrowser は、モジュール型で拡張しやすい設計によって、堅牢で賢いブラウザー自動化を実現しています。ここでは、そのアーキテクチャ、状態管理、インテリジェンス、そして独自の技術的解決策をまとめます。

#🚀 概要とアーキテクチャ

• 柔軟な自動化: 自然言語、録画した操作、コードを組み合わせて、状況に応じた制御を実現します。
• 高度なタスク分解: 複雑な作業を扱いやすいサブタスクへ分解し、適切なツールを賢く選びます。
• 包括的なツールセット: ブラウザー、ファイル、コマンドライン、API、データ分析機能を統合しています。
• リアルタイムフィードバック: タスク実行中の中間結果を追跡し、その場で変更できます。
• モジュール型で拡張しやすい設計: 信頼性、透明性、拡張のしやすさを重視しています。

#コアワークフロー

HuBrowser は連続ループで動作します。

1. 初期化: タスク、LLM、ブラウザーインスタンスを使ってエージェントを作成し、すべてのコンポーネントをテレメトリー付きで初期化します。
2. 実行ループ: 状態取得 → LLM 分析 → アクション実行 → 状態更新。
3. 完了: タスク完了時にイベントを記録し、履歴を返し、必要に応じて GIF を生成します。

#システムコンポーネント

• Agent: タスクの計画と実行、状態と履歴の管理、LLM とのメッセージやエラー処理を担当します。
• Controller: ブラウザー操作を登録し、パラメータを検証し、LLM の指示を実際のブラウザー操作へつなぎます。
• Browser: ブラウザーインスタンス、コンテキスト、タブ、ナビゲーション、DOM 操作を管理します。
• DomService: DOM ツリーを構築し、操作可能な要素を特定し、履歴や viewport 情報を追跡します。
• バックグラウンドプロセス（仮想サンドボックス）: 自動化タスクを隔離環境で実行し、ユーザーの通常の閲覧体験を邪魔しないようにします。

#🔍 メモリ管理

• エージェントは過去の操作を持続的に記憶しながら動作します。そのため、以前のやり取りから得た文脈を使って、次のステップでよりよい判断ができます。たとえば、ボタンを押して新しいページへ移動したあと、データ抽出時に「自分がその遷移を起こした」ことを覚えていられます。
• 履歴データを「メモリ」として扱うことで、ステップ間で明示的な変数受け渡しを手作業で行うよりも、ずっと簡潔かつ堅牢に自動化を構築できます。複雑なワークフローでは、この差がとても大きくなります。
• アプリケーション状態: 開いているタブ、フォーム入力値、認証 Cookie。
• 個人設定: 暗黙のシグナルから学習します。
• 閲覧履歴: Sentence-BERT embeddings によって意味ベースで想起できる形にエンコードされます。

この仕組みによって、エージェントが自分の行動文脈を本当に「理解」したうえで動く、より複雑で動的な自動化シナリオを構築できます。

#基本プロパティ

• context_evaluation: アクション後の結果分析と次の調整計画。
• memory: 進捗と重要情報の持続保存。
• short_term_goal: 直近で達成すべき目標。
• long_term_goal: 一連の流れ全体を導く最終目標。

#圧縮メモリ

• 完了した各ステップを要約: クリック、データ抽出、ページ移動など、各アクションのたびに「今起きたこと」を短く要約します。たとえば次のような内容です。
  • "Navigate: amazon.com."
  • "Input text: 'parrot toy' into field 'Search Query'."
  • "Query: 'Product Name' as 'Parrot Toy', 'Price' as '$22'."
  • "Tap: on the 'Submit' button."
• 後続ステップで再利用: こうした要約は現在の自動化実行のあいだ保持され、後の判断やアクションの材料として使われます。

HuBrowser は状態を 2 つの層で管理します。

1. マルチタブオーケストレーション: 複雑なワークフローに向けて、ブラウザーインスタンス、コンテキスト、ページを管理します。
2. タブ単位のコンテキスト: ページ要素の情報を解析・抽出し、正確に対象を絞ります。
   • 空テキスト、script、SVG など不要ノードを除外し、一意な XPath 識別子を付与します。
   • ARIA ロール、イベントリスナー、content-editable などから操作可能要素を検出します。
   • Cookie バナーや同意ダイアログも扱います。
   • JavaScript のフラットマップを Python のオブジェクトネットワークへ変換します。

#📄 ページと DOM の処理

HuBrowser は、複雑な Web 構造を、構造化テキストと番号付きスクリーンショットによって LLM が理解しやすい説明へ変換します。ページ情報は 1 回限りのデータとして扱い、各リクエスト後にクリアすることで、モデルの文脈効率を保ちます。

#DOM ツリー解析

• 可視要素、操作可能要素、最前面要素を識別します。
• ARIA、イベント、content-editable などを組み合わせた多層的なインタラクティブ判定を行います。
• 高性能なハイライトオーバーレイで要素をマーキングします。
• ボタン、テキストノード、画像、フォーム、コンテナなど、操作価値の高い要素に注力します。
• フィルタリング: 5px 未満の要素、たとえばトラッキングピクセルや、画面サイズより大きい要素を無視します。
• 抽出: ID、ハッシュ、locator を含む統一 WebElementInfo を生成します。
• タグ処理: 多くの要素では親タグを使い、フォームには特別な処理を行います。
• ツリー操作: 構造化ツリーへ変換するためのアルゴリズムを適用します。

要素プロパティの例:

{
	"tagName": "a",
	"attributes": {},
	"xpath": "html/body/div/a[2]",
	"children": ["idx_459"],
	"isVisible": true,
	"isTopElement": true,
	"isInteractive": true,
	"isInViewport": true,
	"highlightIndex": 5,
	"elementId": "element_123",
	"indexId": "idx_456",
	"nodeHashId": "hash_789",
	"content": "HuBrowsing",
	"position": { "x": 100, "y": 200, "width": 60, "height": 30 },
	"centerCoordinates": { "x": 150, "y": 225 },
	"zoomLevel": 1.0,
	"screenDimensions": { "width": 1920, "height": 1080 }
}

#スクリーンショット処理

• DPR（Device Pixel Ratio）に応じた解像度対応: 高解像度画面、DPR > 1 に合わせてスクリーンショットを調整し、ピクセル単位で正確な要素位置を保ちます。
• 要素マーキング: LLM が識別しやすいように、操作可能要素へマーカーや枠線を追加し、行動可能な UI 手掛かりを与えます。

#ユーザー意図の認識

• マウスやタッチの動きのパターンを分析してユーザーの関心を推定し、どこを優先的に処理するか決め、応答も調整します。
• 各要素に対して意味的意図にもとづく相互作用可能性を強調し、必要なら色分け表示も行えます。これにより、エージェントはもっとも重要な情報やアクションへ集中できます。

#🧠 エージェントの知能とツール統合

#ツール統合とアクション登録

• JSON Schema 検証付きの構造化 function calling により、正確な実行を実現します。
• 同期処理・非同期処理の両方に柔軟に対応できる登録方式です。

#🧅 マルチレイヤー文脈システム

HuBrowser はタスクの複雑さと LLM の必要性に応じて文脈レイヤーを選び、性能と精度のバランスを取ります。

• テキスト内容: 画面上の可視テキストを抽出。
• HTML メタデータ: title や meta tags。
• viewport スクリーンショット: 現在見えている領域。
• ページサムネイル: 低解像度プレビュー。
• フルページスクリーンショット: ページ全体の視覚スナップショット。
• 平坦化 HTML ツリー: 主要プロパティを持つ構造化 DOM。
• 完全 HTML ツリー: 深い調査向けの完全 DOM。
• Web API データ: 詳細タスク向けの構造化データ。

#🎯 対象計画と実行

#計画手法

1. パラメータ構築: 要素文脈を含む詳細な探索パラメータを作ります。
2. プラン作成: フォールバック戦略込みの包括的な操作プランを生成します。
3. タスク実行: プランを実行可能なタスクへ変換します。

AI Assist の応答:

• テキストモデル: 要素 ID と、その理由づけ。
• 視覚モデル: バウンディングボックス座標。

#アクション方式と文脈管理

• 要約済み履歴とともに、単一のユーザーメッセージを保持します。
• 一般的なモデルには DOM ツリーや要素詳細を含む包括的なページ説明を渡します。
• 視覚モデルでは DOM 情報を除外し、オーバーヘッドを抑えます。
• 結果予測付きの詳細なアクションプランを生成します。
• 実行ログとエラー情報を保持します。
• 実行前に結果を予測し、先回りしてエラー対応します。
• 最大 4 枚のスクリーンショット付きでメッセージ履歴を保持します。
• ユーザー指示をシステムプロンプトへ直接組み込みます。
• 以前の AI 応答も含めて文脈の連続性を保ちます。
• 高度な機能:
  • アクション分解: 複雑な指示を個別の操作へ分けます。
  • 要素探索の最適化: 既に見つけた ID、class、座標を再利用してモデル呼び出しを減らします。
  • 文脈効率: 履歴量と性能のバランスを取ります。

#🧩 技術的課題と解決策

HuBrowser は、現実の Web 自動化で起こる課題に対して高度な解決策を用意しています。

• 🖼️ iframe 処理: ネストした iframe の再帰走査と cross-origin 対応。
• 🛡️ CSP 制限: content security policy によるブロックを回避・緩和する複数戦略。
• 🌑 Shadow DOM: 分離コンポーネントを扱う高度な走査。
• 🧩 拡張機能の自動化: ブラウザー拡張とのネイティブな相互作用。
• 🔗 コンテキスト間メッセージング: ページや拡張機能をまたぐシームレスな通信。
• ⏱️ スクリプト注入のタイミング: 信頼性の高い自動化のための精密なタイミング制御。
• 📝 非標準 HTML: 構造の悪いドキュメントでも頑丈に抽出。
• 🎯 要素精度: 正確に狙うための高度なフィルタリングと探索。