Limits and FAQ

Limits

• Text, embeddings, Clef classification, Clairic extraction and image input.
• Clairic is a Cloudflare preview model. Its behavior can change.
• Clef and Clairic do not use the /compat path. A url that ends in /compat throws for those calls.
• Chat models take no audio or video attachments. Documents need convert_documents. See Documents.
• nova-3 cannot run through AI Gateway. See Non-JSON models.
• No Laravel AI provider tools. CloudflareWebSearch is a normal tool that searches the web.
• No request concurrency limit. The package retries HTTP 429. It does not prevent it.
• The package does not check model names.
• The package does not set up your AI Gateway. Create and configure it in the Cloudflare dashboard.
• Reasoning controls depend on the model. Some models ignore reasoning_effort.
• Timing and rate figures in these docs come from tests on one account. Your results can differ.

FAQ

Do I need AI Gateway?

No. Set only account_id to call Workers AI directly. Add gateway to get logs, analytics, caching and gateway retries. See AI Gateway.

Do I need AI Gateway for Clef and Clairic?

No. Both work on the direct route. Set account_id and key. Add gateway only if you want gateway logs. The package sends it as the cf-aig-gateway-id header.

What is the difference between this package and the openai-compatible driver?

The Laravel AI openai-compatible driver works with the Cloudflare /compat URL. If you use one model for text and set #[MaxTokens] on every agent, that driver can be enough.

Use this package when you need one or more of these:

• A default token cap. Without a cap, Cloudflare stops most models at 256 tokens.
• An exception when a reasoning model spends its whole budget on thinking and returns nothing.
• reasoning_effort control.
• Neuron figures for cost tracking.
• Automatic retry of HTTP 429 and of Cloudflare edge errors.
• An AI Gateway with Authenticated Gateway turned on.
• Clef classification and Clairic extraction. The built-in driver has neither.

Which token permission do I need?

A token with the permission named Account > Workers AI > Read in the Cloudflare dashboard. For an authenticated gateway, chat and embeddings also need gateway_token.

Does it work with Laravel Cloud, queues and Horizon?

The package is a normal Cloudflare Workers AI provider for Laravel AI. It makes HTTP calls with the Laravel HTTP client. Anything Laravel AI supports for queued agents works the same. Set #[Timeout] to fit your job timeout.

Which model should I use?

For agents with tools, start with @cf/openai/gpt-oss-120b. For a cheap model, use #[UseCheapestModel]. Test your own prompts. See Models.

Why does my reasoning model return nothing?

It used the whole token cap on thinking. See Reasoning models.

Can I use two Workers AI accounts?

Yes. Add two provider entries in config/ai.php, each with 'driver' => 'workers-ai' and its own account_id and key. Give each entry its own name.

Does the package send data anywhere except Cloudflare?

No. Requests go to the URL that your config resolves to.

Is the package production ready?

Version 1.3.0 is current. The 1.x line follows semantic versioning, and 1.0.0 was the first stable release. It supports laravel/ai 0.9 to 1.3. Clairic is a Cloudflare preview model, so test it on your own data. Read the changelog before you upgrade.

How do I report a bug?

Open an issue on GitHub.