---
title: "Quickstart"
description: "Install the package, connect directly or through AI Gateway, and make your first text, Clef and Clairic calls."
---

> Documentation Index
> Fetch the complete documentation index at: https://laravel-cf-workersai.meirdick.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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/ai` installed. See the [Laravel AI documentation](https://laravel.com/docs/ai-sdk).
- PHP 8.3 or later.
- A Cloudflare account.

## 1. Install and get your credentials

1. **Install the package**

   ```bash
   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.

   ```bash
   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](https://dash.cloudflare.com) 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](https://developers.cloudflare.com/fundamentals/account/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](https://developers.cloudflare.com/fundamentals/api/get-started/create-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](/docs/concepts/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`.

### Direct

Add your credentials to your application's `.env` file:

```ini
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:

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

### Gateway

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:

```ini
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:

```php
'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](/docs/guides/ai-gateway/#authenticated-gateway).

> **Keep tokens out of git**
>
> Laravel's `.gitignore` already excludes `.env`. Don't commit tokens, and don't write them into `config/ai.php`, which is in git. If you've run `php artisan config:cache`, Laravel reads the cached values, so run it again whenever you change `.env`.

## 3. Make your first calls

The same code runs on both routes. You can try these calls in `php artisan tinker`.

Generate text:

```php
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:

```php
$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:

```php
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:

```php
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](/docs/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:`:

```php
'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](/docs/system-one/clef/) for decisions and [Clairic](/docs/system-one/clairic/) for typed values.
- Add [reranking](/docs/guides/reranking/), [images](/docs/guides/images/), [speech and transcription](/docs/guides/audio/), [documents](/docs/guides/documents/) or [web search](/docs/guides/web-search/).
- [Pick a model](/docs/guides/models/), and set [`reasoning_effort`](/docs/guides/reasoning/) for reasoning models.
- Move to the gateway later with [AI Gateway](/docs/guides/ai-gateway/).

Source: https://laravel-cf-workersai.meirdick.com/docs/quickstart/index.mdx
