Skip to content

Quickstart

Install the package, connect directly or through AI Gateway, and make your first text, Clef and Clairic calls.

Updated

In step 2 you choose how to reach Cloudflare. You can change that later without touching your calling code.

Before you start

You need:

1. Install and get your credentials

  1. Install the package

    composer require meirdick/laravel-cf-workersai

    Laravel’s package discovery registers the provider, so there’s nothing to publish from this package.

  2. 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"
  3. 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.

  4. 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 .env in 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-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'),
],

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.0

Pull 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

Type to search…

↑↓ navigate↵ selectEsc close