#Appendix A: Provider Reference

The Laravel AI SDK supports a growing list of AI providers through the Laravel\AI\Enums\Lab enum. Each provider supports a different combination of features. This appendix provides a complete reference for choosing and configuring providers.

#A.1 Provider Feature Matrix

Note: Feature availability reflects the SDK's v0.2.x release. Providers may add features in future SDK versions.

#A.2 Recommended Models per Provider

#Text Generation

#Image Generation

#Text-to-Speech

#Speech-to-Text

#Embeddings

#Reranking

#A.3 Provider Configuration

Every provider requires an API key set in your .env file. The naming convention follows the pattern {PROVIDER}_API_KEY:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
GROQ_API_KEY=gsk_...
XAI_API_KEY=xai-...
DEEPSEEK_API_KEY=sk-...
MISTRAL_API_KEY=...
COHERE_API_KEY=...
ELEVENLABS_API_KEY=...
JINA_API_KEY=...
VOYAGEAI_API_KEY=...

For providers with custom URL support, you can override the base URL:

OPENAI_URL=https://your-proxy.example.com/v1
OLLAMA_URL=http://localhost:11434

Azure requires additional configuration:

AZURE_API_KEY=...
AZURE_URL=https://your-resource.openai.azure.com
AZURE_API_VERSION=2024-12-01-preview

#Appendix B: Complete API Reference

This appendix catalogs every Artisan command, interface, trait, method, attribute, and fluent API surface in the Laravel AI SDK.

#B.1 Artisan Commands

#B.2 Agent Interfaces

#Laravel\AI\Contracts\Agent

The base interface for all agents. Requires:

public function instructions(): string;

#Laravel\AI\Contracts\Conversational

Enables multi-turn conversation memory. Requires:

public function id(): string|int;

#Laravel\AI\Contracts\HasTools

Declares that the agent can use tools. Requires:

/** @return array<int, class-string> */
public function tools(): array;

#Laravel\AI\Contracts\HasStructuredOutput

Declares that the agent returns structured JSON output. Requires:

public function schema(): array;

#Laravel\AI\Contracts\HasMiddleware

Declares that the agent uses middleware. Requires:

/** @return array<int, class-string|object> */
public static function middleware(): array;

#B.3 Agent Traits

#Promptable

Automatically included on all agents. Provides:

• prompt(string $message): AgentResponse — Send a prompt and receive a response.
• stream(string $message): StreamedAgentResponse — Stream a response via SSE.
• queue(string $message): PendingAgentTask — Queue the prompt for background processing.
• broadcastOnQueue(string $message): PendingAgentTask — Queue and broadcast streamed events.
• forUser(Authenticatable $user): static — Scope the agent to a specific user.
• continue(string $conversationId): static — Resume a previous conversation.
• make(): static — Create an agent instance via the container.

#RemembersConversations

Adds automatic conversation persistence. When applied alongside Conversational, the agent automatically stores and retrieves conversation history from the database without manual intervention.

#B.4 Configuration Attributes

These PHP 8.4 attributes are applied to agent classes to configure behavior:

Usage example:

use Laravel\AI\Attributes\{Provider, Model, MaxSteps, Temperature};
use Laravel\AI\Enums\Lab;

#[Provider(Lab::Anthropic)]
#[Model('claude-sonnet-4-20250514')]
#[MaxSteps(5)]
#[Temperature(0.3)]
class AnalysisAgent implements Agent
{
    // ...
}

#B.5 Image API

use Laravel\AI\Facades\Image;

Image::of('A sunset over a mountain lake')  // Set the prompt
    ->on(Lab::OpenAI)                        // Set the provider
    ->using('gpt-image-1')                   // Set the model
    ->generate();                            // Returns ImageResponse

// Aspect ratio helpers
Image::of('...')->square()->generate();      // 1:1
Image::of('...')->portrait()->generate();    // 3:4 or similar
Image::of('...')->landscape()->generate();   // 4:3 or similar

// Quality and timeout
Image::of('...')->quality('hd')->timeout(120)->generate();

// Attachments (image remixing)
Image::of('Make this logo blue')
    ->attachments([Document::fromPath('/path/to/logo.png')])
    ->generate();

// Storage
Image::of('...')->store('images');                        // Default disk
Image::of('...')->storeAs('images', 'hero.png');          // Custom filename
Image::of('...')->storePublicly('images');                // Public disk
Image::of('...')->storePubliclyAs('images', 'hero.png'); // Public + name

// Queued generation
Image::of('...')
    ->store('images')
    ->queue()
    ->then(fn ($path) => logger()->info("Stored: {$path}"))
    ->catch(fn ($e) => logger()->error($e->getMessage()));

#B.6 Audio API

use Laravel\AI\Facades\Audio;

Audio::of('Welcome to our application.')    // Set the text
    ->on(Lab::OpenAI)                       // Set the provider
    ->using('tts-1-hd')                     // Set the model
    ->generate();                           // Returns AudioResponse

// Voice selection
Audio::of('...')->male()->generate();       // Male voice
Audio::of('...')->female()->generate();     // Female voice
Audio::of('...')->voice('shimmer')->generate(); // Specific named voice

// Instructions for delivery style
Audio::of('Breaking news: ...')
    ->instructions('Speak with urgency and energy.')
    ->generate();

// Storage
Audio::of('...')->store('audio');
Audio::of('...')->storeAs('audio', 'welcome.mp3');
Audio::of('...')->storePublicly('audio');
Audio::of('...')->storePubliclyAs('audio', 'welcome.mp3');

// Queued generation
Audio::of('...')->store('audio')->queue();

#B.7 Transcription API

use Laravel\AI\Facades\Transcription;

// Source methods
Transcription::fromPath('/absolute/path/to/audio.mp3');
Transcription::fromStorage('audio/recording.mp3');
Transcription::fromUpload($request->file('audio'));

// Generate
$text = Transcription::fromPath('...')->generate();

// Provider and model
Transcription::fromPath('...')
    ->on(Lab::OpenAI)
    ->using('gpt-4o-transcribe')
    ->generate();

// Speaker diarization
$transcript = Transcription::fromPath('...')
    ->diarize()
    ->generate();

// Queued transcription
Transcription::fromPath('...')
    ->queue()
    ->then(fn ($text) => /* process */)
    ->catch(fn ($e) => /* handle error */);

#B.8 Embeddings API

use Illuminate\Support\Str;
use Laravel\AI\Facades\Embeddings;

// Quick string helper
$vector = Str::toEmbeddings('The quick brown fox');

// Full fluent API
$vectors = Embeddings::for('The quick brown fox')
    ->on(Lab::OpenAI)
    ->using('text-embedding-3-small')
    ->dimensions(1536)
    ->cache(seconds: 3600)
    ->generate();

// Batch embeddings
$vectors = Embeddings::for([
    'First document',
    'Second document',
    'Third document',
])->generate();

#B.9 Reranking API

use Laravel\AI\Facades\Reranking;

// Rerank an array of documents
$ranked = Reranking::of([
    'Laravel is a PHP framework',
    'React is a JavaScript library',
    'Vue.js works great with Laravel',
])
->on(Lab::Cohere)
->using('rerank-v3.5')
->limit(2)
->rerank('best framework for PHP');

// Rerank a Laravel collection (macro)
$articles = Article::all();
$ranked = $articles->rerank(
    query: 'machine learning tutorials',
    key: 'content',
    limit: 5
);

#B.10 Files API

use Laravel\AI\Facades\Files;
use Laravel\AI\Attachments\Document;
use Laravel\AI\Attachments\Image as ImageAttachment;

// Creating file references
$doc = Document::fromPath('/path/to/file.pdf');
$doc = Document::fromStorage('documents/file.pdf');
$doc = Document::fromUrl('https://example.com/file.pdf');
$doc = Document::fromString('raw content', 'file.txt');
$doc = Document::fromUpload($request->file('document'));
$doc = Document::fromId('file-abc123', Lab::OpenAI);

$img = ImageAttachment::fromPath('/path/to/image.png');
$img = ImageAttachment::fromUrl('https://example.com/photo.jpg');

// File operations with providers
Files::on(Lab::OpenAI)->put($document);   // Upload to provider
Files::on(Lab::OpenAI)->get('file-id');   // Retrieve file metadata
Files::on(Lab::OpenAI)->delete('file-id');// Delete from provider

#B.11 Stores API (Vector Stores)

use Laravel\AI\Facades\Stores;

// Create a vector store
$store = Stores::on(Lab::OpenAI)->create('knowledge-base');

// Get an existing store
$store = Stores::on(Lab::OpenAI)->get('vs_abc123');

// Delete a store
Stores::on(Lab::OpenAI)->delete('vs_abc123');

// Add files to a store
Stores::on(Lab::OpenAI)->add('vs_abc123', [
    Document::fromPath('/path/to/doc1.pdf'),
    Document::fromStorage('docs/doc2.pdf'),
]);

// Remove files from a store
Stores::on(Lab::OpenAI)->remove('vs_abc123', ['file-id-1', 'file-id-2']);

#B.12 Vector Query Methods (Eloquent)

These methods are available on Eloquent models with vector columns when using PostgreSQL with pgvector:

use App\Models\Article;

Article::query()
    ->whereVectorSimilarTo('embedding', $queryVector)
    ->whereVectorDistanceLessThan('embedding', $queryVector, 0.5)
    ->selectVectorDistance('embedding', $queryVector)
    ->orderByVectorDistance('embedding', $queryVector)
    ->limit(10)
    ->get();

#Appendix C: Event Reference

The Laravel AI SDK dispatches events at key points throughout every operation. You can listen to these events for logging, monitoring, rate-limit tracking, billing, or custom business logic. Register listeners in your EventServiceProvider or use closures in AppServiceProvider::boot().

All events live in the Laravel\AI\Events namespace.

#C.1 Agent Events

#C.2 Tool Events

#C.3 Image Events

#C.4 Audio Events

#C.5 Embeddings Events

#C.6 Reranking Events

#C.7 File and Store Events

#C.8 Listening to Events

// In EventServiceProvider
protected $listen = [
    \Laravel\AI\Events\AgentPrompted::class => [
        \App\Listeners\LogAgentUsage::class,
    ],
];

// Or in AppServiceProvider::boot()
use Illuminate\Support\Facades\Event;
use Laravel\AI\Events\AgentPrompted;

Event::listen(AgentPrompted::class, function (AgentPrompted $event) {
    logger()->info('Agent prompted', [
        'agent' => get_class($event->agent),
        'tokens' => $event->response->usage(),
    ]);
});

#Appendix D: Troubleshooting Guide

This appendix covers the most common issues encountered when working with the Laravel AI SDK and provides tested solutions.

#D.1 Missing or Invalid API Keys

Symptom: RuntimeException: No API key configured for provider [openai].

Solution: Ensure the correct environment variable is set in your .env file. Each provider follows the convention {PROVIDER}_API_KEY. After adding or changing a key, clear the config cache:

php artisan config:clear

Verify the key is loaded:

php artisan tinker
>>> config('ai.providers.openai.key')

If using Laravel Forge or Vapor, set the environment variable in the hosting platform's environment settings and redeploy.

#D.2 Provider Not Supported for Feature

Symptom: InvalidArgumentException: Provider [deepseek] does not support [image_generation].

Solution: Not all providers support all features. Consult the Provider Feature Matrix in Appendix A. Choose a provider that supports the feature you need:

// DeepSeek doesn't support images — use OpenAI instead
Image::of('A sunrise')->on(Lab::OpenAI)->generate();

#D.3 Timeout Errors

Symptom: ConnectionException: cURL error 28: Operation timed out.

Causes and solutions:

1. Long-running prompts: Increase the timeout on your agent with the #[Timeout(120)] attribute or pass it fluently.
2. Image generation: Image models can take 30–90 seconds. Use ->timeout(120) on the Image facade.
3. Large transcriptions: Audio files over 10 minutes may need extended timeouts. Consider splitting large files.
4. PHP configuration: Ensure max_execution_time in php.ini exceeds your longest expected AI operation.
5. Queue workers: When using queues, set the --timeout flag on the worker above your expected operation time: php artisan queue:work --timeout=300.

#D.4 Rate Limit Errors

Symptom: 429 Too Many Requests or RateLimitException.

Solutions:

1. Implement backoff: Use Laravel's retry helper or the SDK's built-in failover.
2. Queue with throttling: Use a rate-limited queue to spread requests over time:

// In your queue configuration (config/queue.php)
'redis' => [
    'driver' => 'redis',
    'connection' => 'default',
    'queue' => 'ai',
    'retry_after' => 300,
],

3. Multi-provider failover: Configure multiple providers so the agent falls back when one is rate-limited.
4. Track usage with events: Listen to AgentPrompted and ImageGenerated events to monitor your consumption rate and alert before you hit limits.

#D.5 pgvector Installation Issues

Symptom: ERROR: could not open extension control file "pgvector" or type "vector" does not exist.

Step-by-step fix:

1. Install the pgvector extension (Ubuntu/Debian):

sudo apt install postgresql-17-pgvector

On macOS with Homebrew:

brew install pgvector

2. Enable in PostgreSQL:

CREATE EXTENSION IF NOT EXISTS vector;

3. For Docker environments, use an image with pgvector pre-installed:

# docker-compose.yml
services:
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_DB: laravel
      POSTGRES_USER: laravel
      POSTGRES_PASSWORD: secret

4. Verify installation:

SELECT * FROM pg_extension WHERE extname = 'vector';

#D.6 Migration Failures

Symptom: SQLSTATE[42704]: Undefined object: 7 ERROR: type "vector" does not exist.

Solution: The pgvector extension must be created before any migration that uses vector columns. Create a migration that runs first (use an early timestamp):

// 0001_01_01_000000_create_pgvector_extension.php
return new class extends Migration {
    public function up(): void
    {
        DB::statement('CREATE EXTENSION IF NOT EXISTS vector');
    }

    public function down(): void
    {
        DB::statement('DROP EXTENSION IF EXISTS vector');
    }
};

Ensure this migration file has a timestamp earlier than any migration referencing vector columns.

#D.7 Queue Configuration for AI Jobs

Symptom: Queued AI operations never execute, silently fail, or time out.

Checklist:

1. Run the worker with sufficient timeout:

php artisan queue:work --queue=ai --timeout=300 --memory=512

2. Set the queue connection in .env:

QUEUE_CONNECTION=redis

3. Configure retry and backoff in your queue configuration to handle transient API failures.

4. Monitor failed jobs:

php artisan queue:failed
php artisan queue:retry all

5. Use Horizon for Redis-based queues to monitor AI job throughput and failure rates in a dashboard.

#D.8 Memory Limits with Large Embeddings

Symptom: Allowed memory size of X bytes exhausted when generating or processing embeddings.

Solutions:

1. Increase PHP memory limit:

; php.ini
memory_limit = 512M

2. Process in batches: Instead of embedding thousands of documents at once, chunk them:

$documents->chunk(100)->each(function ($batch) {
    Embeddings::for($batch->pluck('content')->toArray())->generate();
});

3. Reduce dimensions: Use the ->dimensions() method to request fewer dimensions when full fidelity isn't needed:

Embeddings::for($text)->dimensions(256)->generate();

4. Queue workers: Set --memory=512 on queue workers processing embedding jobs.

#D.9 Streaming Not Working

Symptom: Streamed responses arrive all at once instead of incrementally, or the connection drops.

Causes and solutions:

1. PHP output buffering: Disable output buffering for streaming routes:

ini_set('output_buffering', 'off');
ini_set('zlib.output_compression', false);

while (ob_get_level()) {
    ob_end_flush();
}

2. Nginx buffering: Add to your Nginx location block:

location /api/chat {
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header X-Accel-Buffering no;
    proxy_read_timeout 300s;
}

3. Apache: Enable mod_headers and set:

SetEnv no-gzip 1
Header set X-Accel-Buffering "no"

4. Laravel Octane: If using Octane with Swoole, ensure you're using the ->toResponse() method on stream responses, which handles Swoole's buffering correctly.

5. Cloudflare / CDN: Disable response buffering for your streaming endpoints, or use WebSocket-based broadcasting instead of SSE.

#D.10 Common Debugging Techniques

When all else fails, these techniques help isolate issues:

// 1. Test provider connectivity in Tinker
php artisan tinker
>>> (new \App\Agents\MyAgent)->prompt('Hello');

// 2. Enable HTTP client logging
// In AppServiceProvider::boot():
Http::globalMiddleware(
    Middleware::log(logger(), new MessageFormatter(MessageFormatter::DEBUG))
);

// 3. Listen to all AI events
Event::listen('Laravel\AI\Events\*', function ($eventName, $data) {
    logger()->debug($eventName, ['data' => $data]);
});

// 4. Check provider status pages
// OpenAI: status.openai.com
// Anthropic: status.anthropic.com
// Google AI: status.cloud.google.com

#Appendix E: Resources and Further Reading

#E.1 Official Laravel Resources

#E.2 Community Tutorials and Guides

#E.3 Related PHP Libraries

#E.4 AI Provider Documentation

#E.5 Conference Talks and Videos

#E.6 Foundational AI Concepts

For readers who want to deepen their understanding of the AI concepts underlying the SDK:

#E.7 Staying Current

The AI landscape evolves rapidly. To stay current with Laravel AI developments:

1. Star the repositories: Watch github.com/laravel/ai and github.com/laravel/mcp for release notifications.
2. Follow Laravel News: The editorial team covers SDK updates promptly.
3. Join the Laravel Discord: The #ai channel is active with SDK discussions and community support.
4. Subscribe to provider changelogs: Each AI provider publishes model updates and API changes that may affect your applications.
5. Test against canary releases: Use composer require laravel/ai:dev-main in a staging environment to preview upcoming features before they land in stable releases.

This concludes the appendices. For errata, updates, and supplementary materials, visit the book's companion repository.

Laravel is created and maintained by Taylor Otwell. The Laravel AI SDK and Laravel MCP are official Laravel packages built by Taylor Otwell and their respective contributor communities. This book is an independent community guide and is not affiliated with or endorsed by Laravel LLC.