page-agent-browser

# Page Agent Browser

Use this skill to let Codex control a rendered webpage through Alibaba PageAgent while staying attached to the user's real Chrome whenever possible.

Treat PageAgent as a browser-side helper layered on top of the browser MCP tools. It is not a standalone Codex plugin.

Read [references/page-agent-real-chrome.md](./references/page-agent-real-chrome.md) when you need the exact setup assumptions, official capability boundaries, or prompt-writing patterns.

## Overview

This skill exists to make Codex better at browser work that is too brittle or too verbose for raw `click` and `fill` scripting.

Treat this as the preferred escalation target when `chrome-devtools-real` can still reach the page, but manual browser primitives are becoming expensive, fragile, or hard to maintain.

Use it to:

- drive the user's real Chrome through `chrome-devtools-real`
- reuse Page Agent Ext when it is already installed in the active Chrome profile
- fall back to direct in-page `PageAgent` injection for active-tab tasks
- keep Codex responsible for verification instead of trusting agent output blindly

This skill is optimized for real-user browsing contexts, especially sites where:

- the user is already logged in
- multiple tabs matter
- extension state matters
- selectors are cumbersome
- the site is hostile to third-party script injection

## Preconditions

- Prefer `chrome-devtools-real`. Use `chrome-devtools` only if the user explicitly wants the isolated browser or the real-browser attachment is unavailable.
- Confirm a browser tab is already open on the target page.
- Confirm the page is one where in-page JavaScript execution is acceptable.
- Do not assume PageAgent works without an LLM configuration.
- Ask before using PageAgent on login, payment, destructive admin, or privacy-sensitive workflows.

## Default Strategy

1. Attach to the user's real Chrome through `chrome-devtools-real`.
2. Keep the active browser profile stable. If the user says Page Agent Ext is installed in a specific profile, avoid switching to another profile window.
3. Inspect the current page before invoking PageAgent.
4. Prefer extension-backed usage when the attached browser already has Page Agent Ext and the task may span multiple steps or tabs.
5. Fall back to direct page injection when extension-backed behavior is unavailable, unverifiable, or unnecessary.
6. Verify the resulting DOM with browser snapshots instead of trusting the agent output alone.

## Switching Rules

Switch into this skill from `chrome-devtools-real` when any of the following are true:

- the raw MCP path requires many low-level browser actions
- selector discovery is taking longer than the task itself
- the flow spans multiple tabs, pages, or coordinated navigation
- the site is CSP-heavy and extension mode is more realistic than page injection
- the user asks for PageAgent explicitly
- repeated raw-browser retries indicate rising cost or brittleness

Do not switch just because PageAgent exists.

Stay with raw browser control when:

- the task is short and deterministic
- one or two direct browser actions solve it cleanly
- PageAgent setup cost is higher than the remaining work

## Tooling Assumptions

- Browser transport is provided by Codex browser MCP tools.
- `chrome-devtools-real` is the preferred target when available.
- `Page Agent Ext` may expose `window.PAGE_AGENT_EXT` on supported pages after its handshake is active.
- Model access is still required because PageAgent is not self-contained.

## Workflow

### 1. Inspect the page first

- Open or select the target page with browser tools.
- Take a snapshot before injection so you understand the current state and can verify the result afterward.

### 2. Choose the model configuration

PageAgent needs an OpenAI-compatible `baseURL`, `apiKey`, and `model`.

Use a concrete configuration that the user already trusts:

- Personal or local model:
  - `baseURL: 'http://localhost:11434/v1'`
  - `apiKey: 'NA'`
  - `model: 'qwen3:14b'`
- OpenAI-compatible cloud endpoint:
  - `baseURL: '<provider-compatible-endpoint>'`
  - `apiKey: '<secret>'`
  - `model: '<tool-capable-model>'`
- Alibaba testing API, only for technical evaluation:
  - `baseURL: 'https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run'`
  - `apiKey: 'NA'`
  - `model: 'qwen3.5-plus'`

Do not present the testing API as production-safe.

### 3. Decide execution mode

Use extension-backed mode first when all of the following are true:

- `chrome-devtools-real` is attached to the user's real Chrome
- the user says Page Agent Ext is installed in that profile
- the task benefits from PageAgent rather than direct DOM actions

Force extension-backed mode when any of the following are true:

- the page has a strict CSP that blocks external script injection
- the site is GitHub or another major app that restricts third-party scripts
- the task needs multiple tabs, cross-page coordination, or tab switching
- the task requires preserving the user's real login state and extension state across pages

Use direct injection mode when:

- the task is limited to the current page
- extension availability is uncertain
- the page must be handled immediately and a normal in-page agent is sufficient

Prefer extension-backed mode over direct injection when the reason for switching was CSP friction, multi-tab coordination, or repeated low-level browser failure.

Do not invent a private extension API. If extension internals are not visible from the page, continue with normal browser tools plus direct PageAgent injection for the active tab.

### 4.5. Use extension mode on GitHub-like sites

On GitHub and similar CSP-heavy sites, assume CDN injection will fail unless proven otherwise.

Use this sequence:

1. Check whether `window.PAGE_AGENT_EXT` is already exposed on the page.
2. If not, confirm the extension handshake token is present for that origin before assuming extension mode is unavailable.
3. If the extension becomes available, call `window.PAGE_AGENT_EXT.execute(...)`.
4. If the extension still does not expose an API, fall back to ordinary browser MCP actions instead of retrying blocked CDN injection repeatedly.

When using extension mode, give more specific prompts than you would for manual browser control. Include:

- exact URLs when known
- whether to open a new tab or reuse the current tab
- which tab should be focused when done
- the expected end state

### 4. Inject the script for active-tab mode

```javascript
async () => {
  if (!window.PageAgent) {
    await new Promise((resolve, reject) => {
      const script = document.createElement('script');
      script.src = 'https://cdn.jsdelivr.net/npm/page-agent@1.5.7/dist/iife/page-agent.demo.js';
      script.crossOrigin = 'anonymous';
      script.onload = resolve;
      script.onerror = () => reject(new Error('Failed to load PageAgent'));
      document.head.appendChild(script);
    });
  }
  return { hasPageAgent: typeof window.PageAgent !== 'undefined' };
}
```

Verify `hasPageAgent` is `true` before continuing.

### 5. Create or reuse one agent instance

Store the instance on `window` so later calls can reuse it:

```javascript
async () => {
  window.__pageAgent = window.__pageAgent || new window.PageAgent({
    baseURL: 'http://localhost:11434/v1',
    apiKey: 'NA',
    model: 'qwen3:14b',
    language: 'zh-CN'
  });
  return { ready: !!window.__pageAgent };
}
```

Adapt the config to the user's actual model endpoint.

### 6. Execute one concrete instruction

Call `execute` from `evaluate_script`:

```javascript
async () => {
  const result = await window.__pageAgent.execute('Click the submit button and confirm the dialog');
  return result;
}
```

Keep instructions concrete and page-local unless the extension-backed workflow is already confirmed. Good examples:

- `Open the profile menu and switch language to Chinese`
- `Fill the search box with "invoice" and submit`
- `Create a new row with quantity 3 and save`

Prefer one goal per call. If the task is long, break it into checkpoints and verify between them.

For extension-backed multi-tab tasks, prefer URL-explicit prompts such as:

- `Open https://github.com/alibaba/page-agent/blob/main/docs/README-zh.md in a new tab, ensure Releases is open in another tab, then return focus to the repository tab`
- `Open the issues page in a new tab, collect the top 3 issue titles, then switch back to the code tab`

### 7. Verify with browser tools

- Take another snapshot.
- Confirm the page state actually changed as intended.
- If the action partially succeeded, report exactly what changed and what remains unresolved.
- For multi-tab tasks, verify the final focused tab with `list_pages` plus a page snapshot or `location.href` check.
- If the agent claims it returned to a target tab but the actual selected tab or URL does not match, correct it manually with browser MCP actions and report the mismatch as an agent limitation.

### 8. Enforce final tab state for multi-page work

When the task specifies which tab should be focused at the end:

1. Record the intended end tab before execution when possible.
2. After `window.PAGE_AGENT_EXT.execute(...)` finishes, immediately verify the selected page and current URL.
3. If the intended tab is missing, say so explicitly instead of claiming success.
4. If the intended tab still exists but is not focused, switch back with browser MCP tools.
5. Only report success after the final tab state is externally verified.

## When To Skip PageAgent

- Skip it for simple deterministic actions that `click`, `fill`, `press_key`, or direct DOM inspection can handle more reliably.
- Skip it when the page blocks script injection and the task does not justify extra setup.
- Skip it on sensitive workflows unless the user explicitly wants PageAgent and accepts the tradeoff.

## Failure Handling

- If script injection fails, fall back to normal `chrome-devtools` actions.
- If a site blocks CDN injection with CSP, prefer extension-backed mode instead of retrying other CDN mirrors.
- If PageAgent reports missing config, stop and supply a valid `baseURL`/`apiKey`/`model`.
- If the page blocks script execution or CSP prevents loading the CDN asset, explain that the page cannot be driven this way and use ordinary browser tools instead.
- If multi-page execution returns correct data but leaves the wrong tab focused, treat that as partial success and repair the tab state manually.
- If the task is sensitive, prefer manual deterministic steps over autonomous natural-language execution.

## Integration Guidance For Codex

Translate the official PageAgent integration model into Codex like this:

1. Use `chrome-devtools-real` as the preferred browser transport.
2. Reuse the user's real Chrome profile when Page Agent Ext is already installed there.
3. Invoke PageAgent from page context for the active tab.
4. Use ordinary browser MCP actions to select pages, gather state, and verify outcomes.
5. Fall back to plain `chrome-devtools` only when the real-browser route is unavailable.

Treat this skill as a browser-side adapter pattern, not as a standalone MCP server.

When both skills are available, use this routing rule:

1. Start with `chrome-devtools-real`.
2. Escalate to `page-agent-browser` when manual browser control becomes high-cost or brittle.
3. Return to ordinary browser verification after PageAgent execution.