Page-Agent で AI に Web ページを操作させる方法：組み込み GUI Agent、フォーム自動化、権限境界

Sun, 12 Jul 2026 12:14:00 +0800

Page-Agent は Agent にブラウザ全体を操作させる方式とは異なり、JavaScript をページに組み込み、ページ自体に GUI Agent を持たせます。公式説明では、主にテキスト化した DOM 操作を使い、スクリーンショット、マルチモーダルモデル、Python、headless browser に依存しません。複数ページのタスクには Chrome 拡張機能があり、Beta MCP Server も提供されています。プロジェクト README

ERP、CRM、管理画面、社内ツールに「一言で一連の操作を行う」支援を加える用途に適しています。ただし、製品の権限を回避するものではありません。すべての操作は既存の認可、サーバー側検証、人による確認に従う必要があります。

Page-Agent とブラウザ自動化の選び方

目的	向く手段
自社 Web 製品に自然言語アシスタントを組み込む	Page-Agent
回帰テスト、クロスサイト収集、決定的スクリプト	Playwright または Puppeteer
coding agent に network、console、performance を調べさせる	Chrome DevTools MCP
人のセッションを保ったまま実際の Chrome を操作する	browser-harness 系ツール

サイト内の browser-harness、Playwright、Puppeteer の比較も参照してください。Page-Agent はテストフレームワークの代替ではなく、操作機能を製品の機能として利用者や外部 Agent に渡すものです。

NPM で最小構成を作る

まずパッケージを導入します。

`1`	`npm install page-agent`

フロントエンドの入口でインスタンスを作成します。モデル URL、キー、許可する操作範囲はサーバー側またはセキュリティ設定で管理し、本番キーをブラウザコードへ直接書かないでください。

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
  model: 'qwen3.5-plus',
  baseURL: 'https://your-compatible-api.example/v1',
  apiKey: 'USE_A_SCOPED_KEY',
  language: 'zh-CN',
})

await agent.execute('在当前页面找到“新建客户”按钮，但不要提交表单')

これは DOM 認識とボタン位置の確認用です。実運用では apiKey を短命、上限付き、失効可能な方式に置き換え、万能キー、ユーザー token、管理者認証情報をページスクリプトへ渡さないでください。

導入順序：読み取り、下書き、送信

最初は顧客一覧の絞り込みやチケット下書きなど、低権限で項目の少ないページを選びます。第1段階では、要素の特定、可視テキストの読み取り、操作提案だけを許可し、テストデータで同名レコードや状態を区別できるか確認します。保存、添付アップロード、外部ドメイン遷移はまだ許可しません。

第2段階でフォーム入力を許可します。顧客 ID、割引率、有効期限など構造化した業務パラメータに限定し、「張三に割引を付ける」だけの曖昧な入力にはしません。フロントエンドは書き込む予定の項目をプレビューし、サーバーは現在のロールで編集可能か、値が範囲内かを再検証します。確認後に既存 API を呼び出し、Agent に迂回経路を与えません。

送信は最後に検討します。人のボタンと同じ API、監査ログ、二重確認を通し、成功後はオブジェクト ID、バージョン、エラーを読み取って表示します。モデルの誤解はプレビュー、権限、サーバー検証のいずれかで止められます。

タスクをレビュー可能な段階に分ける

フォーム自動化で問題になりやすいのはクリックより対象と副作用です。次のように分けます。

検索：現在のページに見える項目と候補レコードだけを読む。
下書き入力：ローカルフォームだけに書き込み、送信・添付アップロードはしない。
差分表示：書き込む項目と値を利用者に確認させる。
送信：利用者の確認とサーバー側認可の後だけ実行する。

「顧客 A に 20% 割引を作る」を直接 Agent に渡してはいけません。下書きを作成させ、顧客 ID、価格規則、有効期間を表示し、権限のある人が送信する設計が安全です。

ページ機能をアクション許可リストに絞る

すべての DOM 要素を呼び出し可能なツールにしないでください。searchCustomer、fillDiscountDraft、previewDiscount、submitDiscount のような業務アクションを定義し、読み取り専用、取り消し可能、副作用ありを区別します。Agent がアクションを選び、フロントエンドが対応する操作を実行します。削除、返金、メンバー招待、データ出力などは登録しないか、常に手動確認を要求します。

実行ごとに利用者、ページ、アクション、入力要約、結果、失敗理由を記録します。ログはマスキングし、完全なキー、cookie、顧客の機密項目を保存しません。誤操作時に、Agent が何を見て何を提案し、誰が最終確認したかを追えます。

ログイン、複数ページ、MCP の境界

Page-Agent はページの既存ログイン状態を利用できますが、権限拡大の理由にはなりません。次を避けてください。

Agent に自然言語から cookie、パスワード、認証コードを抽出・表示させること。
ログイン後データを未審査のモデル endpoint に送ること。
「自動化」で二重確認、決済確認、ロール承認を飛ばすこと。
複数ページ機能を全利用者に既定で開放すること。

公式 Chrome 拡張機能や MCP Server を複数ページまたは外部 Agent 制御に使う場合は、ドメイン許可リスト、アクション許可リスト、監査ログを作ります。Beta 機能は本番管理画面の前にテスト環境で試してください。

本番前に実タスクで検証する

「今週フォローが必要な顧客を絞る」「指定チケットの下書き項目を補う」「注文から顧客ページへ移動する」など、低リスクの実タスクを3～5件選びます。成功、曖昧、権限なしの例を用意します。成功はプレビューまで、曖昧な場合は質問または停止、権限なしは追加情報を漏らさずバックエンドが拒否しなければなりません。

正しいボタンを押せたかだけでなく、初回応答時間、失敗の説明可能性、更新後の下書き、ネットワーク断やモデル timeout 時の未送信データも確認します。通過してから対象ページを広げます。

トラブルシューティング

問題	対処
ボタンまたは項目が見つからない	動的レンダリング、iframe／オーバーレイ、文言の安定性を確認する。
Agent が誤ったレコードを選ぶ	名前だけで照合せず、一意 ID、読み取り専用プレビュー、結果表示を加える。
モデル呼び出しが失敗する	互換 API、上限、CORS、キー注入位置を確認し、フロントエンドログにキーを出さない。
入力済みなのに送信結果が違う	入力と送信を分け、送信後にサーバーの戻り値を読み取り表示する。

まとめ

Page-Agent の要点は、ページが一文を理解することではなく、自然言語の操作を観測可能、取り消し可能、承認可能な製品フローへ制限することです。まず読み取りと下書き入力で検証し、その後に副作用を段階的に開放します。

Page-Agent on KnightLiブログ