How it works | laravel-cf-workersai

The three parts

Workers AI is the Cloudflare service that hosts models. You call it over HTTP. Cloudflare meters most models in neurons. It prices Clef and Clairic per input token.

AI Gateway is an optional Cloudflare proxy 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 a Cloudflare Workers AI provider for Laravel AI. It turns Laravel AI calls into Workers AI requests.

How it plugs into Laravel AI

The package registers one driver in the Laravel AI manager. The driver name is workers-ai, and workersai is an alias.

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, so tool calls, message history and step limits work as on any other provider.

Laravel AI features work on this provider, including #[MaxTokens], #[Timeout], #[Provider], Ai::fakeAgent(), Classification::fake() and failover. Clairic is not part of Laravel AI, so Extraction has its own fake(), events and failover with the same shape.

How the package picks a URL

It reads your config in this order:

url is set. Text and embeddings go to that URL.
account_id and gateway are set. Text and embeddings go to the gateway’s /compat path.
account_id is set. Text and embeddings 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

Sends a 4096 token cap when the call sets none. With no cap, Cloudflare stops most models at 256 tokens.
Throws EmptyResponseException when a reasoning model returns HTTP 200 with no text.
Sends reasoning_effort, which Laravel AI does not have.
Dispatches WorkersAiUsageReported with the neuron figure.
Retries HTTP 429, 502, 503, 504, 520, 522 and 524.
Reads reasoning text from each key that models use.

What the package does for run API calls

Sends the model ID in the URL, and the request shape each model needs. Clef and Clairic take a short selector in the body. Some image models take multipart.
Reads binary image and audio replies, and returns them as Laravel AI responses.
Reads a reply with or without Cloudflare’s result envelope.
Throws AiException when a 200 reply has an error or no output.
Dispatches WorkersAiUsageReported with the neuron figure.
Applies the same retries, headers and failover rules as text calls.