企业官网建设流程全解析

如何用 Browserbase 会话监控跟踪 Stagehand 自动化的资源用量与 token 消耗

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand

当 Stagehand 自动化跑在 Browserbase 云端浏览器上时，你通常要回答两个问题：这个会话消耗了多少 CPU、内存和带宽？act / extract / observe 各花掉了多少 token？Stagehand 的文档为这两类问题提供了各自的读取方式：会话级资源数据通过 Browserbase 的 sessions API 读取，token 消耗通过stagehand.metrics()从运行时读取。本文以 TypeScript 为主线，给出从安装、接入到验证输出的完整路径，适用条件：已持有 Browserbase API key，运行环境满足 安装文档 要求（Node.js 22.18 或更高、Python 3.11 或更高、Go 1.26 或更高；Bun 可用）。

准备条件

安装 Stagehand SDK 和依赖（按 快速开始 的命令）：

mkdir my-stagehand-app && cd my-stagehand-app pnpm init -y pnpm install @browserbasehq/stagehand zod

会话监控部分还需要@browserbasehq/sdk（即 可观测性文档 中import { Browserbase } from "@browserbasehq/sdk"所引用的 Browserbase 官方 SDK）。

设置环境变量。Stagehand 不会替你读取环境变量，API key 需要在你自己的代码里读取后显式传给浏览器工厂：

export BROWSERBASE_API_KEY="bb_live_..." # 你的 Browserbase API key export BROWSERBASE_PROJECT_ID="..." # 手动创建会话时需要

未配置模型时，Model Gateway 会自动选择并鉴权模型，不需要额外的模型供应商 key。

跟踪 token 消耗：metrics 基线相减法

stagehand.metrics()从运行时返回指标，调用需要 await。文档强调：指标在整个会话内是累计值，所以要得到某段自动化的真实消耗，需要在任务开始前记一次基线，任务结束后再取一次，两者相减。

import { browserbase, Stagehand } from "@browserbasehq/stagehand"; import { z } from "zod/v4"; const UserSchema = z.object({ name: z.string(), email: z.string() }); const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY, }); const stagehand = await Stagehand.create({ browser }); const startTime = Date.now(); const initialMetrics = await stagehand.metrics(); // ... 执行自动化任务 const [page] = await browser.context.pages(); await page.goto("https://example.com"); await stagehand.act("click the login button"); const { data } = await stagehand.extract("extract user info", UserSchema); const finalMetrics = await stagehand.metrics(); const executionTime = Date.now() - startTime; // 指标是会话内累计值，因此减去基线 const tokensUsed = finalMetrics.totalPromptTokens + finalMetrics.totalCompletionTokens - (initialMetrics.totalPromptTokens + initialMetrics.totalCompletionTokens); console.log("Automation Summary:", { tokensUsed, executionTime: `${executionTime}ms`, avgInferenceTime: `${finalMetrics.totalInferenceTimeMs / 3}ms`, });

Python 和 Go SDK 提供同样的metrics()能力，字段命名为 snake_case（total_prompt_tokens等）和 PascalCase（TotalPromptTokens等），相减逻辑一致。

metrics 对象包含哪些字段

指标按 Stagehand 操作类型（act / extract / observe）分别给出 token 与推理耗时，另有累计总量：

totalCachedInputTokens单独统计从模型供应商的 prompt cache 中命中的部分，与 Stagehand 自身的服务端结果缓存（后者直接省掉推理调用）是两回事。

文档给出的示例输出（数值仅作示例，实际运行结果不同）：

const metrics = await stagehand.metrics(); console.log(metrics); // { // actPromptTokens: 4011, // actCompletionTokens: 51, // actInferenceTimeMs: 1688, // extractPromptTokens: 4200, // extractCompletionTokens: 243, // extractInferenceTimeMs: 4297, // observePromptTokens: 347, // observeCompletionTokens: 43, // observeInferenceTimeMs: 903, // totalPromptTokens: 8558, // totalCompletionTokens: 337, // totalInferenceTimeMs: 6888 // // ...（reasoning / cached 字段略） // }

验证方式：任务完成后打印的 summary 中tokensUsed应为正数且随任务中 act / extract 次数增长；metrics()调用本身应正常返回对象（它是从运行时获取的，若会话已关闭则不再有效）。

跟踪会话资源：CPU、内存与带宽

Browserbase 的会话级监控提供实时画面回放、网络请求监控、console 日志、CPU 与内存指标、会话状态与时长。想通过 API 读取这些数据，关键点是自己创建会话以持有 session ID，再用browserbase.connect()按 session ID 接入：

import { Browserbase } from "@browserbasehq/sdk"; import { browserbase as stagehandBrowserbase, Stagehand } from "@browserbasehq/stagehand"; const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY, }); // 自己创建会话，从而持有 session ID const session = await bb.sessions.create({ projectId: process.env.BROWSERBASE_PROJECT_ID, }); const browser = await stagehandBrowserbase.connect({ apiKey: process.env.BROWSERBASE_API_KEY, sessionId: session.id, }); const stagehand = await Stagehand.create({ browser }); // ... 执行自动化 const sessionInfo = await bb.sessions.retrieve(session.id); console.log("Session status:", sessionInfo.status); console.log("Session region:", sessionInfo.region); console.log("CPU usage:", sessionInfo.avgCpuUsage); console.log("Memory usage:", sessionInfo.memoryUsage); console.log("Proxy bytes:", sessionInfo.proxyBytes);

这里用connect()而不是launch()：按 浏览器配置文档 的说明，browserbase.launch()创建会话时若不带extensionId，Stagehand 会自动上传扩展；而直接管理会话时，需要先上传 Stagehand 扩展并在创建会话时带上extensionId（扩展不能在会话开始后追加），然后通过 session ID 交给browserbase.connect()。文档中connect()示例的extensionId来自环境变量BROWSERBASE_STAGEHAND_EXTENSION_ID，即 Browserbase Extensions API 返回的已上传扩展资源 ID，需要你按自己的上传流程填充。

需要注意的限制：avgCpuUsage、memoryUsage等资源计数在较旧的 Browserbase API 版本中可能缺失，文档中的类型定义将它们标记为可选字段（avgCpuUsage?: number）。读取时对undefined做兜底。

会话状态取值范围：RUNNING、COMPLETED、ERROR、TIMED_OUT。

按状态与元数据过滤会话

批量运行时，用sessions.list()查询和筛选会话：

// 按状态过滤（例如只列出运行中的会话） const sessions = await browserbase.sessions.list({ status: "RUNNING" }); // 按元数据查询 const matches = await browserbase.sessions.list({ q: query });

每条会话记录可读取id、status、startedAt、endedAt、region、avgCpuUsage、memoryUsage、proxyBytes、userMetadata。文档建议在browserbase.launch()上用userMetadata给每个会话打标签，这样后续查询就能按工作流、客户或部署维度切分。

验证方式：list({ status: "RUNNING" })返回的会话集合应只包含状态为RUNNING的会话；带userMetadata标签的会话可用q查询命中，据此判断标签是否生效。

操作历史：日志回调构建时间线

metrics()给的是总量。要看"发生了什么"的顺序，文档给出的方式是通过日志回调自行记录：每次 act、observe、extract 都会发出带结构化数据的日志记录，Stagehand实例上没有现成的 history 访问器。

const history: Array<{ level: "debug" | "info" | "warn" | "error"; message: string; data: Record<string, unknown>; timestamp: string; }> = []; const stagehand = await Stagehand.create({ browser: await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY }), logging: { level: "debug", format: "json", onLog(log) { history.push({ ...log, timestamp: new Date().toISOString() }); }, }, }); // ... 运行自动化 console.log(history.filter((entry) => entry.level === "error")); console.log(await stagehand.metrics());

记录内容的完整程度取决于日志级别：默认是info及以上，想要最完整的时间线时把级别调到debug。在 Browserbase 上，会话回放面板也能可视化展示同一条时间线，而且能看到网络与 console 活动——这些内容不会进入日志回调。

边界与不适用项

• metrics()与sessions.retrieve()是两套数据：前者是 Stagehand 推理侧的 token 与耗时统计，后者是 Browserbase 会话侧的 CPU、内存、带宽与状态，两者互补，不能互相替代。
• 本地浏览器（localBrowser.launch()）同样支持stagehand.metrics()，但不经过 Browserbase 会话 API，因此本文的会话级资源字段只在 Browserbase 云会话上可用。
• 文档明确avgCpuUsage/memoryUsage字段在旧版 Browserbase API 中可能缺省，读取代码需要容忍undefined。
• 想把完整调用链接入自己的可观测系统时，Stagehand 对每个操作和每条日志都会发 OpenTelemetry span（100% 采样），telemetry.traces.endpoint必须指向以/v1/traces结尾的 OTLP 端点——这属于独立配置路径，本文不展开。

完成上述步骤后，你应当能看到：脚本输出的Automation Summary（含相减后的tokensUsed）、sessions.retrieve()返回的会话状态与资源字段，以及list()按状态过滤后的会话列表。这三类输出共同构成了对一次 Browserbase 上 Stagehand 自动化的资源与 token 消耗核对依据；进一步的 token 成本优化可参考文档中指向的 缓存 与 日志配置 页面。

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand