Our review

Automates a real browser to open web pages, interact with elements (click, fill), take screenshots, and extract JavaScript-rendered content.

Strengths

Real browser interaction handling dynamic JS rendering.
Provides interactive snapshot with refs for precise actions.
Maintains session state across commands without context loss.
Structured JSON output for easy integration.

Limitations

Requires prior installation of the agent-browser CLI tool.
Only supported on Linux (per declared compatibility).
Does not replace agent-search for simple information retrieval.

When to use it

Use when you need full browser interaction (click, form) or JavaScript-rendered content that static reading cannot provide.

When not to use it

Avoid for simple public information searches or static pages; prefer agent-search instead.

Examples

Open a page and get interactive snapshot

Open https://example.com and show me all clickable elements with their refs.

Click a button and capture the result

Go to https://example.com/form, click the button with ref @e2, then take a screenshot of the page.

Fill a form and submit

Navigate to https://example.com/login, fill the username field @e1 with 'testuser', fill the password field @e2 with 'password123', then click the submit button @e3.

name: "agent-browser" description: "浏览器自动化 workflow：打开网页、获取可交互 snapshot、点击、填写表单、截图与读取 JS 渲染内容。用户需要真实 browser interaction、DOM refs、页面操作或截图时使用。" compatibility: "linux" allowed-tools: "exec_command" metadata: hypo.category: "pure" hypo.backend: "exec" hypo.exec_profile: "cli-json" hypo.triggers: "browser,浏览器,网页,页面,网页交互,网页操作,点击,点一下,按钮,链接,表单,截图,打开网页,js渲染,dom,页面元素,snapshot" hypo.risk: "medium" hypo.dependencies: "agent-browser" hypo.cli_package: "agent-browser" hypo.cli_commands: "agent-browser" hypo.io_format: "json-stdio"

Agent Browser 使用指南

定位 (Positioning)

agent-browser 是真实浏览器自动化 workflow，用于打开网页、读取 JS 渲染后的页面内容、生成带 ref 的交互式 snapshot、执行点击/填写/等待/截图等动作。

适用场景 (Use When)

用户需要真实 browser interaction，而不是普通网页搜索。
页面依赖 JavaScript 渲染，agent-search 或直接 web_read 不够用。
用户要点击按钮、填写表单、等待页面状态变化、抓取交互元素或截图。

与 Agent Search 的边界

普通公开信息检索、事实核验、读静态页面，优先使用 agent-search。
只有当需要真实浏览器状态、页面交互、DOM refs 或 screenshot 时，才切到 agent-browser。

工具与接口 (Tools)

通过 exec_command 调用 agent-browser CLI。
默认所有 inspect 类调用都加 --json，这样 stdout 返回结构化 JSON。
同一轮浏览器任务中，使用稳定的 --session <name> 维持页面状态；推荐值如 --session agent-browser.
常用命令模板见 references/command-patterns.md。

标准流程 (Workflow)

先用 agent-browser --json --session <name> open <url> 打开页面。
再用 agent-browser --json --session <name> snapshot -i 获取可交互元素和 ref。
后续点击、填写、获取文本、截图等操作都复用同一个 --session。
页面较慢时，先调用 wait，再做 snapshot 或后续动作。
输出时总结关键页面状态和操作结果，不要直接堆完整 JSON。

参数约定 (Parameters)

打开页面： agent-browser --json --session <name> open <url>
获取交互式 snapshot： agent-browser --json --session <name> snapshot -i
点击 ref： agent-browser --json --session <name> click @e2
填写输入框： agent-browser --json --session <name> fill @e3 "value"
读取文本： agent-browser --json --session <name> get text @e1
截图： agent-browser --json --session <name> screenshot <path>

边界与风险 (Guardrails)

不要用 shell chaining，例如 &&；每一步用单独的 exec_command，靠 --session 维持浏览器状态。
默认保持 read-first。未经用户明确要求，不要提交表单、下单、登录、删除内容或触发其他破坏性动作。
页面交互前优先先做 snapshot -i，不要盲点选择器。
涉及登录态、cookie、下载文件或跨站操作时，要明确说明风险和当前步骤。

Browser Automation

Recommended for