Quickstart

This page takes you from composer require to a working call. You choose a route in step 2. You can change it later without changes to your calling code.

Before you start

You need:

• A Laravel app with laravel/ai installed. See the Laravel AI documentation.
• PHP 8.3 or later.
• A Cloudflare account.

1. Install and get your credentials

2. Choose a route

The direct route calls Workers AI and needs nothing else. The gateway route adds AI Gateway request logs, caching and rate limits. Start with the direct route if you are not sure. Direct and gateway routes compares them.

Each route has two parts. Your credentials go in your application’s .env file. The provider entry goes in config/ai.php, and it reads those values with env(). Do not write the values in config/ai.php.

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_AI_API_TOKEN=your-api-token

'workers-ai' => [
    'driver'     => 'workers-ai',
    'key'        => env('CLOUDFLARE_AI_API_TOKEN'),
    'account_id' => env('CLOUDFLARE_ACCOUNT_ID'),
],

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_AI_API_TOKEN=your-api-token
CLOUDFLARE_AI_GATEWAY=your-gateway-slug
CLOUDFLARE_AI_GATEWAY_TOKEN=

'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'),
],

3. Make your first calls

The same code runs on both routes. You can run 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 any 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 a 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

Extract a value with Clairic:

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

On the gateway route, open your gateway in the Cloudflare dashboard and go to Logs. Text calls show under compat.

If a call fails, look for the start of the message in this table. See Troubleshooting for the full list.

5. Omit the provider name

Laravel AI has one default for each kind of call. Set the defaults in config/ai.php, and you can omit 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',

Laravel AI’s default_for_classification is typesafe until you change it. A Clef call with no provider: goes to TypeSafe until then, and Str::decide() does too. 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_effort for reasoning models.
• Move to the gateway later with AI Gateway.