Laravel AI SDK: The Definitive Guide to Building AI-Native PHP Applications
For the past several years, building artificial intelligence applications felt like a party strictly reserved for Python and TypeScript developers. If you wanted to build LLM agents, chain tools together, or stream structured responses, you usually had to wrestle with clumsy HTTP wrappers in PHP, maintain a rogue microservice in FastAPI, or deal with bloated abstractions.
That landscape changed completely with the release of the official Laravel AI SDK (laravel/ai).
By treating Large Language Models (LLMs), autonomous agents, multimodal media, and vector embeddings as first-class citizens alongside queues, notifications, and Eloquent, Laravel has delivered what is arguably the cleanest, most expressive AI framework in the web development world.
Whether you are looking to build multi-turn customer service agents, extract clean JSON from unstructured receipts, or implement semantic vector search across your database, this guide covers everything you need to take full advantage of laravel/ai.
At a Glance: What the Laravel AI SDK Delivers
- Unified Multi-Provider Engine: Write your prompt logic once and effortlessly toggle between OpenAI, Anthropic (Claude), Google Gemini, Mistral, Groq, and local Ollama instances without altering business code.
- First-Class Agent Classes: Scaffold dedicated agent classes (php artisan make:agent) that encapsulate system instructions, conversation memory, tools, and output schemas.
- Deterministic Structured Outputs: Enforce strict JSON Schema validation directly in PHP, eliminating JSON parse hallucinations and guaranteeing predictable database-ready arrays.
- Native Tool Calling (Function Calling): Empower models to inspect your database, call external APIs, and execute business logic through clean, reusable tool classes (php artisan make:tool).
- Multimodal Pipelines: Native generation and handling for text-to-speech (TTS), audio transcription (STT), computer vision, and image synthesis.
- Embeddings & Vector Search: Generate high-dimensional vector representations and connect directly to vector stores for retrieval-augmented generation (RAG).
- Zero-Cost Testing (
Ai::fake): Test your entire AI agent lifecycle, tool execution, and streaming endpoints locally without spending a cent on API tokens.
Architecture Matrix: How Laravel AI SDK Compares
| Feature / Dimension | Laravel AI SDK (laravel/ai) |
Direct API Clients (e.g. openai-php) |
Community Alternatives (e.g. Prism PHP) | Python / LangChain Ecosystem |
|---|---|---|---|---|
| Provider Agnostic | Yes (OpenAI, Anthropic, Gemini, Ollama) | No (Provider-specific) | Yes (Multi-provider) | Yes |
| Laravel Integration | Native (Artisan, Facades, Queues, Testing) | Service provider level | Service provider level | Separate service required |
| Class-Based Agents | Native (make:agent contract) |
Manual implementation | Fluent / procedural | Heavy class hierarchy |
| Tool Calling & Schema | Built-in JsonSchema contracts | Manual JSON schema array | Fluent builder | Pydantic / LangChain Tools |
| Testing & Mocking | Ai::fake(), Embeddings::fake() |
Manual HTTP client mocking | Prism::fake() |
Mocking libraries / VCR |
| Maintenance & Support | First-party Laravel Core Team | Community maintained | Community maintained | Open-source ecosystem |
1. Installation & Environment Setup
Getting started with the Laravel AI SDK follows familiar Laravel conventions.
Install the package via Composer:
$ composer require laravel/ai
Publish the package configuration file and database migrations:
$ php artisan vendor:publish --tag=ai-config $ php artisan migrate
The migrations set up conversation memory tables and agent execution audit logs, which allow your agents to persist dialogue history across requests.
Configuring Providers
Inside your .env file, define the API keys for the providers you plan to use:
AI_DEFAULT_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-proj-...
GEMINI_API_KEY=AIzaSy...
OLLAMA_BASE_URL=http://localhost:11434
In config/ai.php, you can inspect and tune default models, temperature, token limits, and fallback strategies.
2. Quick-Start: Interacting via the Ai Facade
For simple, one-off interactions—like summarizing a blog post or drafting an email response—you don't need a heavy agent class. You can interact directly with the Ai facade.
Basic Text Generation
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Laravel\Ai\Facades\Ai;
class SummaryController extends Controller
{
public function __invoke(Request $request)
{
$summary = Ai::prompt("Summarize the key takeaways of this changelog: {$request->input('notes')}")
->maxTokens(300)
->temperature(0.3)
->generate();
return response()->json(['summary' => $summary]);
}
}
Switching Providers Dynamically
One of the SDK’s greatest strengths is effortless provider switching. You can route low-cost background tasks to smaller models and complex reasoning tasks to top-tier models without changing anything else in your application:
// Run on Anthropic Claude 3.5 Sonnet
$thoughtfulResponse = Ai::using('anthropic')
->prompt('Analyze this multi-step contractual edge case...')
->generate();
// Run on local Ollama instance (completely free & offline)
$localDraft = Ai::using('ollama')
->prompt('Fix punctuation and grammar in this sentence...')
->generate();
3. Autonomous Agents: Building Stateful AI in PHP
While simple prompts are great for quick tasks, production applications usually demand state, distinct personalities, strict outputs, and tools. This is where Laravel AI's class-based agents shine.
Scaffold a new agent using Artisan:
$ php artisan make:agent CustomerSupportAgent --structured
This generates an agent class in app/Ai/Agents/ that implements the Agent, HasTools, and HasStructuredOutput contracts:
namespace App\Ai\Agents;
use App\Ai\Tools\CheckOrderStatus;
use App\Ai\Tools\IssueStoreCredit;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Stringable;
class CustomerSupportAgent implements Agent, HasTools, HasStructuredOutput
{
use Promptable;
/**
* Define the system instructions guiding the agent's behavior.
*/
public function instructions(): Stringable|string
{
return <<<PROMPT
You are a warm, efficient e-commerce customer support concierge for Hamdaoui Academy Store.
Help customers track orders and resolve satisfaction issues.
Always verify order details before issuing any store credits.
PROMPT;
}
/**
* Define the tools available to this agent.
*/
public function tools(): iterable
{
return [
new CheckOrderStatus(),
new IssueStoreCredit(),
];
}
/**
* Specify the strict JSON schema the agent must return.
*/
public function schema(JsonSchema $schema): array
{
return [
'reply_to_customer' => $schema->string()
->required()
->description('The polite message displayed to the customer.'),
'order_resolved' => $schema->boolean()
->required()
->description('Whether the customer request was completely fulfilled.'),
'action_taken' => $schema->string()
->enum(['none', 'tracked_shipment', 'credit_issued', 'escalated_to_human'])
->required(),
];
}
}
Calling the Agent in Your Application
Because the agent uses the Promptable trait, prompting it initiates an automated execution loop: the agent reasons, checks if any registered tools need to be called, runs the tools, inspects their output, and serializes the final response into your typed schema.
use App\Ai\Agents\CustomerSupportAgent;
$agent = new CustomerSupportAgent();
$result = $agent->prompt("Where is my order #HA-9421? My email is john@example.com.");
// Access structured schema attributes directly:
$customerMessage = $result['reply_to_customer'];
$isResolved = $result['order_resolved'];
$actionTaken = $result['action_taken'];
4. Supercharging Agents with Custom Tools
A tool is a bridge between the natural language reasoning of an LLM and the deterministic business logic of your Laravel codebase (database queries, external webhooks, mailers, or payment gateways).
Generate a tool using Artisan:
$ php artisan make:tool CheckOrderStatus
Here is a clean implementation of the tool:
namespace App\Ai\Tools;
use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Stringable;
class CheckOrderStatus implements Tool
{
/**
* The description tells the LLM when and why it should call this tool.
*/
public function description(): Stringable|string
{
return 'Look up shipping and tracking information for a specific customer order ID.';
}
/**
* The parameters expected by the handle method.
*/
public function schema(JsonSchema $schema): array
{
return [
'order_number' => $schema->string()
->required()
->description('The unique order reference code, e.g. HA-9421'),
];
}
/**
* The executable business logic triggered when the model calls this tool.
*/
public function handle(string $order_number): string
{
$order = Order::where('order_code', $order_number)->first();
if (! $order) {
return "Order {$order_number} was not found in the database.";
}
return json_encode([
'order_code' => $order->order_code,
'status' => $order->status, // e.g., 'Shipped', 'Out for delivery'
'carrier' => $order->shipping_carrier,
'tracking' => $order->tracking_number,
'est_arrival'=> $order->estimated_delivery?->toFormattedDateString(),
]);
}
}
When the customer asks "Where is my order #HA-9421?", the model detects the match, generates the arguments, allows Laravel to safely invoke handle(), and uses the returned JSON string to construct its response.
5. Embeddings & Semantic Search (RAG)
If you are building knowledge bases, documentation search, or recommendation engines, keywords alone are often insufficient. The Laravel AI SDK includes the Embeddings facade to vectorize text into semantic numerical representations.
Generating Vector Embeddings
use Laravel\Ai\Facades\Embeddings;
$vectors = Embeddings::for("How do I configure Redis queues in Laravel?")
->dimensions(1536)
->generate();
Storing & Querying via PostgreSQL pgvector
Combined with Laravel's modern database capabilities or packages like pgvector-php, searching your knowledge base becomes as simple as an Eloquent query:
$userQuery = "payment problems with credit card";
$queryVector = Embeddings::for($userQuery)->generate();
$relevantArticles = Article::query()
->select(['id', 'title', 'content'])
->orderByRaw('embedding <=> ?::vector', [json_encode($queryVector)])
->limit(4)
->get();
6. Real-Time Streaming with Server-Sent Events (SSE)
Waiting 8–15 seconds for a large model to finish generating a paragraph creates poor user experience. The SDK makes real-time response streaming feel as natural as any standard HTTP response.
In your controller:
namespace App\Http\Controllers;
use App\Ai\Agents\SalesCoach;
use Illuminate\Http\Request;
class AiStreamController extends Controller
{
public function stream(Request $request)
{
$agent = new SalesCoach();
return response()->stream(function () use ($agent, $request) {
$agent->stream($request->input('message'), function (string $chunk) {
echo "data: " . json_encode(['chunk' => $chunk]) . "\n\n";
ob_flush();
flush();
});
}, 200, [
'Content-Type' => 'text/event-stream',
'Cache-Control' => 'no-cache',
'Connection' => 'keep-alive',
]);
}
}
7. Zero-Cost Testing: Never Hit Live APIs in CI
Running tests against live AI APIs is slow, expensive, and non-deterministic. The Laravel AI SDK provides world-class testing utilities directly out of the box.
Testing Agents and Assertions
namespace Tests\Feature;
use App\Ai\Agents\CustomerSupportAgent;
use Laravel\Ai\Testing\FakeResponse;
use Tests\TestCase;
class SupportAgentTest extends TestCase
{
public function test_support_agent_resolves_inquiry_with_schema(): void
{
// Fake the agent response
CustomerSupportAgent::fake([
new FakeResponse([
'reply_to_customer' => 'Your package HA-9421 is on its way and will arrive tomorrow.',
'order_resolved' => true,
'action_taken' => 'tracked_shipment',
]),
]);
$response = (new CustomerSupportAgent())
->prompt('Where is order #HA-9421?');
$this->assertTrue($response['order_resolved']);
$this->assertEquals('tracked_shipment', $response['action_taken']);
// Assert that the agent was called
CustomerSupportAgent::assertPrompted(function ($prompt) {
return str_contains($prompt, 'HA-9421');
});
}
}
Preventing Stray Live Requests
Add Ai::preventStrayPrompts() in your base TestCase::setUp() method to guarantee your continuous integration (CI) pipeline fails instantly if any developer accidentally triggers an unmocked live API call:
protected function setUp(): void
{
parent::setUp();
Ai::preventStrayPrompts();
}
8. Where It Fits: The Laravel First-Party AI Trio
The Laravel AI SDK does not exist in isolation. The Laravel ecosystem has introduced three complementary packages targeting different aspects of modern software:
laravel/ai(Laravel AI SDK): Runs inside your web application. Used for user-facing features, customer chatbots, dynamic data structuring, and background AI workflows.laravel/boost: A developer dependency (composer require laravel/boost --dev). Bridges external AI coding tools (Cursor, Windsurf, Claude Code) with your Laravel project, providing live schema context, routes, and framework documentation.laravel/mcp: Turns your Laravel application into a Model Context Protocol (MCP) server, securely exposing your internal tools and APIs to external AI clients and workstations.
Frequently Asked Questions
Is the Laravel AI SDK free?
The package itself (laravel/ai) is completely open-source and free under the MIT license. However, you will pay for API usage directly to whichever model providers you use (such as OpenAI or Anthropic). If you want zero operational cost, you can pair it with Ollama to run models locally on your server.
How does laravel/ai differ from Prism PHP?
Prism PHP is an exceptional community package created by Echo Labs that pioneered multi-provider AI in PHP. The Laravel AI SDK builds on many similar principles but provides deeper integration with Laravel's core architecture—specifically native Artisan generators (make:agent, make:tool), native integration with Laravel's JsonSchema contract, and standardized conversation persistence tables.
Can I run local open-source models with it?
Yes. By setting AI_DEFAULT_PROVIDER=ollama in your .env and running models like Llama 3, Mistral, or DeepSeek through Ollama, you can process prompts entirely on-premise without sending customer data to external third parties.
Final Verdict: Is It Ready for Production?
For years, Laravel developers had to invent their own AI abstractions or resort to maintaining hybrid Python microservices just to handle basic agent loops and tool calling.
With the Laravel AI SDK, that friction is gone. Its combination of typed agent classes, built-in schema guarantees, first-class testing harness, and vendor neutrality makes building intelligent, production-ready applications in PHP faster and cleaner than ever before.
If you are running Laravel 11 or later and looking to bring modern artificial intelligence into your project, laravel/ai is the gold standard foundation to build upon.