Page Agent

Web アプリの中に、自然言語で操作できる相棒を組み込みます。

skill の情報

参考: SKILL.md 全文

page-agent

alibaba/page-agent（https://github.com/alibaba/page-agent 、スター 17,000 超、MIT）は、TypeScript で書かれた、ページの中で動く GUI エージェントです。Web ページの内側に住み、DOM をテキストとして読み（画面の撮影も、複数の形式を扱う LLM も使いません）、「ログインボタンを押して、ユーザー名に John と入れて」のような自然言語の指示を、いま開いているページに対して実行します。すべてブラウザ側で完結し、載せる側はスクリプトを読み込んで、OpenAI 互換の LLM の接続先を渡すだけです。

こんなときに使います

次のような場面で、この skill を読み込みます。

• 自分の Web アプリに AI の相棒を載せたい（SaaS、管理画面、法人向けツール、ERP、CRM）— 「ダッシュボードの利用者に、5 画面をたどらせる代わりに『Acme Corp の請求書を作ってメールして』と打ってもらいたい」
• 古い Web アプリを、画面を作り直さずに今風にしたい — page-agent は既存の DOM の上にそのまま載ります
• 自然言語での操作を足して、使いやすくしたい — 音声や読み上げを使う人が、やりたいことを言葉で伝えて画面を操作できます
• page-agent を試したい・評価したい — 手元の LLM（Ollama）でも、提供されている LLM（Qwen、OpenAI、OpenRouter）でも動かせます
• 対話型の研修や製品デモを作りたい — 「経費精算の出し方」を、実際の画面の上で AI に案内させられます

こんなときは使いません

• Hermes 自身にブラウザを操作させたい → Hermes に組み込みのブラウザツール（Browserbase / Camofox）を使ってください。page-agent は *逆向き* のものです。
• 組み込まずに、タブをまたぐ自動操作をしたい → Playwright、browser-use、あるいは page-agent の Chrome 拡張を使ってください
• 画面を見て位置を判断してほしい → page-agent は DOM のテキストしか見ません。画像も扱えるブラウザエージェントを使ってください

事前に必要なもの

• Node 22.13 以上または 24 以上、npm 10 以上（ドキュメントには 11 以上とありますが、10.9 でも問題なく動きます）
• OpenAI 互換の LLM の接続先。Qwen（DashScope）、OpenAI、Ollama、OpenRouter、あるいは /v1/chat/completions を話せるものなら何でも構いません
• 開発者ツールが使えるブラウザ（調べもの用）

方法 1 — CDN を使って 30 秒で試す（導入なし）

いちばん早く動きを見られる方法です。alibaba が無償で公開している評価用の LLM 中継を使います。評価だけに使ってください。先方の規約が適用されます。

好きな HTML ページに次の 1 行を足します（開発者ツールのコンソールに貼って、ブックマークレットとして使っても構いません）。

<script src="https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>

パネルが現れます。指示を打ちます。これだけです。

ブックマークレットの形（ブックマークバーに入れて、好きなページで押します）:

javascript:(function(){var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js';document.head.appendChild(s);})();

方法 2 — 自分の Web アプリに npm で入れる（本番向け）

既にある Web プロジェクトの中で（React / Vue / Svelte / 素の JavaScript、どれでも）:

npm install page-agent

自分の LLM の接続先をつないで動かします。評価用の CDN を実際の利用者に届けてはいけません。

const agent = new PageAgent({
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: process.env.LLM_API_KEY,   // never hardcode
    language: 'en-US',
})

// Show the panel for end users:
agent.panel.show()

// Or drive it programmatically:
await agent.execute('Click submit button, then fill username as John')

接続先の例です（OpenAI 互換ならどれでも動きます）。

主な設定項目（new PageAgent({...}) に渡します）:

• model、baseURL、apiKey — LLM への接続
• language — 画面の言語（en-US、zh-CN など）
• エージェントが触れる範囲を絞るための、許可リストとデータの伏せ字の仕組みもあります。項目の全体は https://alibaba.github.io/page-agent/ を見てください

安全のために。 実際に公開するなら、apiKey をブラウザ側のコードに置かないでください。LLM の呼び出しは自分のサーバー経由にして、baseURL をそちらに向けます。評価用の CDN があるのは、その中継を alibaba が評価向けに動かしているからです。

方法 3 — 元のリポジトリを取ってくる（開発に加わる、あるいは手を入れる）

page-agent そのものを直したい、手元でまとめた IIFE 版を使って好きなサイトで試したい、ブラウザ拡張を開発したい、というときに使います。

git clone https://github.com/alibaba/page-agent.git
cd page-agent
npm ci              # exact lockfile install (or `npm i` to allow updates)

リポジトリの直下に .env を作り、LLM の接続先を書きます。例:

LLM_MODEL_NAME=gpt-4o-mini
LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1

Ollama の場合:

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=NA
LLM_MODEL_NAME=qwen3:14b

よく使うコマンド:

npm start           # docs/website dev server
npm run build       # build every package
npm run dev:demo    # serve IIFE bundle at http://localhost:5174/page-agent.demo.js
npm run dev:ext     # develop the browser extension (WXT + React)
npm run build:ext   # build the extension

好きなサイトで試すには、手元でまとめた IIFE 版を使います。次のブックマークレットを登録してください。

javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log('PageAgent ready!');document.head.appendChild(s);})();

そのうえで npm run dev:demo を実行し、好きなページでブックマークレットを押すと、手元の版が読み込まれます。保存するたびに作り直されます。

注意: 開発用にまとめると、.env の LLM_API_KEY がそのまま IIFE 版の中に埋め込まれます。まとめたファイルを共有しないでください。コミットもしないでください。URL を Slack に貼るのもやめてください。（実際に、公開されている開発用の版を検索すると .env の値がそのまま出てきます。）

リポジトリの構成（方法 3）

npm のワークスペースを使ったモノレポです。主なパッケージはこちらです。

動いているかを確かめる

方法 1 か方法 2 のあと:

1. 開発者ツールを開いた状態で、そのページをブラウザで開きます
2. 浮いたパネルが見えるはずです。見えなければコンソールのエラーを確認してください（多いのは、LLM の接続先の CORS、baseURL の誤り、API キーの誤りです）
3. そのページに見えているものに合わせて、簡単な指示を打ちます（「ログインのリンクを押して」など）
4. ネットワークのタブを見ます。baseURL あての通信が出ているはずです

方法 3 のあと:

1. npm run dev:demo が Accepting connections at http://localhost:5174 と表示します
2. curl -I http://localhost:5174/page-agent.demo.js が HTTP/1.1 200 OK と Content-Type: application/javascript を返します
3. 好きなサイトでブックマークレットを押すと、パネルが出ます

つまずきやすいところ

• 評価用の CDN を本番で使う — やめてください。回数の制限があり、alibaba の無償の中継を使っていて、先方の規約でも本番利用は禁じられています。
• API キーが見えてしまう — new PageAgent({apiKey: ...}) に渡したキーは、JavaScript の配布物に載ります。実際に公開するなら、必ず自分のサーバー経由にしてください。
• OpenAI 互換でない接続先 は、黙って失敗するか、意味の取りにくいエラーになります。Anthropic や Gemini の形式が必要な提供元なら、あいだに OpenAI 互換の中継（LiteLLM、OpenRouter）を挟んでください。
• CSP で止まる — Content-Security-Policy が厳しいサイトでは、CDN のスクリプトを読み込めなかったり、インラインでの評価が禁じられていたりします。その場合は自分のドメインから配ってください。
• 方法 3 で .env を直したら 開発サーバーを立て直してください — Vite は起動時にしか環境変数を読みません。
• Node の版 — リポジトリの宣言は ^22.13.0 || >=24 です。Node 20 では npm ci が engine のエラーで失敗します。
• npm 10 と 11 — ドキュメントには npm 11 以上とありますが、npm 10.9 でも問題なく動きます。

一覧

• リポジトリ: https://github.com/alibaba/page-agent
• ドキュメント: https://alibaba.github.io/page-agent/
• ライセンス: MIT（browser-use の DOM 処理の内部実装をもとにしています。Copyright 2024 Gregor Zunic）