The three parts
Workers AI is the Cloudflare service that hosts the models, and you call it over HTTP. Cloudflare bills most models in neurons, its own usage unit, but it prices Clef and Clairic per input token.
AI Gateway is an optional Cloudflare proxy that sits between your app and the model. It adds request logs, cost analytics, caching and rate limits. You set it up in the Cloudflare dashboard; the package only sends requests to it.
Laravel AI (laravel/ai) is the Laravel package that gives you agent(), Embeddings, Classification, tools and streaming. It sends each request through a provider.
This package is that provider for Cloudflare Workers AI. It turns each Laravel AI call into a Workers AI request and turns the reply back into a Laravel AI response.
How it plugs into Laravel AI
The package registers one driver with Laravel AI, named workers-ai (with workersai as an alias). Each kind of call is handled by its own class, which Laravel AI calls a gateway. That’s a different thing from AI Gateway.
| Call | Handled by | Cloudflare API |
|---|---|---|
agent(), Embeddings::for() |
One gateway class, WorkersAiGateway |
OpenAI-compatible, /ai/v1 or /compat |
Classification::of(), Str::decide() |
WorkersAiClassificationGateway, on laravel/ai 1.0 and later |
/ai/run/{model} |
Extraction::of() |
WorkersAiExtractionGateway, on all versions |
/ai/run/{model} |
Reranking::of(), Image::of(), Audio::of(), Transcription::of() |
One gateway class for each | /ai/run/{model} |
Markdown::of(), convert_documents |
WorkersAiMarkdownGateway |
/ai/tomarkdown |
CloudflareWebSearch |
The tool itself | /ai/websearch |
The text gateway runs one model turn per call. Laravel AI runs the tool loop itself, so tool calls, message history and step limits work as they do on any other provider.
Laravel AI features work here too, including #[MaxTokens], #[Timeout], #[Provider], Ai::fakeAgent(), Classification::fake() and failover. Clairic isn’t part of Laravel AI, so Extraction brings its own fake(), events and failover, built the same way.
How the package picks a URL
It checks your config in this order and uses the first match:
- If
urlis set, text and embeddings go to that URL. - If
account_idandgatewayare set, they go to the gateway’s/compatpath. - If only
account_idis set, they go to the direct API.
Direct and gateway routes has the full table, with the URLs for Clef and Clairic.
What the package does for text calls
On a text call, the package:
- Sends a 4096 token cap when the call sets none. With no cap, Cloudflare stops most models at 256 tokens.
- Throws
EmptyResponseExceptionwhen a reasoning model returns HTTP 200 with no text. - Sends
reasoning_effort, which Laravel AI doesn’t have. - Dispatches
WorkersAiUsageReportedwith the neuron figure. - Retries HTTP 429, 502, 503, 504, 520, 522 and 524.
- Reads the reasoning text, whichever response key the model puts it in.
What the package does for run API calls
Clef, Clairic, reranking, images, speech and transcription use Cloudflare’s run API, /ai/run/{model}, instead of the OpenAI-compatible one. On those calls, the package:
- Puts the model ID in the URL and builds the request body each model expects. Clef and Clairic take a short model selector in the body, and some image models take a multipart form.
- Reads binary image and audio replies and returns them as Laravel AI responses.
- Reads a reply whether or not Cloudflare wraps it in its
resultenvelope. - Throws
AiExceptionwhen a 200 reply has an error or no output. - Dispatches
WorkersAiUsageReportedwith the neuron figure. - Applies the same retries,
headersand failover rules as text calls.