Browser·续2

Provide either browser or cdpUrl. When only cdpUrl is set, the Quick Action tools are skipped.

Session lifecycle

By default, each execution gets a fresh browser session, torn down when the run ends (one-shot). Pass a session option for two more modes:

createBrowserTools({
    ctx: this.ctx,
    browser: this.env.BROWSER,
    loader: this.env.LOADER,
    session: { mode: "dynamic" }, // or { mode: "reuse", key: "main" }
});

createBrowserTools({
    ctx: this.ctx,
    browser: this.env.BROWSER,
    loader: this.env.LOADER,
    session: { mode: "dynamic" }, // or { mode: "reuse", key: "main" }
});

• one-shot (default) — fresh session per execution; deterministic cleanup when the execution reaches a terminal status.
• reuse — a named shared session that persists across executions until explicitly closed or swept.
• dynamic — starts one-shot; the model can promote the session with cdp.startSession() (for example, after logging in to a page) so later executions continue in the same browser.

Sessions are tracked durably in the Durable Object's storage, so they survive hibernation and approval pauses. A run that pauses for human approval resumes with its browser session, tabs, and cookies intact. If Browser Run expires the session while a pause waits, the resume surfaces a clear error and the model starts over.

Host-side helpers

For host-side wiring, use createBrowserRuntime, which returns { runtime, connector, tools }:

import { createBrowserRuntime } from "agents/browser/ai";

const { runtime, connector, tools } = createBrowserRuntime({
    ctx: this.ctx,
    browser: this.env.BROWSER,
    loader: this.env.LOADER,
    session: { mode: "dynamic" },
});

await connector.sessionInfo(); // Shared session ID and open tabs
await connector.liveView(); // Live View URLs for the shared session's tabs
await connector.closeSession(); // Close the shared session
await connector.sweep(); // Reclaim expired or stale sessions
await runtime.expirePaused(); // Reject stale pauses that were never approved

import { createBrowserRuntime } from "agents/browser/ai";

const { runtime, connector, tools } = createBrowserRuntime({
    ctx: this.ctx,
    browser: this.env.BROWSER,
    loader: this.env.LOADER,
    session: { mode: "dynamic" },
});

await connector.sessionInfo(); // Shared session ID and open tabs
await connector.liveView(); // Live View URLs for the shared session's tabs
await connector.closeSession(); // Close the shared session
await connector.sweep(); // Reclaim expired or stale sessions
await runtime.expirePaused(); // Reject stale pauses that were never approved

Call connector.sweep() from a scheduled task. connector.liveView() returns the shared session's tabs and Live View URLs, with each tab's current pageUrl, so an agent UI can label tabs and skip blank or internal pages.

Approval and human handoff

With createBrowserRuntime, the Code Mode runtime can pause a run with the browser session intact. A handoff follows this pattern:

1. The model calls cdp.getLiveViewUrl() to get a link to the current tab.
2. The agent surfaces the link to the user.
3. The model makes an approval-gated call, so the run pauses durably.
4. After approval, the run resumes against the same session.

async () => {
    const { targetId } = await cdp.send({
        method: "Target.createTarget",
        params: { url: "https://example.com/login" },
    });

const { url } = await cdp.getLiveViewUrl({ targetId, mode: "tab" });
    return { needsHumanLogin: url };
};

async () => {
    const { targetId } = await cdp.send({
        method: "Target.createTarget",
        params: { url: "https://example.com/login" },
    });

const { url } = await cdp.getLiveViewUrl({ targetId, mode: "tab" });
    return { needsHumanLogin: url };
};

Pass mode: "tab" for an interactive page view, or mode: "devtools" for the full DevTools inspector. The URL is valid for about five minutes. Call cdp.getLiveViewUrl() again to create a fresh URL.

Every cdp.* call is recorded in the runtime's durable log. If a run pauses for approval or the sandbox aborts, resuming replays the log and continues. Connector calls must therefore be sequential and deterministic. Model code must not use Promise.all for CDP calls, and the tool instructions enforce this. The sessionId from cdp.attachToTarget() is a stable handle that stays valid across pause and resume.

Legacy CDP methods

In addition to the shared CDP API, browser_execute provides these methods:

Session recording

To record legacy sessions, set recording: true in the session option:

import { createBrowserRuntime } from "agents/browser/ai";

const { connector } = createBrowserRuntime({
    ctx: this.ctx,
    browser: this.env.BROWSER,
    loader: this.env.LOADER,
    session: { mode: "reuse", key: "main", recording: true },
});

import { createBrowserRuntime } from "agents/browser/ai";

const { connector } = createBrowserRuntime({
    ctx: this.ctx,
    browser: this.env.BROWSER,
    loader: this.env.LOADER,
    session: { mode: "reuse", key: "main", recording: true },
});

A recording is finalized after the session closes. Capture the session ID with connector.sessionInfo() while the session is alive, then fetch the recording with getBrowserRecording(), as described in Recording. A recording on a shared reuse or dynamic session spans the full session lifetime, including every user that shares the session key.

Kitesurf

To use Kitesurf with browser_execute, select it in the session options:

const tools = createBrowserTools({
    ctx: this.ctx,
    browser: this.env.BROWSER,
    loader: this.env.LOADER,
    session: { browser: "kitesurf" },
});

const tools = createBrowserTools({
    ctx: this.ctx,
    browser: this.env.BROWSER,
    loader: this.env.LOADER,
    session: { browser: "kitesurf" },
});

A Kitesurf browser is scoped to its CDP WebSocket, so it supports only one-shot execution. Session reuse, pause and resume, Live View, recording, keepAliveMs, protocol discovery with cdp.spec(), and Kitesurf-backed Quick Actions are not available.

Quick Action tools

createQuickActionTools from agents/browser/ai gives the model tools for Browser Run Quick Actions. Each call is a one-shot request: Browser Run loads the page in a new browser, returns the result, and closes the browser. Quick Actions need only the browser binding, so they do not need a Durable Object, Worker Loader, or sandbox. To read a page, prefer the web_fetch tool.

Quick Actions do not share a browser or a login with browserTool. A site the model logged in to with browserTool is not logged in for a Quick Action. To read a protected page, pass credentials such as cookies or authenticate through options.

import { createQuickActionTools } from "agents/browser/ai";

const tools = createQuickActionTools({ browser: this.env.BROWSER });
// browser_markdown, browser_extract, browser_links, browser_scrape

import { createQuickActionTools } from "agents/browser/ai";

const tools = createQuickActionTools({ browser: this.env.BROWSER });
// browser_markdown, browser_extract, browser_links, browser_scrape

Pass actions to choose the tools, maxChars to bound results, and options for request settings:

const tools = createQuickActionTools({
    browser: this.env.BROWSER,
    maxChars: 20_000,
    options: { gotoOptions: { waitUntil: "networkidle0" } },
});

const tools = createQuickActionTools({
    browser: this.env.BROWSER,
    maxChars: 20_000,
    options: { gotoOptions: { waitUntil: "networkidle0" } },
});

Every Quick Action result is bounded to maxChars, which defaults to 50,000 characters, to protect the model context window while preserving the result shape. Host-supplied request options, such as cookies, authenticate, gotoOptions, and viewport, are passed once through options and are not exposed to the model.

Quick Actions require a Worker compatibility_date of 2026-03-24 or later and remote: true on the browser binding for local wrangler dev.

Browser agent example

The browser agent example uses the legacy tools. It covers Browser Run setup, tool definitions, and screenshot capture.

Browser agent

Build an agent that can browse the web, inspect pages, capture screenshots, and debug frontend issues.

Related resources

Browser Run

Run browser automation on Cloudflare.

Chrome DevTools Protocol

Use CDP commands, events, and types with Browser Run.

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/agents/tools/browser/#page","headline":"Browser","description":"Give your agent a browser that remembers tabs, cookies, and logins between turns. Use it with Pi Durable, the AI SDK, or another harness.","url":"https://developers.cloudflare.com/agents/tools/browser/","inLanguage":"en","image":"https://developers.cloudflare.com/agents/tools/browser/og.png?v=c6d74daaf14142d0","dateModified":"2026-10-22","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Use Code Mode to let models discover and compose tools by writing code as a compact, executable plan. title: Code Mode image: https://developers.cloudflare.com/agents/tools/codemode/og.png?v=7917c0fd55f05688

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.