别再把浏览器当黑盒：agent-browser 如何让 AI Agent 的网页操作可观测、可重播

AI Agent 真正走出聊天介面后，很快就会遇到一个不容易被 demo 呈现的问题：浏览器不是一组稳定的 API，而是一个会变动、会载入、会被登入状态影响的互动环境。代理程式必须先理解页面，再决定要点哪个按钮、填哪个栏位，最后还要能证明操作确实完成。若流程只依赖座标或一长串 CSS selector，网站一改版，整个自动化就可能静默失效。

vercel-labs/agent-browser 提供的是一条偏工程化的路线：用 CLI 把浏览器能力包装成适合 AI Agent 呼叫的操作介面，再用 Accessibility Snapshot 将页面转成较容易推理的结构化文字。专案目前是实作型工具，不是教学素材或资源清单；它的价值在于把「代理程式如何安全、可观测地操作浏览器」拆成一组可以被脚本、模型与测试流程重复使用的原语。

一、它解决的不是「能不能点」，而是「代理程式能不能稳定地点」

传统浏览器自动化常见的写法，是先找出一个 selector，再呼叫 click、fill 或 press。这种方法在固定测试页面上很直观，但对 AI Agent 而言有三个问题。第一，selector 需要事先知道 DOM 细节；第二，模型看到的画面与程式实际使用的 selector 之间缺少共同语言；第三，当页面有重复元素、延迟载入或重新渲染时，错误讯息通常只告诉你「找不到」，不告诉你当下页面究竟长什么样子。

agent-browser 的核心互动模式是先执行 snapshot，取得页面 Accessibility Tree 的文字表示，再从输出中的短 ref 指向元素。例如，模型可以先读到一个带有 @e1、@e2 等参照的页面快照，接着使用 click @e1、fill @e2 "..." 或 get text @e3。这个设计把「观察」和「行动」分开：每次行动都能回溯到当时的页面语意，而不是只留下某个难以解释的 selector。

这不代表 selector 完全消失。专案仍支援 CSS、role、text、label 等常见定位方式，适合人类已经知道目标结构的脚本。差别在于，Accessibility Snapshot 与 ref 提供了更适合代理程式的预设路径：先看可操作的语意，再选择行动目标。

二、CLI 与 daemon：把浏览器程序和代理程式解耦

agent-browser 的命令列介面可以直接让人类或另一个程序执行浏览器操作；对需要大量短命令的 Agent 工作流来说，专案也提供常驻 daemon 模式。命令端不必每次都重新建立整个浏览器程序，而是透过本机服务与既有的浏览器 session 沟通。这个分层很重要，因为模型呼叫通常是许多小步骤的序列：开页、等待、读快照、填栏位、送出、验证结果。

从工程角度看，daemon 让「浏览器生命周期」不再和「单次命令生命周期」绑死。代理程式可以在同一个 session 中保留 cookies、localStorage 与目前分页，减少反复登入与初始化的成本；测试或 CI 也能用明确的 session 名称隔离不同任务。当某个工作流需要并行处理多个帐号或多个网站时，session 隔离比把所有状态混在一个全域浏览器中更容易诊断。

这个设计也带来一个必须正视的边界：daemon 是有权限的本机自动化入口。实际部署时，应把它限制在需要的网路介面与执行环境，避免把未经保护的控制端点暴露到公网；对登入状态、Cookie、下载档与 session state 则应采取最小权限和独立保存策略。工具提供能力，不会自动替你完成威胁模型。

三、从快照到验证：一个可重播的代理程式工作流

一个实用的 agent-browser 流程，不应只是「点击成功」就结束，而应该包含观察、操作与验证三段：

1. 建立隔离 session 并开启目标页面。 对需要登入的流程，先确认 session 是否是预期的帐号与环境。

1. 取得 snapshot。 让模型或脚本看到当下可互动元素，而不是直接猜 selector。

1. 用 ref 执行最小动作。 每次只做一个明确的 click、fill、press 或 select，并保留命令输出。

1. 重新观察结果。 表单送出、页面转址或弹窗出现后，再取得一次 snapshot 或读取特定文字。

1. 保存证据与状态。 对需要后续接续的任务，保存 storage state；对需要稽核的任务，保存关键输出、URL 与截图。

这种工作流的重点是「行动后再观察」，而不是假设网站一定按照预期改变。对模型而言，这也形成一个简单的控制回圈：取得环境状态、提出下一个工具呼叫、读取结果、修正计划。它比一次生成十几个步骤的长脚本更容易在中途恢复。

四、为什么 Accessibility Snapshot 对 AI Agent 特别有用？

Accessibility Tree 并不是完整 DOM 的替代品，而是以角色、名称与状态描述使用者可操作的介面。对语言模型来说，这种输出通常比压缩后的 HTML 更接近任务语言：按钮有名称，输入栏位有 label，连结有可读文字，元素还可以透过 ref 被后续命令引用。

更重要的是，snapshot 是一种可检查的中介表示。开发者可以把它记录到测试产物，确认模型到底看见什么；如果操作选错，也能回头检视当下的页面结构。当网站使用大量动态元件时，这种「先把观察结果固定下来」的做法，有助于区分是模型推理错误、页面尚未稳定，还是定位策略本身不可靠。

不过，Accessibility Snapshot 也不应被神化。若网站没有正确提供语意标签，快照仍可能不完整；如果元素在操作后重新生成，旧 ref 也可能失效。因此稳定流程需要在页面重大变更后重新 snapshot，并对关键结果增加文字、URL、元素状态或截图验证。

五、MCP 与脚本介面：同一套能力接上不同 Agent

专案同时提供适合命令列工作流的 CLI，以及可供 MCP 客户端使用的整合方式。这让浏览器能力可以被放进不同的 Agent 架构：简单任务可由 shell 脚本串接；需要工具发现与结构化呼叫的代理程式，则可透过 MCP 使用同一套浏览器操作。

这里的关键不是「多一个协定」而已，而是把浏览器操作从某个特定模型的 prompt 技巧，提升成可被替换与测试的工具层。你可以先用 CLI 在终端机重现一个失败案例，再把相同步骤接到 MCP Agent；也可以在不改变浏览器控制核心的情况下，替换上层的规划器或模型。

但 MCP 工具描述越完整，代理程式可执行的动作也越多。部署时仍应限制可存取的网域、档案路径与凭证范围，并把高风险操作，例如付款、删除、寄信或提交正式表单，设计成需要人类确认的门槛。

六、安装与第一个可验证的操作

专案 README 提供 npm 安装与直接执行的方式。实际导入前，先确认 Node.js 环境、浏览器依赖与执行权限，再用一个不含敏感资料的测试页面验证。最小流程可以抽象成以下形式：

# 安装 CLI（实际版本请以专案 README 为准）
npm install -g agent-browser
# 首次下载 Chrome；Linux 可连同系统依赖一起安装
agent-browser install
# agent-browser install --with-deps
# 启动浏览器并开启测试页
agent-browser open https://example.com
# 取得可操作的页面快照
agent-browser snapshot
# 依 snapshot 中的 ref 执行操作
agent-browser click @e1
# 操作后再次观察并验证
agent-browser snapshot

上面的 @e1 只是示意，不能在没有查看实际 snapshot 的情况下照抄。更可靠的自动化程式会解析命令输出、确认 ref 仍属于目前页面，并在操作后检查预期文字或 URL。若使用 session state，请把 state 档案视为凭证处理，不要提交到 Git，也不要放进公开的 CI artifact。

七、把它放进测试与生产工作流前，先补上这些护栏

权限隔离。 用专用浏览器 profile 和最低权限帐号执行，将测试、预览与正式环境分开。

网路限制。 对 Agent 能开启的网域建立 allowlist；若工具执行在伺服器上，避免将控制端点直接绑到公网介面。

可观测性。 保留命令、URL、snapshot 摘要、错误讯息与必要截图，但先排除 Cookie、Token、个人资料与表单秘密。

幂等性。 对提交、付款、删除等不可逆动作，先做 dry run 或预览，并用唯一识别码避免重复执行。

失败恢复。 将长流程切成可重试的阶段；每个阶段都重新观察页面，而不是盲目重播旧 ref。

版本固定。 在 CI 或生产环境锁定套件版本，并以一组代表性页面做 smoke test。浏览器版本、网站改版与 Accessibility Tree 变化，都可能影响代理程式行为。

结语：浏览器是工具，但快照才是代理程式的观察界面

agent-browser 值得注意的地方，不只是它能替 AI Agent 按钮或填表单，而是它把浏览器自动化整理成一个可观察、可分段、可验证的控制回圈：CLI 负责可组合性，daemon 负责持续 session，Accessibility Snapshot 负责把画面转成可推理的语意，ref 负责把观察和行动连起来，state 与输出则让流程有机会重播与稽核。

对想把 Agent 从展示推进到实际工作流的团队，这种介面比「让模型自己猜 selector」更值得测试。不过导入成功的关键，仍然是把权限、网路、敏感资料与不可逆操作放进系统设计，而不是把所有责任交给模型。若你的下一个 AI 工作流需要操作真实网站，agent-browser 是一个值得用小型、低风险场景开始评估的开源候选。

参考资料

专案首页：https://github.com/vercel-labs/agent-browser
README 与安装说明：https://github.com/vercel-labs/agent-browser/blob/main/README.md
npm 套件页面：https://www.npmjs.com/package/agent-browser