---
title: "Overview"
description: "What the package does, what it adds to Laravel AI, and where to start."
---

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

# Overview

`meirdick/laravel-cf-workersai` is a [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) provider for the [Laravel AI SDK](https://laravel.com/docs/ai-sdk): text, embeddings, reranking, images, speech, transcription, Clef decisions and Clairic typed extraction, with AI Gateway routing. Install it, add a `workers-ai` entry to `config/ai.php`, and Laravel AI calls run on the models Cloudflare hosts.

## What you can do

| Task | API | Default model |
| --- | --- | --- |
| Generate text, call tools, stream | `agent()` | `@cf/meta/llama-3.3-70b-instruct-fp8-fast` |
| Create embeddings | `Embeddings::for()` | `@cf/baai/bge-large-en-v1.5` |
| Answer typed questions about an input | `Classification::of()`, `Str::decide()` | `@cf/cloudflare/clef` |
| Read or predict typed values from an input | `Extraction::of()` | `@cf/cloudflare/clairic` |
| Order documents by relevance | `Reranking::of()` | `@cf/baai/bge-reranker-base` |
| Generate images | `Image::of()` | `@cf/black-forest-labs/flux-2-klein-4b` |
| Turn text into speech | `Audio::of()` | `@cf/deepgram/aura-2-en` |
| Turn audio into text | `Transcription::of()` | `@cf/openai/whisper-large-v3-turbo` |
| Read PDF, Word and Excel files | `Markdown::of()`, `convert_documents` | Cloudflare's `/ai/tomarkdown` |
| Search the web from a tool call | `CloudflareWebSearch` | Cloudflare's Web Search API |

Clef uses the Laravel AI classification API. Clairic has no Laravel AI API, so the package adds `Extraction`. See [Clef](/docs/system-one/clef/) and [Clairic](/docs/system-one/clairic/).

## What the package adds

Laravel AI's `openai-compatible` driver can call a Cloudflare URL. It is enough if you generate text with one model and every agent has `#[MaxTokens]`. This package also does these things:

- Sends a 4096 token cap by default. With no cap, Cloudflare stops most models at 256 tokens.
- Throws `EmptyResponseException` when a reasoning model returns HTTP 200 with no text.
- Sends `reasoning_effort`, which Laravel AI does not have.
- Reports the neurons Cloudflare meters on every model call, with the `WorkersAiUsageReported` event.
- Retries HTTP 429 and Cloudflare edge errors, and maps them for Laravel AI failover.
- Sends the second token that an authenticated AI Gateway needs.
- Calls Clef, Clairic, images, speech, transcription and reranking, which the `openai-compatible` driver cannot reach on Cloudflare.

## How it reaches Cloudflare

Calls go directly to Workers AI, or through [AI Gateway](https://developers.cloudflare.com/ai-gateway/) for logs, caching and rate limits. Both use the same calling code, and only the config differs. See [Direct and gateway routes](/docs/concepts/routes/).

## Requirements

- PHP 8.3 or later.
- `laravel/ai` 0.9 to 1.3. Clef needs 1.0 or later.
- A Cloudflare account and an API token.

## Next steps

- Install the package with the [Quickstart](/docs/quickstart/).
- Choose a connection with [Direct and gateway routes](/docs/concepts/routes/).
- See every config key in [Configuration](/docs/reference/configuration/).

Source: https://laravel-cf-workersai-docs.mdick85.workers.dev/docs/overview/index.mdx