Next.js + Vercel

使用 Vercel Sandbox 在 Vercel 上的 Next.js 应用中运行 agent-browser。Linux microVM 按需启动，运行 agent-browser + Chrome，然后关闭。没有二进制大小限制，也没有 Chromium 打包的复杂性。

设置¶

pnpm add @agent-browser/sandbox @vercel/sandbox

服务器操作¶

Vercel Sandbox 运行的是 Amazon Linux。Chromium 需要默认未安装的系统库，因此全新的沙盒需要在 agent-browser 启动 Chrome 之前执行 dnf install 步骤。在生产环境中，使用沙盒快照（见下文）可以完全跳过这一步。@agent-browser/sandbox 辅助工具默认会安装这些系统依赖，并负责命令执行。

"use server";
import { runAgentBrowserCommand, withAgentBrowserSandbox } from "@agent-browser/sandbox/vercel";

export async function screenshotUrl(url: string) {
  return withAgentBrowserSandbox(async (sandbox) => {
    await runAgentBrowserCommand(sandbox, ["open", url]);

    const ssResult = await runAgentBrowserCommand<{ data?: { path?: string } }>(sandbox, [
      "screenshot",
    ]);
    const ssPath = ssResult.json?.data?.path;
    if (!ssPath) throw new Error("Screenshot did not return a file path.");

    const b64Result = await sandbox.runCommand("base64", ["-w", "0", ssPath]);
    const screenshot = (await b64Result.stdout()).trim();
    await runAgentBrowserCommand(sandbox, ["close"], { json: false });
    return { ok: true, screenshot };
  });
}

export async function snapshotUrl(url: string) {
  return withAgentBrowserSandbox(async (sandbox) => {
    await runAgentBrowserCommand(sandbox, ["open", url]);

    const result = await runAgentBrowserCommand(sandbox, ["snapshot", "-i", "-c"], {
      json: false,
    });

    await runAgentBrowserCommand(sandbox, ["close"], { json: false });
    return { ok: true, snapshot: result.stdout };
  });
}

通过 stdin 的 MCP 服务器¶

当智能体在同一 Vercel Sandbox 中发起多次 MCP 工具调用时，请使用 @agent-browser/sandbox/vercel 中的 startAgentBrowserMcp。它会启动一个 agent-browser mcp 进程，并通过该命令的 stdin 发送每个请求，这样工具调用可以复用该进程，而不是像 runAgentBrowserCommand 那样每次都启动一条 CLI 命令：

import { startAgentBrowserMcp, withAgentBrowserSandbox } from "@agent-browser/sandbox/vercel";

const snapshot = await withAgentBrowserSandbox(async (sandbox) => {
  const mcp = await startAgentBrowserMcp(sandbox, { timeout: 60_000 });
  try {
    await mcp.callTool("agent_browser_open", { url: "https://example.com" });
    return await mcp.callTool("agent_browser_snapshot", { interactive: true });
  } finally {
    await mcp.close();
  }
});

startAgentBrowserMcp 需要 @vercel/sandbox 3.7 或更高版本。timeout 以毫秒为单位，适用于每个请求以及 close()；如果不设置，请求将无限期等待。在其他运行时中，请将带有 stdin 和 stdout 流的进程传递给 @agent-browser/sandbox 中的 connectAgentBrowserMcp。

沙盒快照¶

如果不进行优化，每次 Sandbox 运行都会从头安装系统依赖 + agent-browser + Chromium（约 30 秒）。沙盒快照是预先安装了所有内容的已保存 VM 镜像，类似于 Vercel Sandbox 的 Docker 镜像。当设置了 AGENT_BROWSER_SNAPSHOT_ID 时，沙盒将直接从此镜像启动，而无需重新安装，从而将启动时间缩短到亚秒级。

这不同于 agent-browser 的可访问性快照（它会转储页面的可访问性树）。沙盒快照是 Vercel 基础设施层面的概念。

通过运行一次辅助脚本来创建沙盒快照：

npx tsx scripts/create-snapshot.ts

该脚本会启动一个全新的沙盒，安装系统依赖 + agent-browser + Chromium，保存 VM 状态，并输出快照 ID：

AGENT_BROWSER_SNAPSHOT_ID=snap_xxxxxxxxxxxx

将此添加到您的 Vercel 项目环境变量中（或在本地开发时使用 .env.local）。建议在任何生产部署中使用。

身份验证¶

在 Vercel 部署中，Sandbox SDK 会通过 OIDC 自动进行身份验证。对于本地开发，请提供显式凭据：

变量	描述
`VERCEL_TOKEN`	Vercel 个人访问令牌
`VERCEL_TEAM_ID`	Vercel 团队 ID
`VERCEL_PROJECT_ID`	Vercel 项目 ID

当这三个变量均已设置时，它们会被传递给 Sandbox.create()。如果未设置，SDK 将回退到 VERCEL_OIDC_TOKEN（在 Vercel 上自动可用）。

定时工作流（cron）¶

对于每日监控等重复性任务，请使用 Vercel Cron Jobs：

// app/api/cron/monitor/route.ts
import { runAgentBrowserCommand, withAgentBrowserSandbox } from "@agent-browser/sandbox/vercel";

export async function GET() {
  const result = await withAgentBrowserSandbox(async (sandbox) => {
    await runAgentBrowserCommand(sandbox, [
      "open", "https://example.com/pricing",
    ]);
    const snap = await runAgentBrowserCommand(sandbox, [
      "snapshot", "-i", "-c",
    ], { json: false });
    await runAgentBrowserCommand(sandbox, ["close"], { json: false });
    return snap.stdout;
  });

  // Process results, send alerts, store data...
  return Response.json({ ok: true, snapshot: result });
}

// vercel.json
{
  "crons": [
    { "path": "/api/cron/monitor", "schedule": "0 9 * * *" }
  ]
}

环境变量¶

变量	描述
`AGENT_BROWSER_SNAPSHOT_ID`	用于亚秒级启动的沙盒快照 ID（见上文）
`VERCEL_TOKEN`	Vercel 个人访问令牌（用于本地开发；OIDC 在 Vercel 上自动生效）
`VERCEL_TEAM_ID`	Vercel 团队 ID（用于本地开发）
`VERCEL_PROJECT_ID`	Vercel 项目 ID（用于本地开发）

演示应用¶

一个可运行的演示，包含流式进度 UI、限流功能，以及一个部署到 Vercel 的按钮，位于 examples/environments/。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 agen/agent-browser