agent-browser 把浏览器操作组织成“观察页面、选择元素、执行操作、再次检查”的循环。先为 Agent 安装入口，再准备 CLI 与浏览器，才能真正操作页面。
安装与准备
在终端完成运行环境与 Skill 安装：
npm install -g agent-browser
agent-browser install
npx skills@latest add vercel-labs/agent-browser
准备 Node.js、能执行终端命令的 Agent 和可访问的目标页面。以下在终端安装 CLI、浏览器和 Skill；仅安装最后一行不会完成前面的运行环境准备。Linux 缺少系统库时，按官方安装文档处理依赖。
第一次使用
以下内容发到 Agent 对话中，替换成自己的文件和目标：
请使用 agent-browser 检查本地 http://localhost:3000 的课程预约流程。先读取已安装 CLI 的 core 指南；运行 `agent-browser session id --scope worktree --prefix course-check` 取得会话 ID，每条浏览器命令都用 `--session` 指向同一 ID，最后以 `agent-browser --session <ID> close` 关闭该会话，其中 `<ID>` 换成刚生成的同一 ID。检查选课、填写表单和返回修改，不提交真实付款；保存失败步骤和最后截图。
读取当前版本的操作指南
仓库里的 Skill 是发现入口，完整操作说明由 CLI 提供。让 Agent 先运行 agent-browser skills get core --full，再按当前版本选择会话、打开页面。升级 CLI 后也应重新读取，以免沿用旧参数。
根据当前快照操作
页面打开后先读取可交互元素，按实际标签和编号定位课程、按钮和表单。填写之后如果出现新的选项或错误提示，应重新获取快照；旧编号可能已经不对应原来的元素。等待明确的文字或页面状态，比固定等待几秒更可靠。
把操作结果变成可复查记录
预约检查需要说明在哪个步骤失败、输入了什么测试值、预期与实际有什么差异。截图用于定位问题，提取文本用于说明状态。结束后关闭本次命名会话，避免后续任务沿用错误页面或临时表单内容。
不经过 Agent，也能先跑最小闭环
CLI 和浏览器装好后，在目标项目目录的同一终端运行下面整段，用公开测试页熟悉三个动作：
COURSE_CHECK_SESSION="$(agent-browser session id --scope worktree --prefix course-check)"
agent-browser --session "$COURSE_CHECK_SESSION" open https://example.com
agent-browser --session "$COURSE_CHECK_SESSION" snapshot -i
agent-browser --session "$COURSE_CHECK_SESSION" screenshot example.png
agent-browser --session "$COURSE_CHECK_SESSION" close
在同一终端运行整段命令，让每一步使用同一个命名会话；如果 Agent 每次新开 Shell，就保存生成的 ID，并在每条命令中显式指定 --session。真正操作表单时，从 snapshot -i 输出里选当前页面的元素引用，例如 @e3；点击或填写后再次快照，必要时用 agent-browser --session "$COURSE_CHECK_SESSION" wait --text "成功" 等待具体状态。截图路径是本机文件，需要打开检查。官方 core 指南还包含 read、文本提取、多标签页和无障碍检查等命令，可按任务再学，不必第一次就把每种能力都塞进同一流程。
填写表单后，读回目标字段
先辨认当前快照中的控件：可编辑文本框用 fill，原生 HTML <select> 下拉框用 select，勾选框用 check。combobox 角色也可能来自自绘组件；这类菜单应按页面交互展开、重新快照再选择选项，不能仅凭角色判断能用 select。[8]
FredAmartey 在 agent-browser 0.38.2、headless Chrome 147 的问题报告中展示：对非文本控件误用 fill / type，终端显示完成，内容却进入此前获得焦点的文本框。[7] 在已打开的测试表单中，可以这样核对一个文本框：
agent-browser --session "$COURSE_CHECK_SESSION" fill @e3 "test@example.com"
agent-browser --session "$COURSE_CHECK_SESSION" get value @e3
把 @e3 换成当前文本框引用，沿用本任务的命名会话 ID。读回值应与测试输入一致；若填写触发页面重渲染，先重新快照再定位字段。选项和勾选状态也应从当前页面确认，之后再继续下一步。
登录、会话与失败现场
登录站点先确认账号授权和测试数据范围。默认未命名会话会与同机其他任务共享。CLI 默认各自启动浏览器时，不同命名 ID 会隔离页面和登录状态；若经 --cdp 连接同一个外部 Chrome，会话只分开标签选择，不能当成账号隔离。命名本身不保证关闭或重启后保留登录；需要继续使用登录状态时，按官方会话说明另行配置 --restore。要报告失败，记录目标 URL、上一次快照、执行的命令、预期文字与实际文字，再决定是否截图或录制；“点击命令返回成功”只说明操作发出，不说明业务动作完成。验证码、站点访问限制和权限不足属于真实边界，不能假设有头浏览器一定能绕过。
另一个场景：筛选后台订单
可把一次自动化限定成只读验证：“打开测试环境订单页，筛选‘待处理’，记录筛选前后结果数与第一条订单编号；再切到‘已完成’，确认状态确实变化。不要修改订单或触发通知。” Agent 应在每次筛选后重新取快照，再从当前页面提取文字；如果列表由异步请求更新，就等待结果状态，而非固定睡眠。交付物是操作顺序、实际看到的文字和必要截图。若无法登录或页面验证拦截，记录停在哪一步，不能从空页面推断没有订单。
浏览器启动或连接失败时，先诊断
CLI 已在 PATH，却遇到 Chrome 无法启动、连接失败或升级后的版本不匹配时，在终端运行：
agent-browser doctor --offline --quick
agent-browser doctor
第一行跳过网络探测与浏览器启动测试，需要检查这两项时再用第二行。退出码 0 表示没有 fail 项（仍可能有警告），1 表示至少一项检查失败。doctor 每次都会清理失效的守护进程辅助文件；额外加 --fix 可能安装缺失的 Chrome、删除过期状态；发现版本不匹配时，还可能关闭所有活跃会话。先读具体检查结果，再决定修复。[5] [9]
常见问题
安装 Skill 后提示找不到命令？ CLI 与 Skill 分开安装，先检查 agent-browser 是否在 PATH。
点击了错误元素？ 页面变化后重新观察，再使用新快照里的引用。
显示浏览器就能打开所有网站吗？ 不能，登录、验证码和网站访问规则仍可能阻止操作。