---
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-docs.mdick85.workers.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](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
   ```

   Package discovery registers the provider. This package has nothing to publish.
2. **Publish the Laravel AI config**

   Skip this step if `config/ai.php` exists.

   ```bash
   php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
   ```
3. **Find your account ID**

   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 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**

   Go to your profile, then API Tokens, then Create Token. Add the permission Account, Workers AI, Read. Copy the token. Cloudflare shows it once. You 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** adds AI Gateway request logs, caching and rate limits. Start with the direct route if you are not sure. [Direct and gateway routes](/docs/concepts/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`.

### 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`. Copy it 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. This name is 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`. Copy it 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'),
],
```

Leave `CLOUDFLARE_AI_GATEWAY_TOKEN` empty unless Authenticated Gateway is on in the gateway settings. If it is on, create the 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`. Do not commit tokens, and do not write them in `config/ai.php`, which is in git. After `php artisan config:cache`, Laravel reads the cached values, so run it again after you change `.env`.

## 3. Make your first calls

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

Extract a value with Clairic:

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

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](/docs/troubleshooting/) for 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 has one default for each kind of call. Set the defaults in `config/ai.php`, and you can omit `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',
```

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](/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-docs.mdick85.workers.dev/docs/quickstart/index.mdx