智能体
developers.cloudflare.com ·
@Cloudflare Developers
Cloudflare Agents SDK 新增持久化浏览器工具 browserTool
Cloudflare Agents SDK 推出 browserTool，为 Agent 提供可跨轮次复用的 Browser Run 浏览器，标签页、Cookie 和登录会话在会话存活期间保持。模型通过 Chrome DevTools Protocol 编写代码驱动浏览器，截图以图像形式返回供多模态模型检查。需 Agents SDK v0.28.0 及以上，通过 Browser 注册到 Lifecycle 并加入 Pi Durable 扩展注册表。每个 Pi 对话默认独立标签页，Cookie 与登录态在浏览器内共享；浏览器在 Durable Object 休眠时仍存活，默认空闲超时 10 分钟，会话过期或崩溃会新建浏览器并返回 restarted: true，旧标签与登录态丢失。也可配合 AI SDK 和 TanStack AI 适配器使用。
AI推荐理由 Cloudflare Agents SDK 官方 changelog 发布 browserTool，明确给出 v0.28.0 版本要求、代码示例和会话行为细节（默认 10 分钟空闲超时、崩溃后 restarted: true 且旧标签与登录态丢失），属于可验证的开发者工具更新，对构建持久化浏览器 Agent 有直接参考价值；局限是仅覆盖 Cloudflare 自家 Agents SDK 与 Browser Run 生态，且未提供实际效果或性能数据。
82
正文
The [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/) now provides a `browserTool` that gives your agent a [Browser Run](https://developers.cloudflare.com/browser-run/) browser it can return to on later turns. Your agent can open a website, inspect a page, and come back to it with its tabs, cookies, and login session intact while the browser session remains alive.
When you give `browserTool` to your agent, the model writes code that drives the browser through the [Chrome DevTools Protocol (CDP)](https://developers.cloudflare.com/browser-run/cdp/). Screenshots return as images that an image-capable model can inspect and your UI can display.
To use `browserTool`, make sure you have [Agents SDK v0.28.0 ↗︎](https://github.com/cloudflare/agents/releases/tag/agents%400.28.0) or greater installed. Create a `Browser`, register it with your object's [Lifecycle](https://developers.cloudflare.com/agents/runtime/lifecycle/), and add the tool to a [Pi Durable](https://developers.cloudflare.com/agents/harnesses/pi/) [extension registry](https://developers.cloudflare.com/agents/harnesses/pi/extensions/) before opening the harness:
```
import { Browser, browserRun } from "agents/browser";
import { browserTool } from "agents/browser/pi";
export class MyAgent extends DurableObject {
// ...
browser = new Browser({ provider: browserRun(this.env.BROWSER) });
harness = new PiHarness({
harness: async ({ storage, context }) => {
this.registry.install({
name: "browser",
tools: [
browserTool({
ctx: this.ctx,
browser: this.browser,
loader: this.env.LOADER,
}),
],
});
// ...
return Harness.open(
storage,
{ models, registry: this.registry },
context,
);
},
});
lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
}
```
```
import { Browser, browserRun } from "agents/browser";
import { browserTool } from "agents/browser/pi";
export class MyAgent extends DurableObject {
// ...
browser = new Browser({ provider: browserRun(this.env.BROWSER) });
harness = new PiHarness({
harness: async ({ storage, context }) => {
this.registry.install({
name: "browser",
tools: [
browserTool({
ctx: this.ctx,
browser: this.browser,
loader: this.env.LOADER,
}),
],
});
// ...
return Harness.open(
storage,
{ models, registry: this.registry },
context,
);
},
});
lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
}
```
Each Pi conversation gets its own active tab by default. Cookies and logins remain shared within the browser.
The browser stays alive between turns, including when the Durable Object hibernates. Its default idle timeout is 10 minutes. If the session expires or crashes, the tool creates a fresh browser and reports `restarted: true`. The old tabs and login state are gone.
You can also use the persistent browser with the AI SDK and TanStack AI adapters, or connect another harness through the public Browser and CDP APIs.
Refer to [persistent browser tools](https://developers.cloudflare.com/agents/tools/browser/#return-to-the-same-browser) for the complete Pi Durable example, required bindings, and behavior when a tool call is interrupted.