In step 2 you choose how to reach Cloudflare. You can change that later without touching your calling code.
Before you start
You need:
- A Laravel app with
laravel/aiinstalled. See the Laravel AI documentation. - PHP 8.3 or later.
- A Cloudflare account.
1. Install and get your credentials
Install the package
composer require meirdick/laravel-cf-workersaiLaravel’s package discovery registers the provider, so there’s nothing to publish from this package.
Publish the Laravel AI config
This creates
config/ai.php, where the provider entry goes. Skip it if the file already exists.php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"Find your account ID
The package needs it to build the Workers AI URL. Sign in to the Cloudflare dashboard and select your account. The account ID is the 32-character string in the URL right after the host. See Find account and zone IDs.
Create an API token
The package sends this token on every call. Go to your profile, then API Tokens, then Create Token, and add the permission Account, Workers AI, Read. Copy the token now, because Cloudflare shows it only once. You’ll add it to
.envin step 2. See Create API token.
2. Choose a route
The direct route calls Workers AI and needs nothing else. The gateway route sends the same calls through AI Gateway, which adds request logs, caching and rate limits. If you’re not sure, start with the direct route. Direct and gateway routes compares them.
Either way, the setup has two parts. Your credentials go in your application’s .env file, and the provider entry in config/ai.php reads them with env(). Don’t write the values themselves into config/ai.php.
Add your credentials to your application’s .env file:
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_AI_API_TOKEN=your-api-tokenThen add this entry to the providers array in config/ai.php, exactly as it is:
'workers-ai' => [
'driver' => 'workers-ai',
'key' => env('CLOUDFLARE_AI_API_TOKEN'),
'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
],In the Cloudflare dashboard, go to AI, then AI Gateway, then Create Gateway. Copy the gateway name; the package calls it the slug.
Add your credentials and the slug to your application’s .env file:
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_AI_API_TOKEN=your-api-token
CLOUDFLARE_AI_GATEWAY=your-gateway-slug
CLOUDFLARE_AI_GATEWAY_TOKEN=Then add this entry to the providers array in config/ai.php, exactly as it is:
'workers-ai' => [
'driver' => 'workers-ai',
'key' => env('CLOUDFLARE_AI_API_TOKEN'),
'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
'gateway' => env('CLOUDFLARE_AI_GATEWAY'),
'gateway_token' => env('CLOUDFLARE_AI_GATEWAY_TOKEN'), // optional: only if Authenticated Gateway is on
],Leave CLOUDFLARE_AI_GATEWAY_TOKEN empty unless Authenticated Gateway is on in the gateway settings. If it’s on, create a token on that settings page and put it in .env. See Authenticated Gateway.
3. Make your first calls
The same code runs on both routes. You can try these calls in php artisan tinker.
Generate text:
use function Laravel\Ai\agent;
$response = agent('You are a helpful assistant.')->prompt('Say hi.', provider: 'workers-ai');
echo $response->text;Without model:, the package uses @cf/meta/llama-3.3-70b-instruct-fp8-fast. To use another model, pass its Workers AI model ID:
$response = agent('You are a helpful assistant.')->prompt(
'Summarize this in one sentence.',
provider: 'workers-ai',
model: '@cf/openai/gpt-oss-120b',
);Ask Clef, Cloudflare’s decision model, a yes or no question. This call needs laravel/ai 1.0 or later:
use Laravel\Ai\Classification;
use Laravel\Ai\Classification\Boolean;
$response = Classification::of('Checkout has been failing for every customer.')
->question('urgent', new Boolean('Is this support request urgent?'))
->classify(provider: 'workers-ai');
$response['urgent']->probability; // a value from 0.0 to 1.0Pull a typed value out of text with Clairic, Cloudflare’s extraction model:
use Meirdick\WorkersAi\Extraction;
use Meirdick\WorkersAi\Extraction\Number;
$invoice = Extraction::of('4 pallets at $250.00 each, shipping $80.00.')
->field('total', new Number(instructions: 'Amount due including shipping', unit: 'USD'))
->extract();
$invoice['total']->value();4. Check that it works
If you used the gateway route, open your gateway in the Cloudflare dashboard and go to Logs. Text calls show up under compat.
If a call fails, find the start of its error message in this table. Troubleshooting has the full list.
| Message starts with | Cause |
|---|---|
Workers AI requires an API token |
CLOUDFLARE_AI_API_TOKEN is empty in .env. |
Workers AI requires an account_id or explicit url |
CLOUDFLARE_ACCOUNT_ID is empty in .env. |
HTTP request returned status code 401 |
The token lacks the Workers AI Read permission, or the gateway is authenticated and CLOUDFLARE_AI_GATEWAY_TOKEN is empty. |
5. Omit the provider name
Laravel AI keeps a default provider for each kind of call. Set them to workers-ai in config/ai.php, and you can leave out provider::
'default' => 'workers-ai',
'default_for_embeddings' => 'workers-ai',
'default_for_classification' => 'workers-ai',
'default_for_reranking' => 'workers-ai',
'default_for_images' => 'workers-ai',
'default_for_audio' => 'workers-ai',
'default_for_transcription' => 'workers-ai',Out of the box, Laravel AI’s default_for_classification is typesafe, the provider for TypeSafe’s Jev decision model. Until you change it, a classification call or Str::decide() with no provider: goes to TypeSafe, not to Clef. Extraction finds the workers-ai provider without a default.
Next steps
- Use Clef for decisions and Clairic for typed values.
- Add reranking, images, speech and transcription, documents or web search.
- Pick a model, and set
reasoning_effortfor reasoning models. - Move to the gateway later with AI Gateway.