AI Release Notes

v0.3.0

We've shipped a new release for the Agents SDK v0.3.0 bringing full compatibility with AI SDK v6 and introducing the unified tool pattern, dynamic tool approval, and enhanced React hooks with improved tool handling.

This release includes improved streaming and tool support, dynamic tool approval (for "human in the loop" systems), enhanced React hooks with onToolCall callback, improved error handling for streaming responses, and seamless migration from v5 patterns.

This makes it ideal for building production AI chat interfaces with Cloudflare Workers AI models, agent workflows, human-in-the-loop systems, or any application requiring reliable tool execution and approval workflows.

Additionally, we've updated workers-ai-provider v3.0.0, the official provider for Cloudflare Workers AI models, and ai-gateway-provider v3.0.0, the provider for Cloudflare AI Gateway, to be compatible with AI SDK v6.

The Overview tab is now the default view in AI Crawl Control. The previous default view with controls for individual AI crawlers is available in the Crawlers tab.

What's new

• Executive summary — Monitor total requests, volume change, most common status code, most popular path, and high-volume activity
• Operator grouping — Track crawlers by their operating companies (OpenAI, Microsoft, Google, ByteDance, Anthropic, Meta)
• Customizable filters — Filter your snapshot by date range, crawler, operator, hostname, or path

Get started

• 1. Log in to the Cloudflare dashboard and select your account and domain.
• 1. Go to AI Crawl Control, where the Overview tab opens by default with your activity snapshot.
• 1. Use filters to customize your view by date range, crawler, operator, hostname, or path.
• 1. Navigate to the Crawlers tab to manage controls for individual crawlers.

Learn more about analyzing AI traffic and managing AI crawlers.

Pay Per Crawl enhancements

Pay Per Crawl is introducing enhancements for both AI crawler operators and site owners, focusing on programmatic discovery, flexible pricing models, and granular configuration control.

For AI crawler operators

Discovery API

A new authenticated API endpoint allows verified crawlers to programmatically discover domains participating in Pay Per Crawl. Crawlers can use this to build optimized crawl queues, cache domain lists, and identify new participating sites. This eliminates the need to discover payable content through trial requests.

The API endpoint is

GET https://crawlers-api.ai-audit.cfdata.org/charged_zones

and requires Web Bot Auth authentication. Refer to
Discover payable content
for authentication steps, request parameters, and response schema.

Payment header signature requirement

Payment headers (crawler-exact-price or crawler-max-price) must now be included in the Web Bot Auth signature-input header components. This security enhancement prevents payment header tampering, ensures authenticated payment intent, validates crawler identity with payment commitment, and protects against replay attacks with modified pricing. Crawlers must add their payment header to the list of signed components when constructing the signature-input header.

New crawler-error header

Pay Per Crawl error responses now include a new crawler-error header with 11 specific error codes for programmatic handling. Error response bodies remain unchanged for compatibility. These codes enable robust error handling, automated retry logic, and accurate spending tracking.

For site owners

Configure free pages

Site owners can now offer free access to specific pages like homepages, navigation, or discovery pages while charging for other content. Create a Configuration Rule in Rules > Configuration Rules, set your URI pattern using wildcard, exact, or prefix matching on the URI Full field, and enable the Disable Pay Per Crawl setting. When disabled for a URI pattern, crawler requests pass through without blocking or charging.

Some paths are always free to crawl. These paths are: /robots.txt, /sitemap.xml, /security.txt, /.well-known/security.txt, /crawlers.json.

Get started

• AI crawler operators: Discover payable content | Crawl pages
• Site owners: Advanced configuration

Resumable streaming

The latest release of @cloudflare/agents brings resumable streaming, significant MCP client improvements, and critical fixes for schedules and Durable Object lifecycle management.

AIChatAgent now supports resumable streaming, allowing clients to reconnect and continue receiving streamed responses without losing data. This is useful for:

• Long-running AI responses
• Users on unreliable networks
• Users switching between devices mid-conversation
• Background tasks where users navigate away and return
• Real-time collaboration where multiple clients need to stay in sync

Streams are maintained across page refreshes, broken connections, and syncing across open tabs and devices.

Other improvements

• Default JSON schema validator added to MCP client
• Schedules can now safely destroy the agent

MCP client API improvements

The MCPClientManager API has been redesigned for better clarity and control:

• New registerServer() method: Register MCP servers without immediately connecting
• New connectToServer() method: Establish connections to registered servers
• Improved reconnect logic: restoreConnectionsFromStorage() now properly handles failed connections

The SDK now includes a formalized MCPConnectionState enum with states: idle, connecting, authenticating, connected, discovering, and ready.

Enhanced MCP discovery

MCP discovery fetches the available tools, prompts, and resources from an MCP server so your agent knows what capabilities are available. The MCPClientConnection class now includes a dedicated discover() method with improved reliability:

• Supports cancellation via AbortController
• Configurable timeout (default 15s)
• Discovery failures now throw errors immediately instead of silently continuing

Bug fixes

• Fixed a bug where schedules meant to fire immediately with this.schedule(0, ...) or this.schedule(new Date(), ...) would not fire
• Fixed an issue where schedules that took longer than 30 seconds would occasionally time out
• Fixed SSE transport now properly forwards session IDs and request headers
• Fixed AI SDK stream events convertion to UIMessageStreamPart

Upgrade

To update to the latest version:

npm i agents@latest

Workers AI Platform specifics

We've partnered with Black Forest Labs (BFL) to bring their latest FLUX.2 [dev] model to Workers AI! This model excels in generating high-fidelity images with physical world grounding, multi-language support, and digital asset creation. You can also create specific super images with granular controls like JSON prompting.

Read the BFL blog to learn more about the model itself. Read our Cloudflare blog to see the model in action, or try it out yourself on our multi modal playground.

Pricing documentation is available on the model page or pricing page. Note, we expect to drop pricing in the next few days after iterating on the model performance.

The model hosted on Workers AI is able to support up to 4 image inputs (512x512 per input image). Note, this image model is one of the most powerful in the catalog and is expected to be slower than the other image models we currently support. One catch to look out for is that this model takes multipart form data inputs, even if you just have a prompt.

With the REST API, the multipart form data input looks like this:

curl --request POST \
  --url 'https://api.cloudflare.com/client/v4/accounts/{ACCOUNT}/ai/run/@cf/black-forest-labs/flux-2-dev' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'prompt=a sunset at the alps' \
  --form steps=25 \
  --form width=1024 \
  --form height=1024

With the Workers AI binding, you can use it as such:

const form = new FormData();
form.append('prompt', 'a sunset with a dog');
form.append('width', '1024');
form.append('height', '1024');

//this dummy request is temporary hack
//we're pushing a change to address this soon
const formRequest = new Request('http://dummy', {
  method: 'POST',
  body: form
});
const formStream = formRequest.body;
const formContentType = formRequest.headers.get('content-type') || 'multipart/form-data';
const resp = await env.AI.run("@cf/black-forest-labs/flux-2-dev", {
  multipart: {
    body: formStream,
    contentType: formContentType
  }
});

The parameters you can send to the model are detailed here:

Multi-Reference Images

The FLUX.2 model is great at generating images based on reference images. You can use this feature to apply the style of one image to another, add a new character to an image, or iterate on past generate images. You would use it with the same multipart form data structure, with the input images in binary.

For the prompt, you can reference the images based on the index, like take the subject of image 1 and style it like image 0 or even use natural language like place the dog beside the woman.

Note: you have to name the input parameter as input_image_0, input_image_1, input_image_2 for it to work correctly. All input images must be smaller than 512x512.

JSON Prompting

The model supports prompting in JSON to get more granular control over images. You would pass the JSON as the value of the 'prompt' field in the multipart form data. See the JSON schema below on the base parameters you can pass to the model.

Other features to try

• The model also supports the most common latin and non-latin character languages
• You can prompt the model with specific hex codes like #2ECC71
• Try creating digital assets like landing pages, comic strips, infographics too!

AI Search: Custom HTTP headers for website crawling

AI Search now supports custom HTTP headers for website crawling, solving a common problem where valuable content behind authentication or access controls could not be indexed.

Previously, AI Search could only crawl publicly accessible pages, leaving knowledge bases, documentation, and other protected content out of your search results. With custom headers support, you can now include authentication credentials that allow the crawler to access this protected content.

This is particularly useful for indexing content like:

• Internal documentation behind corporate login systems
• Premium content that requires users to provide access to unlock
• Sites protected by Cloudflare Access using service tokens

To add custom headers when creating an AI Search instance, select Parse options. In the Extra headers section, you can add up to five custom headers per Website data source.

Example headers

For example, to crawl a site protected by Cloudflare Access, you can add service token credentials as custom headers:

CF-Access-Client-Id: your-token-id.access
CF-Access-Client-Secret: your-token-secret

The crawler will automatically include these headers in all requests, allowing it to access protected pages that would otherwise be blocked.

Learn more about configuring custom headers for website crawling in AI Search.

What's new

AI Crawl Control now supports per-crawler drilldowns with an extended actions menu and status code analytics. Drill down into Metrics, Cloudflare Radar, and Security Analytics, or export crawler data for use in WAF custom rules, Redirect Rules, and robots.txt files.

Status code distribution chart

The Metrics tab includes a status code distribution chart showing HTTP response codes (2xx, 3xx, 4xx, 5xx) over time. Filter by individual crawler, category, operator, or time range to analyze how specific crawlers interact with your site.

Extended actions menu

Each crawler row includes a three-dot menu with per-crawler actions:

• View Metrics
• Filter the AI Crawl Control Metrics page to the selected crawler.
• View on Cloudflare Radar
• Access verified crawler details on Cloudflare Radar.
• Copy User Agent
• Copy user agent strings for use in WAF custom rules, Redirect Rules, or robots.txt files.
• View in Security Analytics
• Filter Security Analytics by detection IDs (Bot Management customers).
• Copy Detection ID
• Copy detection IDs for use in WAF custom rules (Bot Management customers).

Get started

1. Log in to the Cloudflare dashboard, and select your account and domain.
2. Go to AI Crawl Control > Metrics to access the status code distribution chart.
3. Go to AI Crawl Control > Crawlers and select the three-dot menu for any crawler to access per-crawler actions.
4. Select multiple crawlers to use bulk copy buttons for user agents or detection IDs.

Learn more about AI Crawl Control.

Rerank for more relevant results

AI Search now supports reranking for improved retrieval quality and allows you to set the system prompt directly in your API requests.

You can enable and configure reranking in the dashboard or directly in your API requests:

const answer = await env.AI.autorag("my-autorag").aiSearch({
  query: "How do I train a llama to deliver coffee?",
  model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
  reranking: {
    enabled: true,
    model: "@cf/baai/bge-reranker-base"
  }
});

Set system prompts in API

Previously, system prompts could only be configured in the dashboard. You can now define them directly in your API requests, giving you per-query control over behavior. For example:

// Dynamically set query and system prompt in AI Search
async function getAnswer(query, tone) {
  const systemPrompt = `You are a ${tone} assistant.`;
  const response = await env.AI.autorag("my-autorag").aiSearch({
    query,
    system_prompt: systemPrompt
  });
  return response;
}

// Example usage
const query = "What is Cloudflare?";
const tone = "friendly";
const answer = await getAnswer(query, tone);
console.log(answer);

Learn more about Reranking and System Prompt in AI Search.

Supported file formats for Markdown Conversion

Developers can now programmatically retrieve a list of all file formats supported by the Markdown Conversion utility in Workers AI.

You can use the env.AI binding:

await env.AI.toMarkdown().supported()

Or call the REST API:

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown/supported \
-H 'Authorization: Bearer {API_TOKEN}'

Both return a list of file formats that users can convert into Markdown:

[
  {
    "extension": ".pdf",
    "mimeType": "application/pdf"
  },
  {
    "extension": ".jpeg",
    "mimeType": "image/jpeg"
  },
  ...
]

Learn more about our Markdown Conversion utility.