Observability 仪表盘

使用本地 Web 仪表板实时监控 agent-browser 会话，该仪表板显示实时浏览器视口和命令活动流。

使用¶

仪表板已捆绑在二进制文件中，无需单独安装。启动服务器并打开任意会话：

agent-browser dashboard start
agent-browser open example.com

然后在浏览器中打开 http://localhost:4848 查看实时仪表板。如果通过反向代理或端口转发暴露仪表板，请在启动服务器时显式允许其浏览器 HTTPS 来源：

agent-browser dashboard start --allowed-origins https://dashboard.example.com

所有会话都会自动将数据流式传输到仪表板。本地回环来源在 IPv4 和 IPv6 上会自动获得允许，无需访问令牌。对于通过反向代理访问的仪表板，请使用 --allowed-origins 或 AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINS 提供以逗号分隔的精确来源列表；这使仪表板能够拒绝跨来源请求和 DNS 重绑定攻击。每个配置的来源都必须有效，自定义端口必须是 1 到 65535 之间的整数。未知选项、缺失值、无效端口和格式错误的来源都会导致启动失败。该命令仅对外部来源打印带私有令牌的访问 URL。打开相应的 URL 一次以建立浏览器会话，请勿分享该 URL。其不可猜测的令牌保留在初始 URL 片段中，随后浏览器会将其存储在 Secure、主机绑定、同站 cookie 中，用于仪表板 API 和流请求。直接打开 http://localhost:<port> 进行本地访问；外部令牌永远不会写入回环 cookie。配置反向代理以从日志中删除 cookie。浏览器保持在仪表板来源上，而服务器在内部代理每个会话的标签页、状态和流流量，因此无需暴露会话端口。重复启动时，仅当这些设置匹配时才会复用仪表板；在更改端口或允许来源之前，请先停止仪表板。

自定义流端口¶

默认情况下，每个会话将其 WebSocket 流服务器绑定到操作系统分配的端口。要使用特定端口，请设置 AGENT_BROWSER_STREAM_PORT 环境变量：

AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com

您还可以使用运行时命令来控制正在运行的会话上的流式传输：

agent-browser stream enable --port 9223
agent-browser stream status
agent-browser stream disable

仪表板功能¶

仪表板是一个单页 Web 应用，包含三个区域：

WebSocket 协议¶

仪表板连接到流式传输 使用的同一 WebSocket 端点，并带有额外的可观测性消息类型：

命令事件¶

在命令开始执行时发送：

{
  "type": "command",
  "action": "click",
  "id": "r123",
  "params": { "selector": "@e5" },
  "timestamp": 1711367000000
}

结果事件¶

在命令完成时发送：

{
  "type": "result",
  "id": "r123",
  "action": "click",
  "success": true,
  "data": {},
  "duration_ms": 45,
  "timestamp": 1711367000045
}

控制台事件¶

在浏览器向控制台记录日志时发送：

{
  "type": "console",
  "level": "log",
  "text": "Page loaded",
  "args": [{"type": "string", "value": "Page loaded"}],
  "timestamp": 1711367000100
}

args 数组包含原始 CDP Runtime.consoleAPICalled 参数，供编程访问使用。对象参数包含预览数据（例如 {userId: "abc", count: 42} 而不是 "Object"）。

这些是对流式传输 页面上已记录的 frame、status 和 error 消息类型的补充。

架构¶

仪表板是 Next.js 静态导出（output: 'export'），生成纯 HTML、CSS 和 JS。它位于 monorepo 中的 packages/dashboard/ 目录下，使用以下命令构建：

pnpm build:dashboard

仪表板在编译时使用 rust-embed 嵌入到 CLI 二进制文件中。普通 HTTP 请求提供嵌入的仪表板资源和同源 API 路由。特定于会话的标签页、状态和流 WebSocket 流量通过仪表板服务器代理到仅限回环的会话端口。

AI 聊天¶

仪表板包含一个可选的 AI 聊天面板，由 Vercel AI Gateway 提供支持。启用后，右侧面板会出现一个 Chat 标签页，与 Activity、Console、Network、Storage 和 Extensions 并列。

设置¶

Chat 标签页始终可见。设置 API 密钥以启用响应：

export AI_GATEWAY_API_KEY=gw_your_key_here
agent-browser dashboard start

可选地覆盖网关 URL 或模型：

export AI_GATEWAY_URL=https://ai-gateway.vercel.sh   # this is the default
export AI_GATEWAY_MODEL=openai/gpt-4o-mini           # default: anthropic/claude-sonnet-4.6

工作原理¶

Rust 服务器将来自仪表板的聊天请求代理到 Vercel AI Gateway，并使用 Vercel AI SDK 的 UI Message Stream 协议将响应流式传输回来。仪表板前端使用 @ai-sdk/react 中的 useChat 和 DefaultChatTransport。

Chat 每次工具调用执行一个 agent-browser 命令。带引号参数中的 ; 或 && 会保留为文本，因此 JSON 参数可以包含它们。Chat 可以通过 skills get <name> 加载捆绑的技能，并使用页面 WebMCP 工具：它使用 webmcp list <tool> --frame <frame-id> --json 获取工具的输入模式，然后使用相同的 --frame 调用 webmcp invoke。Chat 在选定的会话中运行，无法创建或切换会话；如需新会话，请在仪表板中使用 New Session。Chat 命令不能设置除 --json 和 --annotate 之外的全局标志。