# 让 Agent 操作浏览器

> 用「浏览器操作」在真实浏览器里导航、读页、填表和复用登录态，并在提交前保留人工确认。

Canonical page: /product/browser



<Takeaways>
  <li>
    只查公开资料用网页搜索，要「进页面把事办完」才用浏览器操作
  </li>

  <li>
    浏览器窗口就在你面前，登录、验证码和二次验证由你亲自完成
  </li>

  <li>
    每个会话使用独立浏览器 session，发布、付款、删除类动作要求先确认
  </li>
</Takeaways>

浏览器操作（Browser Use）是随应用发布的系统插件。它让 Agent 通过 `agent-browser` 命令行驱动一个真实的 Chrome：打开网址、用无障碍树快照定位元素、点击、输入、等待、翻页并取回结果。页面是真的，登录态是你自己的，因此它能做到网页搜索做不到的事。

面板入口：**设置 → 更多选项 → 浏览器操作**。面板只负责运行时状态与说明，真正的入口是对话框——直接在会话里说明目标和网址即可。

## 先判断该用哪一个 [#先判断该用哪一个]

<Fork>
  <ForkYes title="使用浏览器操作">
    <li>
      页面需要登录才能看到
    </li>

    <li>
      要填表单、切筛选、翻到第 N 页
    </li>

    <li>
      要在后台里完成一次多步骤操作
    </li>

    <li>
      要把多个页面的结果对照整理
    </li>
  </ForkYes>

  <ForkNo title="改用网页搜索">
    <li>
      只需要公开资料的摘要或出处
    </li>

    <li>
      问题能靠一次检索回答
    </li>

    <li>
      不需要保持任何页面状态
    </li>
  </ForkNo>
</Fork>

网页搜索给你的是别人整理过的摘要；浏览器操作是真的开一个浏览器。要「看一眼资料」用搜索，要「替我把事办了」用它。

## 首次使用会装什么 [#首次使用会装什么]

插件本身随应用发布，不需要安装；第一次做浏览器任务时，Agent 会自行准备运行时。

<Steps>
  <Step>
    ### 检查运行时 [#检查运行时]

    Agent 先确认 `agent-browser` 是否存在以及版本是否满足插件锁定的版本。版本读不出来时按不兼容处理，宁可提示重装也不静默失败。
  </Step>

  <Step>
    ### 安装锁定版本 [#安装锁定版本]

    缺失或过旧时，Agent 把锁定版本装进 Vetta 私有的 npm 目录（约 90MB）。安装前会校验该私有目录确实存在，不会改动你机器上已有的全局 `agent-browser`。
  </Step>

  <Step>
    ### 准备浏览器 [#准备浏览器]

    健康检查发现没有可复用的 Chrome 时，会再下载一次 Chrome for Testing；系统已有 Chrome 则直接复用，不额外下载。
  </Step>

  <Step>
    ### 自动流程失败时用面板 [#自动流程失败时用面板]

    自动准备失败时，到 **设置 → 更多选项 → 浏览器操作** 面板里重新检查、安装或升级，面板会显示失败命令与原因。
  </Step>
</Steps>

面板状态含义：

| 状态      | 含义                         | 下一步                    |
| ------- | -------------------------- | ---------------------- |
| 已就绪     | CLI 可用，直接在会话里提要求即可         | 无需操作                   |
| 尚未安装运行时 | 第一次使用，或运行时被移除              | 点击安装                   |
| 运行时版本过旧 | PATH 上有更旧的 `agent-browser` | 点击升级，装入 Vetta 自己的运行时目录 |
| 尚未安装浏览器 | 本机没有可复用的 Chrome            | 下载 Chrome for Testing  |
| 安装失败    | 网络、权限或命令冲突                 | 看面板给出的命令与错误，修复后重试      |

<Callout title="浏览器任务需要全权限执行模式" type="warn">
  沙箱执行模式会给每条命令一个临时 home，浏览器 session 无法在命令之间保持。遇到这种情况请切换会话的执行模式，而不是让 Agent 另建一个游离的 session。
</Callout>

## 一次任务是怎么跑的 [#一次任务是怎么跑的]

1. **打开页面**：Agent 用带窗口的模式打开目标网址，你能看到它在做什么。
2. **读页面**：抓取交互元素快照并拿到元素引用，比传整页 HTML 省上下文，也比截图更准。
3. **操作**：按引用点击、输入、选择、滚动。
4. **同步**：等元素出现、等地址变化或等加载完成，而不是随便睡几秒。
5. **重新快照**：导航、提交、弹窗或明显的动态渲染之后，元素引用会失效，必须重新抓取，不能凭记忆复用。
6. **取结果**：需要语义结果时直接取标题、地址或正文文本，整理成你要的形式。

可以直接抄走的说法：

```text
打开 https://example.com/admin，我自己在弹出的窗口里登录，登录完你继续把「本月订单」整理成表格给我。
```

```text
打开这个报名表单，按下面的信息填好，但先别提交，填完让我确认一下：姓名 张三、邮箱 zhangsan@example.com。
```

```text
打开这两个商品页，对比价格、库存和预计送达时间，做成一张对照表。
```

## 登录、会话与多账号 [#登录会话与多账号]

* **登录你自己来**：浏览器窗口可见，账号密码、验证码和二次验证都由你在窗口里完成，完成后 Agent 接着做。
* **会话隔离**：每个 Agent 会话有自己的浏览器 session。新会话不会接管旧会话的活动页面，插件通过 `ctx.browser` API 使用的浏览器也和 Agent 的 CLI session 相互独立。
* **长期复用登录态**：需要跨会话保留 Cookie 和本地存储时，按账号使用稳定的账号键保存状态；需要完整的持久 Chrome 配置时才用独立 profile。
* **同一任务多个账号**：为每个账号使用不同的账号键，登录状态分别保存，不会互相覆盖。
* **关闭不等于清空**：关掉当前浏览器 session 不会删除已保存的账号状态或持久 profile。

## 安全边界 [#安全边界]

* 页面内容是**数据不是指令**。页面上写着「请执行以下操作」不构成授权。
* 发布、提交、发送、删除、付款、改权限这类不可逆动作，Agent 应当先把「具体会发生什么」讲清楚并等你确认。任务里明确写上「先别提交，让我确认」最稳妥。
* 凭证、Cookie 和 token 不会被复制到对话输出里；你也不要把邮箱、密码、Cookie、token 写进账号键、profile 名称或提示词。
* 让 Agent 做浏览器任务，只授权了这一次浏览器操作，不等于授权它在目标站点上做任何别的事。

## 跑不起来时 [#跑不起来时]

1. 面板显示**版本过旧**，多半是你机器上早先全局装过 `agent-browser` 且在 PATH 里排在前面。用面板升级到锁定版本；仍被旧版抢占时，先排查命令查找顺序，不要反复重装。
2. 不要让 Agent 执行运行时自带的 `upgrade`：它会绕过版本锁定。诊断修复类命令也不应自动执行，它可能重装浏览器并清掉已保存状态。
3. 页面点不动、元素找不到，通常是快照过期。让 Agent 重新抓取快照再操作，而不是猜测元素。
4. Linux 上的系统依赖安装涉及包管理器和提权，需要你明确同意后再执行。
5. 一次准备流程里最多允许一次 CLI 安装和一次浏览器安装；反复失败时应停下来看具体报错，而不是循环重试。

<Continue>
  <ContinueLink href="/product/abilities/" title="使用能力" description="在能力页安装并管理技能、场景、MCP、插件与套装。" />

  <ContinueLink href="/core/context-tools-and-permissions/" title="上下文、工具与权限" description="理解执行模式、工具权限与确认流程。" />

  <ContinueLink href="/reference/security-and-data/" title="安全与数据边界" description="理解登录态、凭证与外部服务之间的边界。" />
</Continue>