PHPackages                             meirdick/prism-workers-ai - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. meirdick/prism-workers-ai

ActiveLibrary

meirdick/prism-workers-ai
=========================

Cloudflare Workers AI provider for Prism PHP — routes through AI Gateway /compat endpoint

v0.3.0(1mo ago)1138↓50%MITPHPPHP ^8.2CI passing

Since Mar 18Pushed 1mo agoCompare

[ Source](https://github.com/meirdick/prism-workers-ai)[ Packagist](https://packagist.org/packages/meirdick/prism-workers-ai)[ RSS](/packages/meirdick-prism-workers-ai/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (5)Used By (0)

Prism Workers AI
================

[](#prism-workers-ai)

Cloudflare Workers AI provider for [Prism PHP](https://github.com/prism-php/prism) and [Laravel AI SDK](https://github.com/laravel/ai) — routes through the AI Gateway `/compat` endpoint.

Works with both `Prism::text()->using('workers-ai', ...)` and `agent()->prompt(provider: 'workers-ai')`.

Why this package?
-----------------

[](#why-this-package)

Workers AI's OpenAI-compatible `/compat` endpoint has subtle differences from the OpenAI API that break Prism's built-in xAI driver:

1. **Array content format** — The xAI `MessageMap` wraps user content in `[{type: "text", text: "..."}]`. Workers AI expects a plain string.
2. **Structured output type mismatch** — `/compat` may return `content` as a JSON object instead of a string, causing TypeError crashes.
3. **Missing `content` field** — Workers AI requires `content` to always be present on assistant messages, even when empty (tool call responses).
4. **No embeddings** — The xAI driver doesn't support embeddings. This package does.

Installation
------------

[](#installation)

```
composer require meirdick/prism-workers-ai
```

The service provider is auto-discovered by Laravel. No additional setup needed.

Configuration
-------------

[](#configuration)

### Prism PHP (`config/prism.php`)

[](#prism-php-configprismphp)

```
'providers' => [
    'workers-ai' => [
        'api_key' => env('CLOUDFLARE_AI_API_TOKEN', ''),
        'url' => env('WORKERS_AI_URL'),
    ],
],
```

### Laravel AI SDK (`config/ai.php`)

[](#laravel-ai-sdk-configaiphp)

```
'providers' => [
    'workers-ai' => [
        'driver' => 'workers-ai',
        'key' => env('CLOUDFLARE_AI_API_TOKEN'),
        'url' => env('WORKERS_AI_URL'),
    ],
],
```

### Environment

[](#environment)

```
CLOUDFLARE_AI_API_TOKEN=your-cloudflare-api-token
WORKERS_AI_URL=https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_slug}/compat
```

> **Note:** The URL must end in `/compat`, not `/workers-ai/v1`. The SDK appends `/chat/completions` automatically.

Create a Cloudflare API token with `Workers AI: Read` permission at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens).

### Understanding the `workers-ai/` model prefix

[](#understanding-the-workers-ai-model-prefix)

The AI Gateway has two OpenAI-compatible endpoints for Workers AI:

EndpointURLModel formatUniversal (recommended)`.../compat``workers-ai/@cf/meta/...`Provider-specific`.../workers-ai/v1``@cf/meta/...`This package targets the `/compat` endpoint. The `workers-ai/` prefix in model names tells the gateway which provider to route to. The gateway strips the prefix internally — responses return just `@cf/...`.

Usage
-----

[](#usage)

### With Prism PHP

[](#with-prism-php)

```
use Prism\Prism\Facades\Prism;

// Text generation
$response = Prism::text()
    ->using('workers-ai', 'workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast')
    ->withPrompt('Hello!')
    ->asText();

// Structured output
$response = Prism::structured()
    ->using('workers-ai', 'workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast')
    ->withSchema($schema)
    ->withPrompt('Classify this intent.')
    ->generate();

// Embeddings
$response = Prism::embeddings()
    ->using('workers-ai', 'workers-ai/@cf/baai/bge-large-en-v1.5')
    ->fromInput('Hello world')
    ->generate();

// Streaming
$stream = Prism::text()
    ->using('workers-ai', 'workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast')
    ->withPrompt('Tell me a story')
    ->asStream();

// Tool calling
$response = Prism::text()
    ->using('workers-ai', 'workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast')
    ->withTools([$weatherTool])
    ->withMaxSteps(3)
    ->withPrompt('What is the weather?')
    ->asText();

// Reasoning models (Kimi K2.5) — thinking content extracted automatically
$response = Prism::text()
    ->using('workers-ai', 'workers-ai/@cf/moonshotai/kimi-k2.5')
    ->withMaxTokens(2000) // reasoning models need higher max_tokens
    ->withPrompt('What is 15 * 37?')
    ->asText();

$response->text; // "555"
$response->steps[0]->additionalContent['thinking']; // "The user is asking for the product of 15 and 37..."

// Streaming with thinking events
$stream = Prism::text()
    ->using('workers-ai', 'workers-ai/@cf/moonshotai/kimi-k2.5')
    ->withMaxTokens(2000)
    ->withPrompt('Explain briefly why the sky is blue.')
    ->asStream();

foreach ($stream as $event) {
    // ThinkingStartEvent, ThinkingEvent (deltas), ThinkingCompleteEvent
    // then TextStartEvent, TextDeltaEvent, TextCompleteEvent
}

// Session affinity (prefix caching for multi-turn conversations)
$response = Prism::text()
    ->using('workers-ai', 'workers-ai/@cf/moonshotai/kimi-k2.5')
    ->withProviderOptions(['session_affinity' => 'ses_' . $conversation->id])
    ->withMaxTokens(2000)
    ->withPrompt('Follow-up question...')
    ->asText();
```

### With Laravel AI SDK

[](#with-laravel-ai-sdk)

```
use function Laravel\Ai\agent;

// Text generation via agent
$response = agent(instructions: 'You are a helpful assistant.')
    ->prompt('Hello!', provider: 'workers-ai');

// With explicit model
$response = agent(instructions: 'Be brief.')
    ->prompt('Hello!',
        provider: 'workers-ai',
        model: 'workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast',
    );

// Via agent class attributes
#[Provider('workers-ai')]
#[Model('workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast')]
class MyAgent implements Agent, Conversational { ... }
```

Recommended Models
------------------

[](#recommended-models)

ModelUse Case`workers-ai/@cf/moonshotai/kimi-k2.5`Frontier — smartest (256K context, reasoning, vision, tool calling)`workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast`General purpose (best quality/speed)`workers-ai/@cf/meta/llama-3.1-8b-instruct`Fast/cheap tasks`workers-ai/@cf/qwen/qwq-32b`Reasoning`workers-ai/@cf/qwen/qwen2.5-coder-32b-instruct`Code generation`workers-ai/@cf/baai/bge-large-en-v1.5`Embeddings (1024 dimensions)> **Reasoning models:** Kimi K2.5 is a thinking model — it reasons before answering. Set `withMaxTokens(2000)` or higher, as reasoning tokens count against the limit. The thinking chain is available in `$response->steps[0]->additionalContent['thinking']`.

All model names must be prefixed with `workers-ai/` when routing through AI Gateway, so the gateway knows which provider to route to.

How it works
------------

[](#how-it-works)

The package registers a `workers-ai` provider at two levels:

1. **Prism layer** — via `PrismManager::extend()`, handling the actual HTTP requests with correct content formatting
2. **Laravel AI SDK layer** — via `AiManager::extend()`, bridging the `workers-ai` driver to the Prism provider

The Laravel AI SDK bridge includes a `PrismGateway` subclass that overrides `configure()` to pass the driver name as a string to Prism, bypassing the SDK's hardcoded provider enum mapping. This override auto-disables itself when `laravel/ai` adds native support for custom Prism providers ([laravel/ai#283](https://github.com/laravel/ai/issues/283), [laravel/ai#284](https://github.com/laravel/ai/pull/284)).

Automated Setup
---------------

[](#automated-setup)

For a fully automated setup — including AI Gateway routing, environment configuration, and Workers AI registration — use the [laravel-cloudflare-ai-gateway](https://github.com/meirdick/laravel-cloudflare-ai-gateway) Claude Code skill:

```
npx skills add meirdick/laravel-cloudflare-ai-gateway
```

It handles installing this package, configuring your gateway URL, and wiring up all providers in a single guided workflow.

Testing
-------

[](#testing)

```
composer test
```

License
-------

[](#license)

MIT

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance90

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

51d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f0407fad46cce273ed6b210601247b4b73a060bda91eba8f8f144a3850a49d48?d=identicon)[meirdick](/maintainers/meirdick)

---

Top Contributors

[![meirdick](https://avatars.githubusercontent.com/u/3604649?v=4)](https://github.com/meirdick "meirdick (4 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/meirdick-prism-workers-ai/health.svg)

```
[![Health](https://phpackages.com/badges/meirdick-prism-workers-ai/health.svg)](https://phpackages.com/packages/meirdick-prism-workers-ai)
```

###  Alternatives

[laravel/ai

The official AI SDK for Laravel.

732506.3k60](/packages/laravel-ai)[prism-php/relay

A Prism tool for interacting with MCP servers

15236.1k3](/packages/prism-php-relay)[vizra/vizra-adk

Vizra Agent Development Kit - A comprehensive Laravel package for building intelligent AI agents.

29026.1k](/packages/vizra-vizra-adk)[elegantly/laravel-translator

All on one translations management for Laravel

6216.9k](/packages/elegantly-laravel-translator)[kirschbaum-development/laravel-loop

Laravel Loop is an MCP (Model Context Protocol) Server for Laravel

12814.4k1](/packages/kirschbaum-development-laravel-loop)[prism-php/bedrock

A provider for Prism adding support for AWS Bedrock.

35116.8k1](/packages/prism-php-bedrock)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)