浏览器自动化中间件

浏览器自动化中间件让 ChatKit 客户端可以操作承载对话的浏览器页面。它把一组安全的 Playwright 风格页面动作暴露为客户端工具，让智能体能够查看当前页面、点击控件、填写表单、滚动、跳转、等待页面状态，并在 DOM 定位不足时通过截图和视口坐标继续操作。

中间件 provider 名称是 browser-automation。

​

适用场景

当智能体需要处理用户浏览器中打开的页面时，可以使用浏览器自动化中间件：

• 辅助用户操作 Web 应用、管理后台、仪表板或表单。
• 在行动前读取页面结构并选择目标元素。
• 填写搜索条件或业务表单，然后等待页面刷新。
• 操作 SAP/Fiori、iframe 较多或 DOM 标签不稳定的复杂企业页面。
• 与 ChatKit 浏览器扩展 配合使用。

​

工作方式

浏览器自动化中间件基于 ChatKit 客户端工具中间件实现：

1. 中间件向模型声明 host_page_* 工具。
2. 模型调用工具时，ChatKit 将请求发送到浏览器客户端。
3. 浏览器客户端执行页面操作并返回工具结果。
4. 中间件发出可读的工具调用消息，并把结果回灌到模型上下文。
5. 对于截图结果，中间件会把图片附加到下一次模型调用，并提供 host_page_pointer 的坐标换算提示。

它还会额外注入一个服务端等待工具 host_page_wait，用于在页面渲染、动画、跳转或异步请求后等待一段时间。

​

配置项

字段	类型	默认值	说明
allowNavigation	boolean	true	是否暴露 host_page_navigate，让智能体可以把宿主页面跳转到 HTTP(S) URL。不希望智能体离开当前页面时可关闭。

示例：

{
  "allowNavigation": true
}

​

客户端要求

浏览器自动化需要 ChatKit 客户端实现这些客户端工具调用。Xpert ChatKit 浏览器扩展已内置支持，并可优先使用 Chrome DevTools Protocol 获得更丰富的快照、截图和真实鼠标/键盘输入。其他 ChatKit 宿主可以使用 ChatKit JavaScript 仓库中的 host automation handler。

如果客户端没有实现某个工具，模型可能会收到失败的工具调用，或无法完成对应浏览器任务。

​

可用工具

工具	能力
host_page_snapshot	获取 URL、标题、视口、滚动位置、页面状态、可操作元素、表单标签、附近文本、可访问性摘要、命中测试信息和客户端能力。
host_page_click	使用 ref、axRef、角色/名称、文本、测试 ID、选择器或视口坐标点击目标。
host_page_fill	填写输入框、文本域或 contenteditable 元素。
host_page_press	按下 Enter、Escape、Tab、F8 等键。
host_page_select	在选择框中选择一个或多个值。
host_page_scroll	滚动页面或指定可滚动元素。
host_page_navigate	当 allowNavigation 开启时，跳转到 HTTP(S) URL。
host_page_hover	将指针悬停到目标元素。
host_page_focus	聚焦目标元素。
host_page_pointer	使用视口 CSS 坐标执行低层级指针动作。
host_page_screenshot	在客户端支持时截取页面截图，并把图片附加到下一次模型调用。
host_page_wait_for	在客户端等待目标变为 attached、visible、hidden 或 detached。
host_page_wait	在服务端等待 3 到 60 秒。

​

推荐智能体行为

为了提高浏览器任务稳定性，建议让智能体按以下顺序行动：

1. 先用 host_page_snapshot 理解页面并获取稳定的 refs。
2. 表单操作优先使用 host_page_fill、host_page_select 和 host_page_press。
3. 如果一次 DOM/ref 点击后页面没有变化，不要重复点击同一目标，改用 host_page_screenshot 和 host_page_pointer。
4. 页面跳转、动画、SPA 刷新或慢请求后使用 host_page_wait_for 或 host_page_wait。
5. 指针坐标是页面视口 CSS 像素，不是操作系统屏幕坐标，也不包含浏览器工具栏或 ChatKit 侧边栏。

​

截图处理

当 host_page_screenshot 返回图片数据时，中间件会压缩工具消息，并追加一个包含截图的新模型输入。如果截图包含视口尺寸和图片尺寸，中间件还会给模型坐标换算公式：

cssX = imageX / imageWidth * viewportWidth
cssY = imageY / imageHeight * viewportHeight

这对 DOM 或可访问性快照难以描述的可视化控件尤其有用。

​

排障建议

• 没有页面跳转工具：检查 allowNavigation 是否关闭。
• 智能体无法操作页面：确认 ChatKit 客户端实现了宿主页面自动化，并且目标页面是 HTTP(S) 页面。
• 重复点击但没有进展：要求智能体在第一次点击无变化后切换到截图和坐标操作。
• 坐标落点不对：确认使用的是视口 CSS 像素，而不是屏幕像素。