The Laravel AI SDK — available as the official laravel/ai package — is a first-party toolkit enabling PHP developers to build production-grade AI applications within Laravel. Released with Laravel 12 on February 5, 2026, and deemed production-stable with Laravel 13 on March 17, 2026, it has surpassed 2.5 million Packagist installs. Whether you're creating production-ready APIs or integrating AI features into a custom web application, this guide covers installation, agents, RAG, MCP integration, multi-agent pipelines, streaming, testing, and critical security considerations.

What Is the Laravel AI SDK?

The Laravel AI SDK is an official package (laravel/ai) that extends the community Prism PHP library with a Laravel-native ecosystem, including images, audio, vector embeddings, Model Context Protocol (MCP), and multi-agent pipelines. It integrates Prism with Laravel's scaffolding, Artisan commands, database migrations, and provider integrations, essential for production applications.

The SDK supports 14 AI providers out of the box: OpenAI, Anthropic, Google Gemini, Groq, Mistral, DeepSeek, xAI (Grok), Ollama, Azure OpenAI, Cohere, OpenRouter, Jina, VoyageAI, and ElevenLabs. Switching providers requires a single line change in your .env file.

Core Capabilities at a Glance

• Text generation — single-call or multi-turn conversation with memory
• Intelligent agents — tool-calling agents with built-in step limits
• Structured output — JSON-schema-validated PHP objects from AI responses
• Image generation — DALL-E 3, Gemini, xAI image models
• Audio synthesis and transcription — ElevenLabs TTS, Whisper transcription
• Vector embeddings and RAG — pgvector-backed similarity search in Eloquent
• MCP (Model Context Protocol) — connect agents to external tool servers
• Multi-agent pipelines — sequential, classifier-routed, and parallel patterns
• Streaming responses — server-sent events via Laravel Reverb and Echo

Based in Mumbai and need a Laravel development team that understands AI integration? We build custom AI-powered web applications for businesses across Mumbai, Andheri, and Navi Mumbai.

Prerequisites and Version Requirements

The Laravel AI SDK requires PHP 8.3 or higher and either Laravel 12 or Laravel 13. It does not support Laravel 11 or earlier, nor PHP 8.2. These are non-negotiable constraints.

Important note on versioning: the package is at v0.x, meaning breaking changes in minor version bumps are possible before v1.0.0 ships. Pin your composer constraint to ^0.8 (not *) to avoid surprise breakage on the next minor release. If you're on Laravel 12 below patch 12.62, upgrade the framework first — the illuminate/json-schema constraint won't resolve otherwise.

Installation and Configuration

Installing the Laravel AI SDK requires two commands and one environment variable. Execute these from your project root:

composer require laravel/ai
php artisan vendor:publish --tag=ai-config

This publishes config/ai.php to your application. Open your .env file and set your default provider and API key:

AI_PROVIDER=openai
OPENAI_API_KEY=sk-...
Additional supported provider keys:
ANTHROPIC_API_KEY, GEMINI_API_KEY, GROQ_API_KEY,
MISTRAL_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY,
OLLAMA_API_KEY, AZURE_OPENAI_API_KEY, COHERE_API_KEY,
OPENROUTER_API_KEY, JINA_API_KEY, VOYAGEAI_API_KEY,
ELEVENLABS_API_KEY

All 14 provider keys reside only in .env — accessed via Laravel's config() layer and never exposed to the frontend. Leaking any of these keys to a Next.js NEXT_PUBLIC_* variable is a serious security mistake covered in the security section below.

Choosing the Right Provider

For most new projects, OpenAI (GPT-4o-mini) is the best starting point — it's affordable, fast, and well-documented. If cost is crucial, Groq offers near-zero-latency inference at a fraction of OpenAI's price. For access to 100+ models through a single API key, OpenRouter is the aggregator to consider — though it adds a pricing markup and an extra network hop. For local development without API costs, Ollama runs models on your own machine.

Text Generation: From One Line to Full Pipelines

Text generation with the Laravel AI SDK starts with a single fluent chain: AI::text(). This is ideal for stateless, one-off generation tasks — summarizing a support ticket, drafting an email reply, or classifying input. It does not spin up an agent or persist memory.

// Simple text generation
$summary = AI::text()
->using('gpt-4o-mini')
->prompt('Summarize this in 3 bullet points: ' . $ticketContent)
->generate()
->text();

For multi-turn conversation with persistent memory, use Agent classes instead (covered in the next section). Use AI::text() for single-turn, stateless tasks — it's cheaper, faster, and avoids conversation memory tables.

Reading the Laravel performance guide before deploying AI features is recommended — text generation calls can block a PHP-FPM worker for 5–30 seconds if run synchronously in the HTTP request cycle.

Building Intelligent Agents with Tool Calling

Laravel AI agents are PHP classes extending Laravel\AI\Agent, holding system instructions, declaring tools, and optionally enforcing structured output. The Artisan scaffolding command creates the class with all required stubs:

php artisan make:agent SupportAgent
php artisan make:agent SupportAgent --structured  # with structured output
php artisan make:tool LookupOrderTool

A complete agent class looks like this:

// app/AI/Agents/SupportAgent.php
use Laravel\AI\Agent;
use Laravel\AI\Contracts\HasStructuredOutput;

class SupportAgent extends Agent implements HasStructuredOutput
{
protected string $instructions = 'You are a customer support agent for an e-commerce store.
Always look up the order before answering. Be concise and professional.';
public function tools(): array
{
    return [
        new LookupOrderTool(),
    ];
}

public function schema(JsonSchema $schema): array
{
    return [
        'score'   => $schema->integer()->required(),
        'summary' => $schema->string()->required(),
    ];
}

}

Invoke the agent from a controller or job:

$result = (new SupportAgent())
->maxSteps(10)
->prompt('What is the status of order #1234?')
->handle();

$text      = $result->text();        // raw text response
$structured = $result->structured(); // validated PHP object (HasStructuredOutput)

Always set maxSteps() in production. Without a step limit, an agent that calls tools in a loop and never converges will run until your API budget is exhausted. Laravel AI throws MaxStepsExceededException when the limit is hit — catch it and return a 422 to the client.

try {
$result = (new ResearchAgent())
->maxSteps(10)
->prompt($userQuery)
->handle();
} catch (\Laravel\AI\Exceptions\MaxStepsExceededException $e) {
Log::warning('Agent exceeded max steps', ['query' => $userQuery]);
return response()->json(['error' => 'Request too complex'], 422);
}

Conversation Memory and Database Persistence

Agent conversation memory is persisted automatically to two database tables: agent_conversations and agent_conversation_messages. Run the publishable migrations and the SDK handles the rest — no custom memory layer, no Redis sessions, no manual message history tracking:

php artisan vendor:publish --tag=ai-migrations
php artisan migrate

Every handle() call on a persistent agent reads prior messages from the database and includes them in the provider request. This enables genuine multi-turn chat without any extra code in your controller.

Structured Output: Getting Typed PHP Objects from AI

Structured output in the Laravel AI SDK uses JSON Schema validation to guarantee that the model returns data that conforms to a declared shape. Implement HasStructuredOutput on your agent class and define the schema in the schema() method. The SDK validates the response before returning it — if it doesn't conform, it re-prompts automatically.

One critical point: always validate structured output with Laravel's Validator before using it in business logic. The model can hallucinate fields or values that don't match your declared schema even when HasStructuredOutput is used. The SDK's JSON Schema validation catches structural mismatches, but it cannot catch semantically wrong values (e.g., a score of 999 when you expect 1–10).

Structured output costs extra tokens — the JSON Schema is included in every request, and occasional re-prompts add overhead. Only use it when you need machine-readable output. Raw AI::text() is cheaper for human-readable responses.

Need to integrate AI agents, RAG pipelines, or automation workflows into your existing web application? Our team builds custom integrations and automations for Mumbai businesses of all sizes.

RAG and Vector Embeddings

Retrieval-Augmented Generation (RAG) with the Laravel AI SDK uses three built-in primitives: Str::of()->toEmbeddings() to convert text to a float array, whereVectorSimilarTo() on Eloquent models to query a pgvector column, and the built-in SimilaritySearch tool that agents can call autonomously.

use Illuminate\Support\Str;

// Convert document text to an embedding vector
$vector = Str::of($documentText)->toEmbeddings(); // returns float[]
// Similarity search in PostgreSQL (requires pgvector extension)
$results = KnowledgeArticle::whereVectorSimilarTo('embedding', $queryVector)
->limit(5)
->get();

For a production RAG pipeline: embed your documents at index time and store vectors in a pgvector-enabled PostgreSQL column. At query time, embed the user's question and run whereVectorSimilarTo() to retrieve the top-5 relevant chunks. Pass those chunks as context to AI::text() or to an agent's system instructions.

pgvector vs External Vector Databases

pgvector (PostgreSQL extension) keeps your vector store inside your existing database, managed with standard Eloquent migrations. It's the right choice for document collections under a few million vectors. Beyond that scale, purpose-built vector databases such as Pinecone or Weaviate offer better ANN indexing performance — but they add operational complexity and a new infrastructure dependency. Start with pgvector and migrate only when query latency becomes a real problem.

MCP (Model Context Protocol) Integration

The Laravel AI SDK natively supports MCP — the open standard that lets agents connect to external tool servers over HTTP or STDIO transports. MCP lets your agents use tools maintained by third parties (GitHub, Jira, a company's internal API) without writing custom tool classes for each one.

Configure MCP servers in config/ai.php:

'mcp' => [
'servers' => [
'github' => [
'transport' => 'http',
'url'       => 'https://mcp.github.com',
'auth'      => ['type' => 'bearer', 'token' => env('GITHUB_TOKEN')],
],
],
],

Inside an agent class, expose the MCP server's tools with a single line:

public function tools(): array
{
return [
...AI::mcp('github')->tools(),
];
}

MCP tokens (bearer or OAuth) are API secrets — store them in .env and access them via env() inside config/ai.php. Validate that MCP server endpoints are internal or trusted before connecting your agent to them. An agent connected to a malicious MCP server can be tricked into exposing data or triggering unintended actions.

Multi-Agent Pipelines

Multi-agent workflows in the Laravel AI SDK use a Pipeline pattern where each step is a dedicated agent class that receives, enriches, and forwards a payload to the next step. The SDK supports three pipeline patterns: sequential (each agent runs in order), classifier-based (a classifier agent routes the payload to the correct specialist agent), and parallel (multiple agents run concurrently and results are merged).

use Laravel\AI\Pipeline;

// Sequential pipeline: classify → handle → summarise
$result = Pipeline::make()
->through([
ClassifierAgent::class,
SupportAgent::class,
SummaryAgent::class,
])
->send($payload)
->run();

Each agent in the pipeline should have a single, well-defined responsibility. A ClassifierAgent that categorises a support ticket should not also look up orders — that's the SupportAgent's job. Mixing responsibilities makes pipelines hard to test and harder to debug when a step produces unexpected output.

Image Generation, Audio Synthesis, and Transcription

Image generation supports OpenAI's DALL-E 3, Google Gemini image models, and xAI. The AI::image() fluent interface mirrors the text generation API:

$image = AI::image()
->using('dall-e-3')
->prompt('A futuristic Mumbai cityscape at night, digital art style')
->generate();

storage()->put('ai/city.png', $image->content());

Audio transcription uses Whisper (via OpenAI) and accepts local file paths:

$text = AI::audio()
->using('whisper-1')
->transcribe(storage_path('app/meeting.mp3'))
->text();

ElevenLabs is supported for text-to-speech synthesis via the same AI::audio() interface — switch the provider string and method from transcribe() to synthesise(). File attachments passed to AI providers (audio, images, documents) must be validated for MIME type and size before forwarding — never blindly pass user uploads to the AI provider.

Streaming Responses

Streaming AI responses via server-sent events significantly improves perceived performance for chat interfaces — users see tokens appear as they're generated rather than waiting for the full response. The Laravel AI SDK integrates with Laravel Reverb and Echo for broadcast streaming, and it's compatible with the Vercel AI SDK stream protocol for Next.js frontends.

However, streaming is not yet a first-class, zero-config SDK feature for token-by-token (character-by-character) output. The initial stable release treats streaming at the response level — you get a complete response delivered over SSE, not individual tokens as they arrive. For true token-level streaming, you need provider-specific SSE handling or custom code. This is expected to improve in a future minor release.

Testing AI Features Without Hitting Live APIs

The Laravel AI SDK ships with built-in test fakes for every major capability: text generation, agents, images, audio, transcriptions, and embeddings. Using fakes means your test suite never makes a real API call, never incurs costs, and never becomes flaky due to provider downtime.

use Laravel\AI\Fakes\TextFake;

// In your test setUp or test method:
AI::fake([
'text' => new TextFake('This is a mocked AI response'),
]);
$result = (new SupportAgent())->prompt('help')->handle();
$this->assertEquals('This is a mocked AI response', $result->text());

Every AI feature in your application should have a feature test that uses fakes. Writing tests that skip fakes and hit live APIs is one of the most common mistakes in Laravel AI projects — it results in slow, expensive, and flaky CI pipelines.

Queue Configuration for AI Jobs

AI jobs run 30–120 seconds — far longer than a typical Laravel queue job. Running AI work synchronously in the HTTP request cycle blocks a PHP-FPM worker for the full duration, degrades user experience, and breaks under any meaningful load. Queue all AI work as jobs and return a job ID to the client.

Configure dedicated queues and extended timeouts for AI workloads:

# In your supervisor config or Forge queue worker settings:
php artisan queue:work --queue=ai --timeout=180 --tries=3

Set rate limits on AI-facing routes to cap token spend per user:

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('ai-per-user', function (Request $request) {
return Limit::perMinute(10)->by($request->user()->id);
});
Route::middleware(['throttle:ai-per-user'])
->post('/ai/chat', [ChatController::class, 'handle']);

Architecture Decisions and Tradeoffs

The most important architectural decision in any Laravel AI project is whether to use AI::text() directly or to build a full Agent class. The right answer depends on the task's complexity:

On the provider side: OpenRouter as an aggregator is compelling for access to 100+ models through one key and automatic cost-based routing — but it adds a pricing markup (typically 5–10%) and an extra network hop versus direct provider calls. For production workloads where latency and cost are measured, go direct to the provider. Use OpenRouter for experimentation and model comparison.

laravel/ai vs prism-php: If you're adding AI to an existing Laravel 10 or 11 application that can't upgrade to Laravel 12 yet, Prism PHP is your only option — laravel/ai won't install. For new Laravel 12/13 projects, laravel/ai is the correct choice — it includes images, audio, embeddings, MCP, and RAG under one roof. Prism is faster to add to legacy apps; laravel/ai is the right foundation for greenfield projects.

Security Considerations

Prompt injection is the primary agent-level security risk in any Laravel AI deployment. Malicious user input can trick an agent into calling tools with unintended arguments — for example, instructing a database-querying tool to return another user's records. Mitigate this by:

1. Scoping all tool queries to the authenticated user via constructor injection. Pass $user into the tool's constructor, not via the prompt.
2. Using column allowlists and operator allowlists inside tool handle() methods. Never allow arbitrary SQL operators or column names from the model's output.
3. Using a read-only database connection for any tool that only reads data. This limits blast radius if an injection attack succeeds.
4. Never passing raw user input into system instructions or agent instructions without sanitisation. Treat the AI prompt boundary the same way you treat SQL parameters.

Additional security rules:

• Sanitise all AI text responses before rendering in HTML to prevent XSS from AI-generated content. Blade's {{ }} escaping handles this automatically — never use {!! !!} with raw AI output.
• Handle RateLimitedException (HTTP 429) and ProviderOverloadedException (HTTP 5xx) explicitly. These are distinct exception types — log both for alerting and implement exponential backoff or provider failover.
• Set hard monthly spend ceilings via your provider's billing dashboard in addition to maxSteps() limits. Rate limiting in code is a defence-in-depth measure, not a substitute for a hard spend cap.
• Keep Laravel Reverb updated — versions 1.6.3 and below are vulnerable to an unserialize() RCE. If you use Reverb for AI streaming, this is a critical patch requirement.
• Never expose AI provider API keys to the Next.js frontend. All AI calls must go through the Laravel backend. Any key prefixed with NEXT_PUBLIC_ is visible in the browser's JavaScript bundle.

Common Mistakes to Avoid

The following mistakes appear in almost every first Laravel AI project — knowing them in advance saves hours of debugging and avoids real production incidents:

1. Not setting maxSteps() — an uncapped agent will loop indefinitely and drain your API budget.
2. Running AI jobs synchronously in the HTTP cycle — they block for 30–120 seconds. Always queue AI work.
3. Using the same queue worker timeout for AI jobs as for normal jobs — the default Laravel timeout is far too low. Use a dedicated queue with --timeout=180.
4. Expecting token-level streaming as a built-in — it's not yet a first-class feature. Custom SSE code is needed.
5. Trusting structured output without validation — always run Validator on structured agent output before acting on it.
6. Installing laravel/ai on Laravel 11 or PHP 8.2 — composer will error out. Upgrade first.
7. Not writing tests with the built-in fakes — your CI pipeline will hit live APIs, incur costs, and break on provider outages.
8. Pinning composer to * instead of ^0.8 — a future minor release at v0.x can introduce breaking changes. Pin to a specific minor.

Frequently Asked Questions

Does the Laravel AI SDK work with Laravel 11?

No. The Laravel AI SDK requires Laravel 12 or Laravel 13 and PHP 8.3 or higher. Laravel 11 and below are not supported, and attempting to install laravel/ai on an older version will result in a composer dependency conflict. If you need AI features on Laravel 11, consider using the community Prism PHP package directly — it supports older Laravel versions. Migrating to Laravel 12 is recommended before adopting the official SDK.

How is the Laravel AI SDK different from Prism PHP?

The Laravel AI SDK (laravel/ai) actually uses Prism PHP under the hood — the Laravel team built their first-party package on top of the community library rather than starting from scratch. The key difference is scope: Prism focuses on LLM text generation and tool calling, while laravel/ai adds images, audio synthesis, audio transcription, vector embeddings, RAG, MCP, multi-agent pipelines, and Artisan scaffolding commands. For new Laravel 12/13 projects needing the full ecosystem, choose laravel/ai. For adding AI to older Laravel apps, choose Prism directly.

Can I use the Laravel AI SDK for RAG (Retrieval-Augmented Generation)?

Yes. The Laravel AI SDK includes built-in RAG primitives: Str::of($text)->toEmbeddings() generates a vector from text, whereVectorSimilarTo() retrieves similar documents from a pgvector-enabled PostgreSQL column, and the built-in SimilaritySearch tool lets agents perform retrieval autonomously. You need to install the pgvector PostgreSQL extension and run the SDK's publishable migrations. For document collections under a few million vectors, this built-in approach is sufficient — external vector databases like Pinecone or Weaviate are only necessary at larger scale.

Is the Laravel AI SDK production-ready?

The package was promoted to production-stable with Laravel 13 on 17 March 2026, with the Laravel team committing to API stability at that point. However, it is still at v0.x (current stable: v0.8.1 as of June 2026), which means breaking changes in minor version bumps are possible before v1.0.0. Pin your composer constraint to ^0.8 and track the GitHub releases page for changelog notes before upgrading. With proper pinning, rate limiting, spend caps, and the security measures in this guide, the SDK is ready for real production workloads.

How do I test Laravel AI SDK features without hitting live APIs?

Use the built-in test fakes that ship with the SDK. Call AI::fake() in your test setup and pass a fake implementation for each capability you use — TextFake, ImageFake, AudioFake, and so on. Faked calls return the response you define without making any HTTP request to the AI provider. This keeps your test suite fast, free of API costs, and isolated from provider downtime. Every Laravel AI feature should have a feature test that uses fakes — not a test that calls the live API.