browser-intent

ブラウザーインテント

低レベルの browser_* セレクターツールの上に構築された自然言語レイヤーです。browser-extract と browser-form-fill がセレクターベースのプリミティブ（browser_click、browser_fill、browser_snapshot）を組み合わせるのに対し、browser-intent では呼び出し側が希望する操作（「ログインボタンをクリック」「検索ボックスに猫と入力して送信」など）を伝えるだけで、page-agent に実行を委任できます。page-agent はページ内に挿入される JS で、DOM をテキストに変換し、それに対する LLM のツール呼び出しループを実行します。

使用する場面

• 対象の要素を確実に選択するより、言葉で説明するほうが簡単な場合（動的なクラス名、曖昧な構造、A/B テストされたマークアップなど）。
• セレクターの連鎖を書くほどではない、単発の操作。
• 正確なセレクターまたは ref（@e1）がすでにわかっている場合は、browser_click ／ browser_fill ／ browser_snapshot を直接使ってください。browser_act には LLM の遅延とコストが追加されますが、セレクターを直接指定する呼び出しでは発生しません。

手順

1. browser_act を呼び出し、task 文字列と、必要に応じて url（最初に移動）および session（デフォルトは "default"）を指定します。

   mcp__plugin_ruflo-core_ruflo__browser_act({
     task: "Click the login button",
     url: "https://example.com/account",
     session: "my-session"
   })
   

2. レスポンスの仕様を確認します。
   • { success: true, result, steps, history, contentFlagged, llmSource } — インテントが実行されました。result は AIDefence によるゲート処理後の最終テキストで、page-agent が生成したものです。history は手順全体のトレース（各手順の内省＋アクション＋ツール結果）で、steps は history.length です。
   • { success: true, degraded: true, reason, hint } — page-agent がインストールされていないか、OpenAI 互換の LLM プロバイダーが設定されていません。degraded: true を再試行が必要なエラーとして扱わないでください。hint を表示し、代わりにセレクターベースの browser_* ツールを使ってください。
   • { success: false, error, ... } — 実際の失敗です（ブラウザーを開けなかった、挿入に失敗した、実行がタイムアウトした、または page-agent 自身の execute() が success:false を報告した場合）。
3. contentFlagged: true の場合、返された result はすでに AIDefence によって編集されています（page-agent の出力から PII またはプロンプトインジェクション／脅威のパターンが検出されました）。元のテキストを復元しようとしないでください。
4. 操作を後で再生することが重要な場合は、記録済みのセッション（browser-record）を優先してください。browser_act 自体は RVF コンテナを開かず、指定されたセッション ID（または "default"）を使用します。

プロバイダーの要件（頻繁に縮退する理由）

page-agent はブラウザーページのコンテキストから、プレーンな OpenAI 互換の POST {baseURL}/chat/completions を使って LLM を直接呼び出します。そのため、次の点に注意してください。

• ANTHROPIC_API_KEY だけでは不十分です。Anthropic のネイティブ API は別の形式（/v1/messages）です。
• 次のいずれかを設定してください。OPENROUTER_API_KEY（OpenRouter、OpenAI 互換）、OLLAMA_API_KEY（Ollama Cloud、OpenAI 互換）、またはカスタムの OpenAI 互換エンドポイント用の CLAUDE_FLOW_PAGE_AGENT_BASE_URL と CLAUDE_FLOW_PAGE_AGENT_API_KEY。
• 実際のプロバイダーキーがページに渡されることは決してありません。browser_act はキーをサーバー側に保持する短時間のループバック HTTP プロキシを起動し、実際の Authorization ヘッダーを自身で挿入します。ページから見えるのは 127.0.0.1 の URL とプレースホルダーのキー文字列だけです。

注意事項

• page-agent は optionalDependencies のエントリーです（doctor/degraded ヒントで必要とされた場合は npm i page-agent を実行してください）。このプラグインは page-agent がなくても完全に動作しますが、自然言語レイヤーが使えなくなり、セレクター方式のツールに切り替わります。
• npm バンドルに含まれるデモの自動初期化用末尾コード（そのままでは Alibaba の公開テストエンドポイントに対して 2 つ目の PageAgent インスタンスを構築します）は、注入前に取り除かれます。このツールから page-ag-testing-* ホストへのトラフィックが発生することはありません。
• 成功した browser_act の呼び出しは毎回、意図とその結果の軌跡をベストエフォートで browser メモリ名前空間に記録します（ADR-174 の蒸留ループ）。これはファイア・アンド・フォーゲット方式です。メモリストアでエラーが発生しても、ツールの呼び出しが失敗することはありません。
• timeoutMs（デフォルトは 120000）は、browser_act が execute() の完了を待つポーリング時間の上限です。複数ステップからなる処理に時間がかかる場合は、より大きな値が必要になることがあります。