企业官网建设流程全解析

OpenHands Software Agent SDK（software-agent-sdk）内置的Browser Use 工具集（BrowserToolSet）能让 AI Agent 像人一样打开浏览器：导航网页、点击按钮、输入文字、提取内容，甚至录制完整的浏览过程。对于需要 Agent 自动调研文档、抓取动态页面、操作 Web 界面的场景，这套 Browser Use 工具开箱即用，无需自己写爬虫。

本文将带你快速了解这套工具的 14 个浏览器动作、接入方法以及会话录制等进阶功能。

一、Browser Use 工具是什么？

Browser Use 工具位于 openhands-tools/openhands/tools/browser_use/ 目录，核心实现包括：

• definition.py：定义全部 14 个浏览器工具的参数 Schema 与说明
• impl.py：执行器BrowserToolExecutor，负责启动 Chromium 浏览器并管理会话生命周期
• server.py：封装 browser-use 浏览器自动化服务
• recording.py：基于 rrweb 的会话录制功能

工具集对外只暴露一个入口：BrowserToolSet。注册它之后，Agent 就能同时获得下面所有浏览器动作，无需逐个添加。

内置的 14 个浏览器动作一览

几个值得注意的设计：

• 截图能力：每次操作的观测结果（BrowserObservation）都可携带 Base64 截图，自动保存到.agent_tmp/browser_observations目录，让多模态模型"看到"页面。
• 自动故障恢复：连续失败 3 次后会自动重置浏览器会话；每次动作默认 300 秒超时，避免 Agent 卡死（见 impl.py）。
• 共享浏览器实例：父 Agent 和子 Agent 复用同一个 Chromium/CDP 实例，避免端口冲突。

二、快速上手：3 行代码接入 Browser Use 工具

1. 环境准备

Browser Use 工具依赖 Chromium 内核浏览器。如果系统尚未安装，会看到提示：

Chromium is required for browser operations but is not installed. 1. Using uvx (recommended): uvx playwright install chromium --with-deps --no-shell 2. Using pip: pip install playwright && playwright install chromium

推荐用第一条uvx命令，一条即可装好。工具也会自动探测系统中已有的 Chrome / Edge / Chromium，优先使用完整安装的浏览器（探测逻辑见 impl.py 中的check_chromium_available）。

2. 最小可运行示例

参考官方示例 examples/01_standalone_sdk/15_browser_use.py，接入的核心思路只有三步：配好 LLM → 把BrowserToolSet加进工具列表 → 发起对话：

from openhands.sdk import LLM, Agent, Conversation from openhands.sdk.tool import Tool from openhands.tools.browser_use import BrowserToolSet llm = LLM(usage_id="agent", model="gpt-5.5", api_key="...") agent = Agent( llm=llm, tools=[Tool(name=BrowserToolSet.name)], # 一行接入全部 14 个浏览器动作 ) conversation = Conversation(agent=agent, workspace=".") conversation.send_message("打开 openhands.dev 的 blog 页面，总结最新一篇博文的要点") conversation.run()

运行后，Agent 会自动规划出"导航 → 查看状态 → 提取内容 → 回答"的完整流程。完整可运行版本（含终端、文件编辑工具）见 15_browser_use.py。

3. 在 Docker 沙箱中运行（更安全）

本地运行浏览器有一定风险，官方推荐将 Agent 放进 Docker 沙箱。参考 examples/02_remote_agent_server/03_browser_use_with_docker_sandboxed_server.py：使用DockerWorkspace启动远程 Agent Server 容器，再用get_default_agent(cli_mode=False)创建 Agent——cli_mode=False会默认启用浏览器工具（默认工具集的开关逻辑见 openhands-tools/openhands/tools/preset/default.py）。

三、Agent 是如何"看"和"操作"网页的？

理解下面这个核心循环，就能看懂 Agent 的每次浏览行为：

browser_navigate → browser_get_state → browser_click / browser_type ↑ │ └──────── 每次操作后再 get_state ─────────┘

• 元素编号制：browser_get_state会把页面上所有可交互元素（按钮、链接、输入框）编号列出，Agent 通过index编号来点击或输入，而不是脆弱的 CSS 选择器。
• 强制先观察再操作：SDK 会自动给 Agent 注入一段浏览器行为指引（BROWSER_PROMPT_GUIDANCE），要求"每次点击或输入前必须先 get_state"，因为元素编号会随每次操作变化。
• 正文提取更干净：browser_get_content返回过滤过噪音和广告的 Markdown 正文，长内容被截断时可用start_from_char继续读取。
• 内置行为护栏：指引中明确规定——子任务最多 10 次浏览器操作、遇到验证码/登录墙最多尝试一次替代方案就放弃、未明确授权不得提交表单或注册账号，防止 Agent 失控乱点。

四、进阶能力：会话录制与登录态复用

用 rrweb 录制 Agent 的浏览过程

想复盘"Agent 到底点了什么"？调用browser_start_recording开始录制即可。录制会捕获 DOM 变化、鼠标移动、点击、滚动等全部交互，事件以编号 JSON 文件形式保存到.agent_tmp/browser_observations/recording-<时间戳>/，之后可用 rrweb-player 回放整个浏览过程。完整演示见 examples/01_standalone_sdk/38_browser_session_recording.py。

复用登录态

browser_get_storage可以导出当前会话的 Cookies、localStorage 和 sessionStorage；browser_set_storage能反过来恢复这些状态。这对"登录后操作内网系统"类任务非常实用。执行器还支持allowed_domains域名白名单和session_timeout_minutes会话超时，进一步收敛 Agent 的活动范围（见 impl.py 中BrowserToolExecutor的构造函数）。

五、把它交给子 Agent：内置 web-researcher

SDK 内置了一个浏览器子 Agent——web-researcher（定义见 openhands-tools/openhands/tools/preset/subagents/web_researcher.md）。它同时装备了 Tavily 搜索、fetch 抓取和 Browser Use 三套联网工具，遵循"先搜索、再抓取、最后才动浏览器"的递进策略，遇到 403/验证码会果断换路径，并始终在结论中附上来源 URL。当主 Agent 需要调研公开资料时，可以把任务委派给它，而不用自己操心浏览细节。

六、常见问题速查

Q：提示 Chromium not installed？运行uvx playwright install chromium --with-deps --no-shell，重启应用即可。

Q：浏览器启动失败会影响整个对话吗？不会。BrowserToolSet.create()捕获了启动异常，浏览器不可用时 Agent 会降级为"没有浏览器工具"继续工作（见 definition.py 中的create方法）。

Q：动作一直超时而卡住？默认单次动作超时 300 秒、会话超时 30 分钟，均可通过执行器参数调整；连续失败 3 次后浏览器会自动重建。

Q：如何只允许访问特定网站？创建执行器时传入allowed_domains=["example.com"]做域名白名单限制。

七、小结

一句话总结：OpenHands SDK 的 Browser Use 工具集 =一个BrowserToolSet注册 + 14 个开箱即用的浏览器动作 + 截图、录制、护栏等完整配套。无论是简单的网页信息提取，还是复杂的 Web 界面自动化，都可以通过它让 AI Agent 真正"动手"浏览网页。