> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/agent-browser/ye-mian-chu-li-qi.md).

# 页面处理器

让智能体浏览器识别每个页面、自动处理访问挑战，并在页面准备就绪时通知您的脚本。

{% hint style="warning" %}
**需要账户访问权限：** 未启用该功能的账户会收到 `在握手过程中，此账户未启用 400 页面处理器` （见 [响应代码](https://developers.oxylabs.io/products/cn/agent-browser/xiang-ying-dai-ma.md)).
{% endhint %}

Oxylabs Agent Browser 使用内置页面处理器来处理网站访问挑战。 `page_handler` 该参数会标识其加载的每个页面，完成找到的受支持挑战，并将页面状态作为窗口消息报告给你的脚本。

```bash
wss://USER:PASS@hb.oxylabs.io?p_cc=US&page_handler=true
```

**页面处理器默认禁用** 并且必须为每个连接传递，并在所有指向同一目标的连接中保持一致，包括共享一个 [持久配置文件](https://developers.oxylabs.io/products/cn/agent-browser/persistent-sessions-and-profiles.md#persistent-profiles) （配置文件 `o_profile` 或粘性代理会话 `proxy_resi_ses_id`).

<table><thead><tr><th width="133">参数</th><th width="405">说明</th><th width="93.5">类型</th></tr></thead><tbody><tr><td><code>page_handler</code></td><td>启用页面识别和自动挑战处理。默认： <code>false</code>.</td><td>布尔值</td></tr></tbody></table>

{% hint style="info" %}
页面处理器会增加页面加载时间，因此仅在目标会出现挑战时启用它。如果你的账户未启用该功能，请联系 [Oxylabs 支持团队。](mailto:support@oxylabs.io)
{% endhint %}

## 页面状态

启用页面处理器后，浏览器会将每个页面的状态报告为 `window` 消息：

```javascript
{ source: "oxylabs-runtime", type: "oxylabs-page-status", status: "open" }
```

<table><thead><tr><th width="130.5">状态</th><th>说明</th></tr></thead><tbody><tr><td><code>识别中</code></td><td>页面正在检查。</td></tr><tr><td><code>已关闭</code></td><td>发现了一个挑战，正在处理中。页面目前还不可用。</td></tr><tr><td><code>开盘价</code></td><td>页面已可用。</td></tr><tr><td><code>失败</code></td><td>无法完成该挑战。该消息包含一个 <code>错误</code> 字段。</td></tr></tbody></table>

`识别中` 和 `已关闭` 是临时状态，因此请等待 `开盘价` 或 `失败`。没有挑战的页面会报告 `开盘价` 大约在加载后 8 秒，而处理挑战通常需要 30–45 秒。如果状态为 `失败`，请关闭会话并使用新连接重试。

## 跟踪页面状态

浏览器控制台输出不会发送给 CDP 客户端，因此请使用在页面加载前添加的脚本监听窗口消息，然后等待最终状态：

{% tabs %}
{% tab title="Python (Playwright)" %}

```python
from playwright.sync_api import sync_playwright

username = "USERNAME"
password = "PASSWORD"
endpoint = "hb.oxylabs.io"
browser_url = f"wss://{username}:{password}@{endpoint}?p_cc=US&page_handler=true"

# Keep the latest page status in the page
status_listener = """
window.addEventListener("message", (e) => {
  const d = e.data;
  if (d?.source === "oxylabs-runtime" && d.type === "oxylabs-page-status") {
    window.__pageStatus = d.status;
  }
});
"""

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url)
    context = browser.contexts[0] if browser.contexts else browser.new_context()
    context.add_init_script(status_listener)  # add before opening the page
    page = context.new_page()
    page.goto("https://example.com")

    # Wait until the page is ready ("open") or the handler gives up ("failed")
    page.wait_for_function("['open', 'failed'].includes(window.__pageStatus)", timeout=90000)
    print(page.evaluate("window.__pageStatus"), page.title())
    browser.close()
```

{% endtab %}

{% tab title="JavaScript (Playwright)" %}

```javascript
import { chromium } from "playwright";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US&page_handler=true`;

// Keep the latest page status in the page
const statusListener = () => {
    window.addEventListener("message", (e) => {
        const d = e.data;
        if (d?.source === "oxylabs-runtime" && d.type === "oxylabs-page-status") {
            window.__pageStatus = d.status;
        }
    });
};

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const context = browser.contexts()[0] || (await browser.newContext());
    await context.addInitScript(statusListener); // add before opening the page
    const page = await context.newPage();
    await page.goto("https://example.com");

    // Wait until the page is ready ("open") or the handler gives up ("failed")
    await page.waitForFunction(
        () => ["open", "failed"].includes(window.__pageStatus),
        null,
        { timeout: 90000 }
    );
    console.log(await page.evaluate(() => window.__pageStatus), await page.title());
    await browser.close();
})();
```

{% endtab %}

{% tab title="JavaScript (Puppeteer)" %}

```javascript
import puppeteer from "puppeteer";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US&page_handler=true`;

// Keep the latest page status in the page
const statusListener = () => {
    window.addEventListener("message", (e) => {
        const d = e.data;
        if (d?.source === "oxylabs-runtime" && d.type === "oxylabs-page-status") {
            window.__pageStatus = d.status;
        }
    });
};

(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: browserUrl });
    const page = await browser.newPage();
    await page.evaluateOnNewDocument(statusListener); // add before opening the page
    await page.goto("https://example.com");

    // Wait until the page is ready ("open") or the handler gives up ("failed")
    await page.waitForFunction(
        () => ["open", "failed"].includes(window.__pageStatus),
        { timeout: 90000 }
    );
    console.log(await page.evaluate(() => window.__pageStatus), await page.title());
    await browser.close();
})();
```

{% endtab %}
{% endtabs %}

### 页面加载后处理挑战

页面处理器会处理页面加载时已存在的挑战。之后出现的挑战，例如点击或表单提交后出现的挑战，不会自动处理。要处理它，请发送一个 `oxylabs-page-handle` 消息到页面。浏览器会重新检查页面，处理找到的任何挑战，并像之前一样报告状态。

### MCP 服务器和代理技能

如果你正在使用 AI 代理或编程助手，我们强烈建议利用 Oxylabs Agent Browser 的简易集成方式：

<table data-header-hidden><thead><tr><th width="152"></th><th></th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/ai-workflows/cn/dai-li-ji-neng.md"><strong>Agent Skills</strong></a></td><td>在 Claude Code、Cursor 和其他 AI 编程助手中设置 Agent Browser。</td></tr><tr><td><a href="https://developers.oxylabs.io/ai-workflows/cn/mcp.md"><strong>MCP 服务器</strong></a></td><td>为兼容 MCP 的 AI 助手提供远程 Agent Browser。</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/agent-browser/ye-mian-chu-li-qi.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
