cloudflare/agents agents@0.31.0

on GitHub

This release adds internal hostnames to the browser. Give a Browser Run browser hostnames such as preview.internal, and its requests to them go to your agent instead of the internet, so the model can open a dev server, a workspace folder or another Worker in the same browser it uses for the web.

Highlights

• Internal hostnames: pass up to 8 hostnames to browserRun() as internalHosts. Serve each one from a fetch function on your agent or from another Worker. See Internal hostnames.
• Hosts the model points: give a host a target schema, and the model chooses what it serves with browser.assignHost(), such as a container port or a folder in its workspace. Without a target, a host always serves the same thing.
• Lighter installs without MCP servers: @modelcontextprotocol/sdk and @modelcontextprotocol/server are now optional peer dependencies, so apps that don't serve MCP no longer install them.
• Stable models: agents/models/ai-sdk and agents/models/pi-ai are no longer experimental. See Models.
• Other changes: createMcpHandler passes the verified token from @cloudflare/workers-oauth-provider 1.x to tool callbacks as context.http.authInfo. createAI from agents/models/pi-ai sends pi-ai's Anthropic betas for catalog Claude models. PiWhenBusy accepts "reject".
• browserTool improvements: the model's code runs in its own Dynamic Worker instead of on codemode, and is stopped from outside that Worker if it overruns its timeout. It can no longer close the browser or create a Live View link. this.browser.session() lets your own code drive the same browser. createBrowserTools, createBrowserRuntime, BrowserConnector and the Quick Action helpers are deprecated in favour of browserTool.

Upgrading

You only need to make changes if you serve MCP or use browserTool.

If you serve MCP or use agents/x402 or agents/experimental/webmcp:

1. Add the MCP packages to your package.json at the versions this release expects, since your package manager no longer installs them. Until you do, builds fail with an unresolved import.

   • agents/mcp (McpAgent, WorkerTransport, createLegacyMcpHandler) and agents/x402: @modelcontextprotocol/sdk@1.32.1 and @modelcontextprotocol/server@2.3.1
   • agents/mcp/server (createMcpHandler): @modelcontextprotocol/server@2.3.1
   • agents/experimental/webmcp: @modelcontextprotocol/sdk@1.32.1

   See Upgrading an existing McpAgent server.

2. Import client helpers such as RPCClientTransport from agents/mcp/client instead of agents/mcp. MCP client code needs neither package.

If you use browserTool:

1. Remove the CodemodeRuntime export from your Worker unless createBrowserTools still uses it, and remove ctx from browserTool's options. Keep the LOADER binding and keep @cloudflare/codemode installed for now.

2. Update instructions of your own that mention cdp.send, such as a system prompt. The tool's description already teaches the new call:

   - await cdp.send({ method: "Page.navigate", params: { url }, sessionId: "active" });
   + await browser.cdp({ method: "Page.navigate", params: { url }, sessionId: "active" });

3. Read notice instead of restarted, newTabs and calls if your code inspects results. notice says in sentences whether the browser restarted, the page opened tabs, or another chat closed or shares the tab. PiBrowserToolDetails now has only executionId and status.

Minor Changes

• #2673 865a57e Thanks @ben-reitz! - Add internalHosts to browserRun() provider: set internal hostnames the browser can reach through your agent. Allow the model to point these hostnames at specific targets like container ports or workspace folders with browser.assignHost(). See Internal hostnames.

• #2667 03b4609 Thanks @ben-reitz! - browserTool now runs the model's code in its own Dynamic Worker instead of on codemode, so it needs no ctx or CodemodeRuntime export (keep @cloudflare/codemode installed for now) and its output has no calls log; browser.session() gives your own code the same connection to the browser. See Persistent browser.

• #2634 565e37c Thanks @mattzcarey! - @modelcontextprotocol/sdk and @modelcontextprotocol/server are now optional peer dependencies, so add them to your package.json if you use agents/mcp, agents/mcp/server, agents/x402 or agents/experimental/webmcp. See Upgrading an existing McpAgent server.

Patch Changes

• #2668 183c141 Thanks @ben-reitz! - browserTool's model code now calls a browser global (browser.cdp(...), browser.spec({ domain })) instead of cdp.send(...), and the result's notice replaces the restarted and newTabs fields. See Persistent browser.

• #2666 57c7813 Thanks @ben-reitz! - createBrowserTools, createBrowserRuntime and BrowserConnector are deprecated; use browserTool. See Persistent browser. The Quick Action helpers (createQuickActionTools, runQuickAction, browserMarkdown and the rest) are deprecated too and will not change.

• #2743 f049ee1 Thanks @mattzcarey! - agents/models/ai-sdk and agents/models/pi-ai are no longer experimental. See Models.

• #2718 916c0e3 Thanks @ben-reitz! - createAI from agents/models/pi-ai now sends pi-ai's betas as the anthropic-beta header for catalog Claude models on /run, as it already did on the provider-native path. See #2714.

• #2717 4d7734a Thanks @ben-reitz! - PiWhenBusy accepts "reject", which PiHarness.submit() already passed through to pi-durable. See Pi harness.

• #2680 2a25d88 Thanks @mattzcarey! - createMcpHandler now reads the verified token that @cloudflare/workers-oauth-provider 1.x sets as ctx.auth, so tool callbacks receive context.http.authInfo (token, client ID, scopes, expiry and resource) behind OAuthProvider and OAuthResourceServer. getMcpAuthContext().props is unchanged.