agent-browser

概览

agent-browser 是什么？

agent-browser 是一款为运行在 inference.sh 平台上的 AI agent 设计的浏览器自动化技能。它在底层使用 Playwright，并提供一个简单的、基于 JSON 的接口，让 agent 可以：

• 在真实浏览器中打开并导航网页
• 使用稳定的 @e 引用与页面元素交互
• 执行点击、输入、拖拽放置、上传文件等操作
• 抽取结构化数据，用于抓取和研究
• 捕获会话截图并录制视频

你无需手写 Playwright 代码，而是通过 infsh CLI（或者能运行 Bash 命令的 agent）调用 agent-browser。该技能负责协调浏览器会话，返回对页面的机器友好描述，并让你的 agent 以逐步方式驱动交互。

agent-browser 适合谁？

agent-browser 主要面向：

• 开发者：将 AI agent 接到真实网站
• 自动化工程师：需要可重复的浏览器工作流
• 数据与研究团队：进行有针对性的 Web 抓取或基于 UI 的研究
• 工作流构建者：使用 inference.sh 作为编排层

当你已经在用，或愿意使用 inference.sh，并希望浏览器成为一个可控、可由 agent 访问的工具时，agent-browser 会非常合适。

它解决哪些问题？

agent-browser 帮助你处理常见的浏览器自动化任务：

• 自动化登录、导航和表单流程
• 抓取需要交互的结构化内容（搜索表单、筛选器、分页等）
• 在线上站点上运行类似“测试”的 agent 驱动流程
• 录制自动化浏览会话的视频，便于回放和审查

它屏蔽了直接编写 Playwright 脚本的复杂度，为 agent 提供了一组基于 @e 元素引用的更高层动作，从而在多步交互中保持稳定性。

什么时候适合使用 agent-browser？

在以下场景适合使用 agent-browser：

• 你通过 inference.sh 运行 agent，并需要它们浏览网页
• 你想要 Playwright 级别的稳定性，但不想写 Playwright 代码
• 你的流程主要由“打开页面—操作元素—读取结果”构成

在以下情况，它可能不太合适：

• 你无法使用 infsh CLI 或类 Bash 工具
• 你需要技能未暴露的极度定制化 Playwright 特性
• 你的场景完全是 API 调用，不需要真实浏览器

如果你需要对浏览器内部或前端框架进行非常细粒度的控制，并且这些能力超出了该技能的暴露范围，那么直接编写 Playwright 脚本可能更合适。对于多数由 agent 驱动的自动化场景，agent-browser 提供了一个更简单、更高层的接口。

使用方法

前置条件

在使用 agent-browser 之前，请确保你具备：

• 一个可以运行 Bash 命令的环境
• 已安装 inference.sh CLI（infsh）
• 一个可以从 CLI 登录的 inference.sh 账户

该技能的 Quick Start 明确依赖 infsh CLI。你可以按照仓库中的官方安装说明进行安装：

• CLI 安装文档：https://raw.githubusercontent.com/inference-sh/skills/refs/heads/main/cli-install.md

当 infsh 安装并配置完成后，你可以在终端中调用 agent-browser 技能，或者从任何可以运行 infsh 命令的 agent 工具中调用它。

安装与技能激活

agent-browser 作为 inferen-sh/skills 仓库的一部分进行分发。在大多数基于 inference.sh 的环境中，你无需安装单独的 npm 包；只需确认技能可用，然后通过 infsh 调用即可。

典型配置步骤：

1. 安装 inference.sh CLI
   • 按照仓库中的 cli-install.md 文档操作。
2. 身份验证
   • 运行：

     infsh login
     

   • 根据提示完成与 inference.sh 的登录认证。
3. 确认技能可用性
   • 确认你的 inference.sh 环境可以访问 inferen-sh/skills 仓库中 tools/utilities/agent-browser 下的 agent-browser app/skill。

如果你接入的是支持 npx skills add 的更大“skills”生态，也可以将该仓库配置为来源，但对 agent-browser 来说，官方推荐的使用方式是通过 infsh app run。

核心浏览器自动化工作流

该技能文档描述了一个稳定的四步模式：

1. Open – 启动浏览器会话并导航到某个 URL。
2. Interact – 使用返回的 @e 元素引用进行点击、输入、拖拽或上传。
3. Re-snapshot – 在导航或 DOM 变化后请求新快照，获取新的 @e 引用。
4. Close – 结束会话；如果启用录制，可在此阶段获取视频。

通过这个模式，你的 agent 可以保持对页面状态的“心智模型”。每次调用都传入 JSON 输入，收到结构化 JSON 输出，然后将其反馈给 agent 的推理循环。

快速上手示例

想要快速体验 agent-browser 打开单页的效果，可以按照仓库中的 Quick Start 模式操作：

infsh login

# 打开页面并获取可交互元素
infsh app run agent-browser --function open --input '{"url": "https://example.com"}' --session new

上述命令会：

• 通过 --function open 指示 agent-browser 在指定 URL 上启动新的浏览器页面。
• 使用 --session new 创建一个新会话，后续操作可以复用同一浏览器状态。
• 技能返回的 JSON 通常包含元素描述和 @e 引用，你的 agent 可以在后续 interact 调用中使用这些引用。

使用 @e 元素引用

agent-browser 的核心特性之一是使用 @e 引用。技能不会要求你提供 CSS selector 或 XPath，而是返回类似 @e:button-1 这样的句柄（具体格式取决于实现），并附带对该元素的可读描述。

你的 agent 通常会：

1. 读取元素列表及其描述。
2. 选择合适的 @e 引用（例如标注为 “Search” 的按钮）。
3. 使用该 @e 引用调用相应的交互函数（如 click 或 fill）。

这种设计针对 AI agent 做了优化：agent 可以基于描述进行推理，而不必了解底层 DOM 细节。同时，只要描述仍然可理解，即使底层 selector 发生变化，交互仍然较为稳健。

示例：打开、点击并重新快照

一个典型的多步流程大致如下（仅为模式示意，请根据实际函数名调整）：

# 1. 启动会话并打开页面
OPEN_RESULT=$(infsh app run agent-browser \
  --function open \
  --session new \
  --input '{"url": "https://example.com"}')

# 2. 在你的 agent 逻辑中，从 OPEN_RESULT 中选择一个 @e 引用（例如 @e:search-button）
# 3. 对该元素进行交互
INTERACT_RESULT=$(infsh app run agent-browser \
  --function interact \
  --session "$INF_SH_SESSION" \
  --input '{"action": "click", "element": "@e:search-button"}')

# 4. 点击后重新快照，获取更新后的元素列表
SNAPSHOT_RESULT=$(infsh app run agent-browser \
  --function snapshot \
  --session "$INF_SH_SESSION" \
  --input '{}')

open 之外的函数名称可能会有变化，因此务必查看 tools/utilities/agent-browser 中的最新 SKILL.md 以及相关文档，以获取准确的函数签名和输入 schema。

截图与视频录制

agent-browser 可以捕获浏览会话的可视化记录：

• 截图（Screenshots） – 便于调试 agent 行为或保存可视化确认。
• 视频（Video） – 在开启录制并关闭会话时，技能可以返回或提供完整自动化流程的视频文件链接。

这些能力通过技能的输入选项进行配置。关于如何开启录制以及如何获取输出，请参考仓库中 tools/utilities/agent-browser 下的 SKILL.md 定义及任何补充文档。

与 agent 和工作流集成的小贴士

要在自动化或研究工作流中充分利用 agent-browser，建议：

• 持久化 --session ID：确保你的 agent 在多次调用间保存会话标识，以便在同一浏览器中连续执行多个动作。
• 仔细解析 JSON 输出：在 agent 运行环境中使用可靠的 JSON 解析；元素列表和元数据通常较为丰富。
• 必要时节流交互：对于加载较慢或高度动态的页面，尽量通过技能支持的配置，让 agent 在步骤间等待元素出现，避免过快操作。
• 记录关键操作日志：如果需要审计或调试浏览行为，建议记录 open、interact 和 close 调用及其关键参数。

常见问题（FAQ）

agent-browser、inference.sh 和 Playwright 之间是什么关系？

agent-browser 是运行在 inference.sh 生态中的一个技能。当你通过 infsh app run 调用它时，它会使用 Playwright 作为底层浏览器自动化引擎。你无需直接调用 Playwright；而是通过更高层的技能函数和 @e 元素引用进行操作。

我该如何安装 agent-browser？

你无需将 agent-browser 安装为独立的二进制或 npm 包。请按以下步骤操作：

1. 使用官方 cli-install.md 文档安装 inference.sh CLI（infsh）。
2. 通过 infsh login 登录。
3. 确认你的环境可以访问 inferen-sh/skills 仓库中 tools/utilities/agent-browser 路径下的 agent-browser 技能。

完成上述步骤后，即可通过 infsh app run agent-browser 直接调用该技能。

使用 agent-browser 是否需要编程经验？

建议至少具备基础的命令行和 JSON 使用经验。你不需要编写 Playwright 脚本，但应当熟悉：

• 运行 infsh 命令
• 通过 --input 传递 JSON
• 在你的 agent 或脚本中解析 JSON 输出

如果要构建更复杂的工作流（条件逻辑、循环、错误处理等），具备通用脚本或编程能力会非常有帮助。

我可以在 inference.sh 之外使用 agent-browser 吗？

该技能专为 inference.sh 使用而构建，并被描述为“Browser automation for AI agents via inference.sh”。官方和受支持的运行方式是通过 infsh CLI。如果你需要一个独立库，可能更适合直接在自己选用的语言中使用 Playwright。

agent-browser 适合大规模 Web 抓取吗？

agent-browser 可以用于有针对性的抓取，尤其适合需要交互或依赖 JavaScript 渲染的页面。但对于非常大规模的高频抓取，你需要重点考虑：

• inference.sh 账户配额和计费
• 对目标站点服务条款和 robots.txt 的合规性
• 性能、并发和限流策略

对于小规模或嵌入在 agent 工作流中的定向抓取，agent-browser 十分适合；而在需要跨大量站点进行大规模爬取时，更专门的抓取技术栈可能更合适。

会话管理是如何工作的？

会话管理通过调用 infsh app run 时的 --session 标志控制。典型模式是：

• 初次调用 open 时使用 --session new
• 在后续 interact 和 snapshot 调用中复用同一个会话 ID
• 通过相应的 close 函数关闭会话，并在需要时获取视频

请始终参考当前的 SKILL.md 以获取与会话管理相关的具体选项和输出说明。

我在哪里可以查看完整的函数和输入规格？

agent-browser 的权威参考文档位于仓库中：

• inferen-sh/skills 仓库根目录下的 SKILL.md
• tools/utilities/agent-browser 目录中的实现细节、示例和补充文档

你可以打开这些文件，查看当前可用的函数列表、预期的 JSON 输入以及输出格式，然后据此设计你的 agent 或脚本。