sap-browser-automation

SAP Browser Automation

このスキルは、SAP 固有のスキルで共通のブラウザレイヤーとして使用します。ブラウザサーフェスの選択、認証の初期設定、分離された Edge/CDP の起動、状態の再利用、対象の確認、証跡、復旧、クリーンアップを担います。利用する側のスキルは、引き続き SAP 操作の範囲を管理します。これには、ストーリーの編集、プランニングの書き戻し、モデルの変更、Datasphere のデプロイ、SQL の実行、テストの受け入れが含まれます。

関連スキル

• sap-sac-scripting：SAC のストーリー／ランタイムスクリプト作成とレポートストーリーの実装。
• sap-sac-test-automation：SAC の受け入れ、探索パケット、Playwright スイート、証跡。
• sap-sac-planning：SAC のプランニングモデル、書き戻し、バージョン、データアクション、ロック。
• sap-datasphere：Datasphere のモデリング、デプロイ、スペース、接続、管理。
• browser:control-in-app-browser：インストール済みのアプリ内ブラウザーランタイムと安全な手動認証。

このスキルを使用する場面

エージェントが認証済みの SAP Web UI を操作する場合、ブラウザーの対象を選択または確認する場合、ループバック CDP で Edge を起動する場合、承認済みの Edge プロファイルを再利用する場合、スコープを限定したブラウザー状態をインストール済みの互換クライアントに転送する場合、またはブラウザーの初期設定／認証の失敗から復旧する場合は、必ずこのスキルを使用してください。表示可能なブラウザー状態を必要としない、コードのみ、API のみ、CLI のみ、またはデータベースネイティブのタスクには使用しないでください。

クイックリファレンス

必要なこと	方法
現在のブラウザーで手動 SSO を行う	アプリ内ブラウザーを使用し、サインイン済みであることを画面上で確認する
エンタープライズ Edge を使用する、または Playwright がインストールされていない	プロファイルをコピーし、ループバック CDP を使用して、新しい分離 Edge を起動する
独立した互換ブラウザーコンテキストを使用する	既存の Playwright と、スコープを限定した storageState または CDP による状態転送を使用する
認証情報が不足している、またはブラウザーの初期設定に失敗した	ユーザーにログインを依頼する、復旧する、または仕様のみを引き継ぐ

要求されたブラウザーと接続方法は必ず守ってください

ユーザーが Chrome、Edge、Chrome DevTools MCP、CDP、またはローカル DevTools ブリッジを指定した場合は、そのブラウザーと接続方法だけを使用してください。アプリ内ブラウザー、ChatGPT ブラウザー拡張機能、Playwright、Computer Use、別のブラウザー、シェル自動化に勝手に切り替えないでください。要求されたサーフェスを利用できない場合は、具体的な阻害要因を報告し、その時点で停止してください。

運用上の契約

• ブラウザーを使わずに要求に答えられる場合は、コネクター、API、CLI、またはデータベースネイティブの確認を優先します。
• ユーザーが別のブラウザーや接続方法を指定していない場合に限り、まずアプリ内ブラウザーを使用します。
• アプリ内ブラウザーの接続先が SSO にリダイレクトされた場合は、ユーザーにアプリ内ブラウザーで手動認証するよう依頼します。安全な認証機能を使用し、チャットでパスワードや OTP を尋ねてはいけません。
• アプリ内での確認後、CDP、エンタープライズ拡張機能、または再利用可能なプロファイルが必要なタスクでは、確実な自動化のために新規の Edge 環境を使用します。
• MCP の設定と MCP の利用可能性は別々に確認します。設定後、アクティブなツールレジストリにサーバーツールが存在することを確認します。codex mcp get の確認に成功しただけでは、MCP を利用できるとは限りません。
• list_pages などでライブハンドシェイクを行い、返されたページが要求されたブラウザーのものであることを確認します。設定後にツールが見つからない場合は、続行する前に Codex を再起動するか、新しいタスクを開くようユーザーに依頼します。
• ユーザーの認証済み通常版 Edge プロファイルを再利用する場合、または Edge を閉じる場合は、事前に明示的な許可を求めます。
• Edge を閉じてからのみコピーし、隔離されたプロファイルパスにコピーします。コピー、Cookie、トークン、ローカルストレージ、ストレージ状態ファイルは認証情報として扱います。
• CDP は 127.0.0.1 にバインドし、ポート、WebSocket エンドポイント、プロファイル、認証状態をネットワーク、リポジトリ、ログ、スクリーンショット、Oracle のレビューに決して公開しません。
• 操作の前に、テナント、ホスト、パス、タイトル、認証済み DOM、対象ページを確認します。最初のタブや対象 ID を推測してはいけません。
• 既定では読み取り専用の操作を行います。利用する SAP スキルが、書き込み、公開、デプロイ、計画、モデル、権限、破壊的な操作を明示的に許可する必要があります。
• ブラウザーの起動、CDP 接続、ログインリダイレクトの成功は、要求された SAP タスクが完了した証拠にはなりません。

必要な場合にのみ、目的に沿ったリファレンスを読み込みます。

• Edge の起動、CDP の検出、対象の選択、復旧については references/edge-cdp-control.md を参照します。
• 認証済み Edge プロファイルのコピー、利用可能な場合のスコープ付き状態のエクスポート、対応クライアントへの注入については references/auth-state-bootstrap.md を参照します。
• アプリ内での手動認証と機能の制限については references/in-app-browser-auth.md を参照します。
• 決定的なプロファイルの複製、起動、状態確認、停止の操作には scripts/edge-profile.ps1 を実行します。
• 対象の検出、調査、操作、スクリーンショットの取得、認証状態の転送には scripts/cdp-agent.mjs を実行します。Node.js 22 以降が必要で、npm パッケージは不要です。

標準ワークフロー

1. タスクを分類して操作環境を選択する

対象アプリケーション、テナント／ホスト、要求された URL、読み取り／書き込みの意図、必要な証拠、プロファイル再利用についてユーザーの承認を得ているかを記録します。次の順序で使用します。

1. 要件を満たす既存の非ブラウザーツール。
2. アクティブなツールとライブハンドシェイクを確認したうえで、明示的に要求されたブラウザーと接続方法。
3. 他のブラウザーや接続方法が要求されていない場合、認証済み UI の表示と手動 SSO にアプリ内ブラウザーを使用。
4. エンタープライズブラウザーの動作と再利用可能な認証には、ループバック CDP を使用する新規の隔離された Edge 環境。
5. すでにインストールされている Playwright を CDP 経由、またはローカルストレージ状態を使って接続。
6. 承認済みのデスクトップ／手動支援、または仕様のみを引き継ぐ方法。

ユーザーが変更を明示的に要求して承認しない限り、エンタープライズ環境に Playwright、ブラウザーバイナリ、MCP サーバー、拡張機能をインストールしてはいけません。Playwright を利用できない場合も、Edge／CDP を主要な自動化環境として使用します。

2. アプリ内ブラウザーで認証する

ほかのブラウザーや接続が指定されていない場合は、インストール済みの Browser スキルを使用して対象を開きます。 表示されている状態を確認します。ページで SSO が必要な場合は、サポートされている安全な認証フローを通じて ユーザーが手動でログインを完了するまで待ちます。対象ドメインでログイン済みであることを示す明確なシグナルを確認し、 許可されている場合はスクリーンショット、または同等の証拠を保持します。

アプリ内ブラウザーから Cookie、ローカルストレージ、セッションストレージ、プロファイルデータベース、パスワード、 トークンを抽出しないでください。アプリ内ブラウザーのセッションは Edge とは独立しています。手動ログイン後も認証済みページを 表示できない場合は、失敗を記録して、承認済みの Edge の手順に進みます。

この手順は Codex または Claude Desktop 内で実行されます。実行時の検証はこれらのデスクトップ環境で行い、 スタンドアロンの Edge／CDP 受け入れテストには含めません。

3. 現在の Edge の状態を取得してから、新しい Edge を起動する

ユーザーの通常の Edge プロファイルを操作する前に、実施する範囲を伝えて確認を求めます。

現在認証済みの Edge の対象から、承認済みの SAP セッションを取得し、通常の Edge を閉じて、選択したプロファイルを分離された自動化用ディレクトリに複製します。続行してもよろしいですか？

ユーザーが拒否した場合は、分離されたプロファイルで一度ログインするよう依頼します。承認された場合は、次の手順を実行します。

1. 通常の Edge のユーザーデータのルート、選択された Default または Profile N、対象 URL、テナントホスト、 対象パス／タイトル、承認済み SAP オリジン、一時的な状態ファイルのローカルパスを特定します。
2. 通常の Edge がまだ実行中で、認証済みであることが画面上で確認できる状態で、edge://inspect/#remote-debugging を開き、 このブラウザーインスタンスでリモートデバッグを許可するを有効にします。
3. 通常のユーザーデータディレクトリに対して scripts/cdp-agent.mjs export-auth を実行します。承認済みページを正確に1件に 特定できるホスト、パス、タイトルのフィルターを指定します。承認済みの SAP または ID プロバイダーの Cookie の範囲ごとに --origin を繰り返し指定します。
4. 通常の Edge を閉じ、ソースプロファイルを使用している msedge.exe プロセスが残っていないことを確認します。
5. 選択したプロファイル名と、新しいか空の自動化ルートを指定して、scripts/edge-profile.ps1 -Action CloneLaunch を実行します。 このヘルパーは Profile N を保持し、空でない複製先を拒否し、--remote-debugging-port=0 を指定して起動し、 DevToolsActivePort から検出したリスナーを検証します。
6. scripts/cdp-agent.mjs inspect を実行し、テナント、パス、タイトル、画面上のログイン状態、ページの準備状況を確認します。
7. 複製によって揮発性状態が失われた場合は、分離された対象に対して scripts/cdp-agent.mjs import-auth を実行し、 ページを再読み込みして、認証状態の検査をもう一度行います。
8. それでも認証に失敗する場合は、分離されたプロファイルで一度ログインするようユーザーに依頼します。以後は scripts/edge-profile.ps1 -Action LaunchExisting を使って再利用します。データが入った自動化ルートに複製しないでください。

Windows コマンド一式、パスの確認、CDP プローブ、復旧マトリクスについては、 references/edge-cdp-control.md と references/auth-state-bootstrap.md を参照してください。

4. 検証済みの対象を操作する

分離された Edge インスタンスを直接使用します。コマンドの全容を確認するには、scripts/cdp-agent.mjs --help を実行します。 同梱のドライバーは、決定的な対象指定、検査／スナップショット、移動、評価、セレクターまたは座標によるクリック、 テキスト入力、キー入力、スクリーンショット、Playwright を使わない認証状態のエクスポート／インポートに対応しています。 利用するタスクで必要な場合に限り、既存の Playwright インストールを使用します。このワークフローのためにインストールしないでください。

認証の転送には、CDP の Storage.getCookies と Storage.setCookies に加え、ページ単位の localStorage と sessionStorage を使用します。インポート後に、SSO リダイレクト、SameSite の挙動、証明書、画面上の準備状況を再確認します。 アプリ内ブラウザーは別のセッションのままです。

5. 準備状況を確認し、ドメイン操作を実行する

変更を加える前に、次の点を確認します。

• テナントとアプリケーションの識別情報
• 認証済みの状態であること。ログインページではない URL であるだけでは不十分です
• 正しい Story Designer、Modeler、Data Builder、SQL エディター、またはテスト対象の領域
• 準備状況を示すマーカーが表示され、操作を妨げるエラーがないこと
• 承認済みのホスト／パスと、選択されている対象ページ
• 利用するスキルで必要とされる場合は、現在のモデル／ストーリー／ウィジェットのメタデータ

ページ固有の証拠と、データなし／エラーの状態を明示的に記録します。スピナーが消えたこと、CDP が接続したこと、またはブラウザーウィンドウが開いたことを、タスク完了とみなしてはいけません。

6. 正直に復旧するか、引き継ぐ

次の順序で代替手段を試します。

1. 選択したブラウザーの、文書化されたトラブルシューティング手順に従って再試行します。
2. Edge／CDP の復旧と DevToolsActivePort の代替手段を使用します。
3. 分離された Edge プロファイルで、一度限りの手動認証を依頼します。
4. 環境が対応している場合は、承認済みのデスクトップ／手動支援を利用します。
5. 認証済みの対象を確認できない場合は停止し、実装可能な仕様、正確に不足している証拠、および次に必要な手動操作を提示します。

ユーザーがブラウザーまたは接続方式を明示的に指定した場合は、別の画面に切り替えるためにこの手順を使用してはいけません。指定された画面を利用できない場合、またはそこでのライブハンドシェイクに失敗した場合は停止します。

認証状態は verified、missing、expired、blocked、または unknown として報告します。ブラウザーの起動だけを根拠に、認証成功と推測してはいけません。

トラブルシューティング

CDP エンドポイントへの接続拒否またはエンドポイントの欠落、404 の検出応答、誤った対象、SSO リダイレクト、認証されていないコピー済みプロファイル、ポリシーによるブロック、ランタイム／ウィジェットのエラーなど、一般的な障害については、共通の Edge リファレンスで説明しています。復旧しても認証済みの対象を確認できない場合は、推測したり完了を主張したりせず、不足している証拠を引き継いで停止します。

ソースと検証

公開ソースのレビューと、文書化された動作と未検証のテナント動作の区別は、docs/project/sap-browser-automation-source-review-2026-07-14.md に記録されています。

安全性と証拠

プロファイルのコピーや認証状態ファイルには、Cookie、更新トークン、保存済みパスワード、履歴、拡張機能、企業のセッションデータが含まれている場合があります。アクセスを制限したユーザー専用のローカルパスに保管してください。リポジトリ内に置いたり、コミットしたり、Oracle に送信したり、バグ報告に含めたり、内容をチャットに貼り付けたりしてはいけません。証拠からは、テナント ID、ストーリー ID、クエリ文字列、セッションに類する URL 値、Cookie 値、WebSocket エンドポイント、および無関係なタブを伏せてください。

書き込みを伴う操作では、承認したユーザー、対象、意図した変更、変更前後の検証、ロールバックまたはクリーンアップの状態を記録します。操作そのものが許可されているかどうかについては、利用する SAP スキルの規定が優先されます。