Agents SDK:无需公共 URL 即可在浏览器中预览开发服务器
构建网站的 Agent 需要在真实浏览器中检查其工作成果。借助内部主机名,您的 Agent 的浏览器可以预览在容器中运行的开发服务器,而无需将该服务器暴露到公共 Internet。
借助内部主机名,Cloudflare Agents SDK 中的持久浏览器可以打开仅由您的 Agent 提供服务的站点。为浏览器提供诸如 preview.internal 之类的主机名后,浏览器发往这些主机名的请求将转到您的 Agent,而不是 Internet。模型可以在其访问网页所用的同一个浏览器中检查沙盒中的开发服务器、工作区中的文件夹或另一个 Worker,且不会公开暴露任何内容。
每个内部主机都有一个在您的 Durable Object 中运行的 fetch 函数,因此它可以使用该对象的绑定和状态。主机也可以通过服务绑定将请求直接发送到另一个 Worker。为主机添加 target schema 后,模型即可选择该主机提供的内容,例如使用哪个端口或哪个文件夹。
内部主机名是浏览器的一项能力,与您的 Agent harness 无关。您可以使用 Pi Durable、AI SDK 和 TanStack AI 的内置适配器,也可以通过使用 browser.session() 实现工具来连接其他 harness。无需预构建的适配器。
此示例为 Pi Durable Agent 添加私有开发服务器预览。请先使用该指南中的软件包、绑定和请求处理程序,并安装 Agents SDK v0.31.0 ↗ 或更高版本。该示例包含三个部分:
- 浏览器配置:
internalHosts定义浏览器如何访问开发服务器。 - Durable Object 连接: Lifecycle 和
fetchInternalHost()将浏览器连接到您的应用程序。 - Harness 集成: 来自
agents/browser/pi的browserTool向 Pi 注册该工具。
import { DurableObject } from "cloudflare:workers";
import { createModels } from "@earendil-works/pi-ai/models";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { Browser, browserRun } from "agents/browser";
import { browserTool } from "agents/browser/pi";
import { PiHarness } from "agents/harness/pi";
import { Lifecycle } from "agents/lifecycle";
import { createAI } from "agents/models/pi-ai";
import { z } from "zod";
// Your own code: reach a port on your sandbox and return its Response.
import { fetchSandboxPort } from "./hosts";
// Browser Run calls back into your Worker through this entrypoint.
export { InternalHostRouter } from "agents/browser";
export class BrowserAssistant extends DurableObject {
ai = createAI({ binding: this.env.AI });
registry = createRegistry();
browser = new Browser({
provider: browserRun(this.env.BROWSER, {
internalHosts: {
router: this.ctx.exports.InternalHostRouter,
hosts: {
"preview.internal": {
description: "Your dev servers",
// What the model passes to browser.assignHost() to choose
// what this host serves. fetch receives it as its second argument.
target: z.object({ port: z.number().int().min(1024) }),
fetch: (request, { port }) => fetchSandboxPort(port, request),
},
},
},
}),
});
harness = new PiHarness({
harness: ({ storage, context, onWake }) => {
const models = createModels();
models.setProvider(this.ai.provider);
this.registry.install({
name: "browser",
tools: [
browserTool({ browser: this.browser, loader: this.env.LOADER }),
],
});
return Harness.open(
storage,
{ models, registry: this.registry, onWake },
context,
);
},
defaults: { model: this.ai("@cf/zai-org/glm-5.3-flash") },
});
lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
// InternalHostRouter calls this method to reach your Browser.
fetchInternalHost(message) {
return this.browser.fetchInternalHost(message);
}
async ask(prompt) {
const { text } = await this.harness.prompt(prompt);
return text;
}
}import { DurableObject } from "cloudflare:workers";
import { createModels } from "@earendil-works/pi-ai/models";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { Browser, browserRun, type InternalHostMessage } from "agents/browser";
import { browserTool } from "agents/browser/pi";
import { PiHarness } from "agents/harness/pi";
import { Lifecycle } from "agents/lifecycle";
import { createAI } from "agents/models/pi-ai";
import { z } from "zod";
// Your own code: reach a port on your sandbox and return its Response.
import { fetchSandboxPort } from "./hosts";
// Browser Run calls back into your Worker through this entrypoint.
export { InternalHostRouter } from "agents/browser";
export class BrowserAssistant extends DurableObject<Env> {
ai = createAI({ binding: this.env.AI });
registry = createRegistry();
browser = new Browser({
provider: browserRun(this.env.BROWSER, {
internalHosts: {
router: this.ctx.exports.InternalHostRouter,
hosts: {
"preview.internal": {
description: "Your dev servers",
// What the model passes to browser.assignHost() to choose
// what this host serves. fetch receives it as its second argument.
target: z.object({ port: z.number().int().min(1024) }),
fetch: (request, { port }) => fetchSandboxPort(port, request),
},
},
},
}),
});
harness = new PiHarness({
harness: ({ storage, context, onWake }) => {
const models = createModels();
models.setProvider(this.ai.provider);
this.registry.install({
name: "browser",
tools: [
browserTool({ browser: this.browser, loader: this.env.LOADER }),
],
});
return Harness.open(
storage,
{ models, registry: this.registry, onWake },
context,
);
},
defaults: { model: this.ai("@cf/zai-org/glm-5.3-flash") },
});
lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
// InternalHostRouter calls this method to reach your Browser.
fetchInternalHost(message: InternalHostMessage) {
return this.browser.fetchInternalHost(message);
}
async ask(prompt: string) {
const { text } = await this.harness.prompt(prompt);
return text;
}
}若要使用其他 harness,请保留浏览器配置。如果有可用的浏览器工具适配器,请选用它,或使用 browser.session() 实现工具。
browserTool 会将每个主机的信息(包括其 target 的 schema)告知模型。由于 preview.internal 具有 target schema,模型可以选择它提供服务的端口。为检查其开发服务器,模型会使用与 schema 匹配的 target(例如 { port: 5173 })调用 browser.assignHost(),并打开返回的 URL:
const { url } = await browser.assignHost({
host: "preview.internal",
target: { port: 5173 },
});
await browser.cdp({
method: "Page.navigate",
params: { url },
sessionId: "active",
});target 会根据 schema 进行校验并存储,因此它在多轮对话、浏览器重启和重新部署之后依然有效。此后,每个发往 http://preview.internal/ 的请求都会以 { port: 5173 } 调用该主机的 fetch 函数。
此版本还简化了 browserTool。它在自己的 Dynamic Worker 中运行模型的代码,不再需要 CodemodeRuntime 导出。如果您已在使用 browserTool,请参阅 v0.31.0 升级说明 ↗。
有关完整示例、限制和安全指南,请参阅内部主机名。