Cloudflare quick actions

Cloudflare Browser Run (formerly Browser Rendering) has quick actions: one REST call renders a page in Cloudflare's browser and gives back what you asked for, such as its markdown, links or a screenshot. @mayurajs/cloudflare-quick-action brings them to Mayura two ways:

• cloudflareQuickActions: a client for every quick action.
• quickActionTools: the actions as permission-gated tools, kept to the origins you allow, both for the URLs the model asks for and for what the rendered page loads. See Web data without a browser.

It talks to Cloudflare's API with fetch: no Cloudflare SDK, no other dependencies, and it runs on every runtime Mayura runs on. For a browser to drive, see Cloudflare Browser Run browsers.

#Install

npm install mayura @mayurajs/cloudflare-quick-action

#Credentials

You need your account id (32 hex characters, on the account's overview page in the Cloudflare dashboard) and an API token. Create the token under My Profile > API Tokens with the Browser Rendering - Edit permission; the package needs nothing else. The package reads nothing from the environment: pass both in yourself, for example from CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_BROWSER_TOKEN.

#Use the tools

import { createRuntime, defineAgent, z } from 'mayura';
import { cloudflareQuickActions, quickActionTools } from '@mayurajs/cloudflare-quick-action';

const actions = cloudflareQuickActions({
  accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? '',
  apiToken: process.env.CLOUDFLARE_BROWSER_TOKEN ?? '',
});

const web = quickActionTools(actions, {
  origins: ['https://docs.example.com'],
  screenshot: true,
  crawl: true,
  costMicros: { markdown: 1_000, links: 1_000, scrape: 1_000, screenshot: 2_000, crawl: 20_000 },
});

const researcher = defineAgent({
  id: 'docs.researcher',
  version: '1',
  instructions: 'Answer from https://docs.example.com. Use cloudflare.links to find pages and cloudflare.markdown to read them.',
  input: z.object({ question: z.string() }),
  output: z.object({ answer: z.string() }),
  tools: web,
  model,
});

const runtime = createRuntime({
  profile: 'ephemeral',
  permissions: {
    allow: [
      'model:openai.responses', 'effect:read', 'web:cloudflare:read', 'web:cloudflare:crawl',
      'tool:cloudflare.markdown', 'tool:cloudflare.links', 'tool:cloudflare.scrape',
      'tool:cloudflare.screenshot', 'tool:cloudflare.crawl',
    ],
  },
  limits: { maxCostMicros: 200_000 },
});

Every tool reads (effects: 'read'), so a call needs tool:<name>.<tool>, effect:read and the tool's permission:

#Tool options

#What the tools do

• Origins, twice. Every URL a tool reads must be within origins; one outside them comes back as the tool's result, { error: 'PERMISSION_DENIED', message }, so the model can choose another. The page Cloudflare renders is kept to them too: the tools send allowRequestPattern built from your origins (originPatterns(origins)), so the page loads no scripts, images or frames from elsewhere. With origins: 'all', no pattern is sent.
• Crawls stay on their site (no subdomains, no external links), poll Cloudflare every 2 seconds until done, and keep only pages read and within origins. One cancelled with the run, or running past crawlTimeoutMs, is cancelled at Cloudflare too, so it stops spending. One Cloudflare ends without completing fails.
• Limits. Markdown, each crawled page and a scrape in all are cut at maxPageBytes and marked truncated: true. Extracted data over it, or a screenshot over 16 MiB, comes back as a LIMIT_EXCEEDED result.
• Off-machine. Cloudflare fetches and renders the pages. Page content is the tools' result for the model to read: treat it as untrusted text.

#Costs

costMicros charges each call to the run's budget. Cloudflare bills browser time on its side, and json uses Workers AI, billed as such. On Cloudflare's free plan, browser time is 10 minutes a day and REST calls are rate limited (about one every 10 seconds).

#The client

cloudflareQuickActions({ accountId, apiToken }) gives every quick action. Each takes the page's url and, optionally, allowRequestPattern (regular expressions; the page loads only what matches one), and an optional { signal }.

The client checks only that url is http(s): keeping to origins is the tools' job, or yours. Its options are accountId, apiToken, baseUrl (https://api.cloudflare.com; https, or localhost/127.0.0.1) and fetch.

#Errors

The client fails with a MayuraError whose message names only the HTTP status, never what Cloudflare wrote:

In the tools, INVALID_INPUT, PERMISSION_DENIED and LIMIT_EXCEEDED come back as the tool's result, { error, message }, for the model to put right. Other failures fail the call: TOOL_FAILED, TIMEOUT (a crawl past crawlTimeoutMs) and CANCELLED (the run was cancelled during a crawl).

Configuration mistakes, such as an account id that is not 32 hex characters, missing origins or maxCrawlPages over 100, fail with INVALID_CONFIG when you call cloudflareQuickActions() or quickActionTools(), before anything is sent.

#How it is tested

• Unit tests run the client and tools against a fake Browser Run API that checks every request: each action's path, token and body, failures without Cloudflare's text, crawls kept to their site, started, polled and cancelled, the request patterns built from origins, the tools' permissions, pages bounded, other sites refused as results, screenshots as images, JSON bounded, and a call blocked without its permission.
• scripts/live/cloudflare-quick-action.mjs runs each action once against Cloudflare on a public page (markdown, content, links, scrape, screenshot, a tool call with allowRequestPattern, and a crawl): all 7 checks passed on October 6, 2026.

#Related

• Browsers: browsers, origins and web data without a browser.
• Cloudflare Browser Run browsers: a Browser Run session to drive over CDP.
• Firecrawl browsers and web tools: scrape, map, search, crawl and extract as tools.