feat(agents): add createBrowserExecuteTool and export BrowserSessions

[ben-reitz]

This adds the public API: createBrowserExecuteTool in agents/browser/ai, plus the BrowserSessions export from agents/browser. Both are experimental and ship with a minor changeset.

import { BrowserSessions } from "agents/browser";
import { createBrowserExecuteTool } from "agents/browser/ai";

export class MyAgent extends Agent<Env> {
  browser = new BrowserSessions({ browser: this.env.BROWSER });

  constructor(ctx: AgentContext, env: Env) {
    super(ctx, env);
    this.lifecycle.use(this.browser);
  }

  getTools() {
    return createBrowserExecuteTool({ sessions: this.browser, loader: this.env.LOADER });
  }
}

The host owns one BrowserSessions, so tools rebuilt every turn reach the same browser. Tabs, cookies, and logins carry over until Browser Run's keep_alive reclaims an idle browser.

What the model gets back

 { executionId, result, logs, calls }          // calls are persisted, not shown to the model
+  restarted: true, notice: "…navigate again…"  // the browser was replaced before this run
+  newTabs: [{ targetId, url }]                 // tabs the page opened

Screenshot summaries include the notice and newTabs as well.

Compared with createBrowserTools

	createBrowserTools	createBrowserExecuteTool
Browser lifetime	model (session modes)	host (BrowserSessions)
Backends	Browser Run, cdpUrl, Kitesurf	Browser Run Chromium only
Quick actions	included	use createQuickActionTools

createBrowserTools is unchanged. It gets deprecated in a later PR.

Details

• Separate history per session name. Each name gets its own codemode runtime (browser-session_<name>), so execution history never mixes with createBrowserTools or with other names.
• ctx is optional. It's resolved from the current Agent when not passed.
• Worker setup is the same as createBrowserTools. The worker exports CodemodeRuntime, which is re-exported from agents/browser. The test worker gains a facet-only CodemodeRuntime binding.

Tests

End-to-end on a real Agent and codemode facet (browser-capability.test.ts):

• model code runs in the persistent browser and the active tab is stored;
• tools rebuilt on a later turn reuse the same browser;
• after the browser is killed, the code runs in a replacement and the model is told.

Not in this PR: Think, TanStack AI, and Flue wrappers; CDP recipes; user docs.

Architecture diff

Outlined boxes are components this PR changes, with one green box per change. Green-filled boxes are new. Grey boxes are unchanged.

flowchart TB
  classDef ctx fill:none,stroke:#8c959f,color:#8c959f
  classDef changes fill:#dafbe1,stroke:#1a7f37,color:#1f2328
  classDef removed fill:#ffebe9,stroke:#cf222e,color:#1f2328
  classDef later fill:none,stroke:#8c959f,stroke-dasharray:4 3,color:#8c959f

  Agent["Agent (host Durable Object)"]:::ctx

  subgraph Tool["createBrowserExecuteTool · ai.ts (new)"]
    direction TB
    T1["+ browser_execute AI SDK tool"]:::changes
    T2["+ one codemode runtime per session name"]:::changes
    T3["+ adds restarted, notice, newTabs to results"]:::changes
    T1 ~~~ T2 ~~~ T3
  end

  Runtime["codemode runtime + sandbox"]:::ctx
  Conn["BrowserSessionConnector · session-connector.ts"]:::ctx

  subgraph BS["BrowserSessions · capability.ts"]
    B1["+ exported from agents/browser, with its types"]:::changes
  end

  BR["Browser Run"]:::ctx

  Agent -->|"getTools()"| Tool
  Agent -->|lifecycle.use| BS
  Tool --> Runtime
  Runtime --> Conn
  Conn -->|"connect(name)"| BS
  BS --> BR

  style Tool fill:#dafbe1,stroke:#1a7f37,stroke-width:2px,color:#1f2328
  style BS stroke:#1a7f37,stroke-width:2px

Loading

[changeset-bot]

🦋 Changeset detected

Latest commit: da7f553

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Minor
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[agent-think]

🟡 agents import sizes: 1 entry point grew

	Entry point	Exports	Largest gzip change	Size now
🟡	agents/chat	1 resized, 2 new	+156 B (+2.92%)	5.4 KiB
🆕	agents/browser	1 new	—	40.4 KiB
🆕	agents/browser/ai	1 new	—	140.4 KiB

Changed exports (5)

	Import	Gzip change	Size now
🟡	agents/chat#ResumableStream	+156 B (+2.92%)	5.4 KiB
🆕	agents/browser/ai#createBrowserExecuteTool	—	140.4 KiB
🆕	agents/browser#BrowserSessions	—	40.4 KiB
🆕	agents/chat#originMessageIds	—	2.4 KiB
🆕	agents/chat#withOriginMessageIds	—	2.3 KiB

How this works

Each runtime export is bundled on its own, minified, and gzipped. Changes smaller than 100 B, or smaller than 1% and 1 KiB, are ignored. Growth over 10% or 5 KiB is marked 🔴. This report is informational and does not fail CI. The workflow artifact contains every measurement.

_{Compared bc7768d9 → da7f553b · workflow run · reported by agent-think[bot]}

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2372

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2372

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2372

hono-agents

npm i https://pkg.pr.new/hono-agents@2372

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2372

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2372

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2372

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2372

commit: da7f553