跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt

Use this file to discover all available pages before exploring further.

浏览器自动化中间件让 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，用于在页面渲染、动画、跳转或异步请求后等待一段时间。

​
配置项

字段类型默认值说明
allowNavigationbooleantrue是否暴露 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 像素，而不是屏幕像素。