browser: deprecate createBrowserTools and Quick Actions in favour of browserTool

.changeset/deprecate-browser-tools.md

@@ -0,0 +1,5 @@
+---
+"agents": minor
+---
+
+`createBrowserTools` and `createBrowserRuntime` are deprecated; use `browserTool`. See [Persistent browser](https://github.com/cloudflare/agents/blob/main/docs/agents/browse-the-web.md#persistent-browser). The Quick Action helpers (`createQuickActionTools`, `runQuickAction`, `browserMarkdown` and the rest) are deprecated too and won't change.

docs/agents/browse-the-web.md

@@ -8,6 +8,8 @@ One durable tool is provided:
 
 > **Experimental** — this feature may have breaking changes in future releases.
 
+> **`createBrowserTools` and `createBrowserRuntime` are deprecated.** Use [`browserTool`](#persistent-browser). Pausing a run with its session kept while a person works in Live View has no replacement yet, so keep using `createBrowserTools` if you rely on it.
+
 ## When to use browser tools
 
 Browser tools are useful when your agent needs to:
@@ -286,6 +288,8 @@ this.registry.install({
 
 ## Quick Actions (stateless browsing)
 
+> **Quick Actions are deprecated** and won't change: `createQuickActionTools`, `runQuickAction` and the `browserMarkdown`-style helpers keep working until they're removed. Use [`browserTool`](#persistent-browser) to drive a browser, the [`web_fetch` tool](./fetch-the-web.md) from `agents/webfetch` to read a page, or call the binding's `quickAction()` directly.
+
 `browser_execute` drives a full, stateful CDP session — the right tool for interactive, multi-step automation. But a lot of agent browsing is really one-shot: _read this page as Markdown_, _extract these fields_, _list the links_. For those, [Quick Actions](https://developers.cloudflare.com/browser-run/quick-actions/) are simpler, faster, and cheaper. They need only the `browser` binding — no Durable Object, Worker Loader, or sandbox — so they work from any Worker.
 
 ```ts

examples/browser-quick-actions/README.md

@@ -1,5 +1,7 @@
 # Browser Quick Actions
 
+> **Deprecated:** the Quick Action helpers in `agents/browser` are deprecated and won't change. See [Quick Actions](../../docs/agents/browse-the-web.md#quick-actions-stateless-browsing) for what to use instead.
+
 Read the web with Browser Run [Quick Actions](https://developers.cloudflare.com/browser-run/quick-actions/) — stateless, one-shot browser tasks that need only the `BROWSER` binding (no Durable Object, Worker Loader, sandbox, or CDP session).
 
 Enter a URL and pick an action: render the page to **Markdown**, list its **Links**, **Extract** structured data with AI, capture a **Screenshot**, or **Ask AI** — which hands the same Quick Actions to a model (via Workers AI) as tools and lets it browse to answer your question.

packages/agents/src/browser/ai.ts

@@ -193,6 +193,10 @@ function connectorOptions(
  *   }
  * }
  * ```
+ *
+ * @deprecated Use `browserTool` from `agents/browser/ai-sdk`,
+ * `agents/browser/tanstack-ai` or `agents/browser/pi`. See
+ * https://github.com/cloudflare/agents/blob/main/docs/agents/browse-the-web.md#persistent-browser
  */
 export function createBrowserRuntime(
   options: CreateBrowserToolsOptions
@@ -312,21 +316,38 @@ export function createBrowserRuntime(
  *   messages,
  * });
  * ```
+ *
+ * @deprecated Use `browserTool` from `agents/browser/ai-sdk`,
+ * `agents/browser/tanstack-ai` or `agents/browser/pi`. See
+ * https://github.com/cloudflare/agents/blob/main/docs/agents/browse-the-web.md#persistent-browser
  */
 export function createBrowserTools(
   options: CreateBrowserToolsOptions
 ): ToolSet {
   return createBrowserRuntime(options).tools;
 }
 
-/** A Quick Action exposed as an AI SDK tool. */
+/**
+ * A Quick Action exposed as an AI SDK tool.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export type QuickActionToolName =
   | "markdown"
   | "extract"
   | "links"
   | "scrape"
   | "content";
 
+/**
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export interface CreateQuickActionToolsOptions {
   /**
    * Browser Run binding with Quick Actions support (`env.BROWSER`). Requires a
@@ -461,6 +482,11 @@ function boundArray(value: unknown[], maxChars: number): unknown[] {
  * const tools = createQuickActionTools({ browser: this.env.BROWSER });
  * const result = await generateText({ model, tools, messages });
  * ```
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
  */
 export function createQuickActionTools(
   options: CreateQuickActionToolsOptions

packages/agents/src/browser/connector.ts

@@ -203,6 +203,10 @@ const ATTACH_HANDLE_PREFIX = "target:";
  *
  * Locks on the session store are held only around store reads/writes, never
  * across network calls to Browser Run or while a socket is open.
+ *
+ * @deprecated Use `browserTool` from `agents/browser/ai-sdk`,
+ * `agents/browser/tanstack-ai` or `agents/browser/pi`. See
+ * https://github.com/cloudflare/agents/blob/main/docs/agents/browse-the-web.md#persistent-browser
  */
 export class BrowserConnector extends CodemodeConnector {
   #options: BrowserConnectorOptions;

packages/agents/src/browser/quick-actions.ts

@@ -120,22 +120,45 @@ export interface QuickActionSnapshot {
  * against the action when it is a string literal (e.g. `"json"` requires a
  * {@link QuickActionExtractInput}); any {@link QuickActionInput} is accepted
  * otherwise.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
  */
 export function runQuickAction(
   browser: QuickActionBinding,
   action: "json",
   params: QuickActionExtractInput
 ): Promise<Response>;
+/**
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export function runQuickAction(
   browser: QuickActionBinding,
   action: "scrape",
   params: QuickActionScrapeInput
 ): Promise<Response>;
+/**
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export function runQuickAction(
   browser: QuickActionBinding,
   action: "screenshot",
   params: QuickActionScreenshotInput
 ): Promise<Response>;
+/**
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export function runQuickAction(
   browser: QuickActionBinding,
   action: QuickAction,
@@ -219,15 +242,29 @@ async function quickActionBinary(
   };
 }
 
-/** Fetch a page's fully rendered HTML via `/content`. */
+/**
+ * Fetch a page's fully rendered HTML via `/content`.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export function browserContent(
   browser: QuickActionBinding,
   input: QuickActionPage
 ): Promise<string> {
   return quickActionJson<string>(browser, "content", input);
 }
 
-/** Convert a page (or raw HTML) to Markdown via `/markdown`. */
+/**
+ * Convert a page (or raw HTML) to Markdown via `/markdown`.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export function browserMarkdown(
   browser: QuickActionBinding,
   input: QuickActionPage
@@ -238,6 +275,11 @@ export function browserMarkdown(
 /**
  * Extract structured data from a page with AI via `/json`. Provide a `prompt`,
  * a `response_format` JSON Schema, or both.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
  */
 export function browserExtract<T = unknown>(
   browser: QuickActionBinding,
@@ -246,23 +288,44 @@ export function browserExtract<T = unknown>(
   return quickActionJson<T>(browser, "json", input);
 }
 
-/** Retrieve every link on a page via `/links`. */
+/**
+ * Retrieve every link on a page via `/links`.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export function browserLinks(
   browser: QuickActionBinding,
   input: QuickActionPage
 ): Promise<string[]> {
   return quickActionJson<string[]>(browser, "links", input);
 }
 
-/** Scrape specific elements (by CSS selector) via `/scrape`. */
+/**
+ * Scrape specific elements (by CSS selector) via `/scrape`.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export function browserScrape(
   browser: QuickActionBinding,
   input: QuickActionScrapeInput
 ): Promise<QuickActionScrapeResult[]> {
   return quickActionJson<QuickActionScrapeResult[]>(browser, "scrape", input);
 }
 
-/** Capture rendered HTML plus a base64 screenshot in one request via `/snapshot`. */
+/**
+ * Capture rendered HTML plus a base64 screenshot in one request via `/snapshot`.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export function browserSnapshot(
   browser: QuickActionBinding,
   input: QuickActionPage
@@ -275,6 +338,11 @@ export function browserSnapshot(
  * content type — by default a PNG (`image/png`). Note that passing
  * `screenshotOptions.encoding: "base64"` makes the service return a `text/plain`
  * data-URI string instead of binary, which this helper hands back verbatim.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
  */
 export function browserScreenshot(
   browser: QuickActionBinding,
@@ -283,7 +351,14 @@ export function browserScreenshot(
   return quickActionBinary(browser, "screenshot", input);
 }
 
-/** Render a PDF via `/pdf`. Returns the PDF bytes. */
+/**
+ * Render a PDF via `/pdf`. Returns the PDF bytes.
+ *
+ * @deprecated Quick Actions are deprecated and won't change. Use
+ * `browserTool` to drive a browser, the `web_fetch` tool from
+ * `agents/webfetch` to read a page, or call the binding's
+ * `quickAction()` directly.
+ */
 export function browserPdf(
   browser: QuickActionBinding,
   input: QuickActionPage

packages/agents/src/browser/tanstack-ai.ts

@@ -40,6 +40,10 @@ export type { CreateBrowserToolsOptions } from "./ai";
  *   messages,
  * });
  * ```
+ *
+ * @deprecated Use `browserTool` from `agents/browser/ai-sdk`,
+ * `agents/browser/tanstack-ai` or `agents/browser/pi`. See
+ * https://github.com/cloudflare/agents/blob/main/docs/agents/browse-the-web.md#persistent-browser
  */
 export function createBrowserTools(
   options: CreateBrowserToolsOptions