Laravel's first-party AI SDK (laravel/ai) arrived alongside Laravel 13 in 2026, changing how PHP teams build AI features. Instead of running a separate Python service or relying on a third-party wrapper, you can build agents, tools, embeddings, and AI tests using the Laravel patterns you already know.

This guide walks through setup, agents, conversation memory, tools, structured output, vector search, multimodal features, multi-agent workflows, and testing, along with everything the SDK gained at Laracon US 2026.

What's New Since Laracon US 2026

At Laracon US in Boston, July 28–29, the Laravel team announced five additions to the AI SDK:

  • Human-in-the-loop tool approval. Agents previously ran on autopilot once they started calling tools. Now, an agent can pause before a sensitive tool runs, allowing a person to approve, deny, or change the call.

  • Filesystem tools. Agents can read, write, and manage files without requiring you to build that integration yourself.

  • A summarize() helper on Laravel's Str class, with no setup required.

  • Multimodal embeddings. Generate embeddings for images and audio, not just text.

  • OpenAI-compatible providers. Point your agents at any service that uses the OpenAI API format, not just OpenAI.

When to Use Human-in-the-Loop Approval

Use it for any tool where a mistake could cost money or trust, such as charging a customer, emailing users, deleting records, or changing permissions. Low-risk tools, such as searching your documentation, can run without approval.

Why the Laravel AI SDK Matters

The SDK is built around provider independence. You write your AI logic once against a single interface and choose the provider (OpenAI, Anthropic, Gemini, and others) in your configuration. Switching providers doesn't mean rewriting your code. In code, reference providers with the Laravel\Ai\Enums\Lab enum (for example, Lab::Anthropic) rather than plain strings.

It also covers far more than chat: agents, tools, structured output, embeddings, reranking, images, audio, and testing, all within the same Laravel\Ai namespace.

Installation and Configuration

Install the package with Composer and publish its files:

composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

Add your provider API keys to .env and choose your defaults in the published config file. If the publish step added migrations, run:

php artisan migrate

Core Concept 1: Agents

An agent is a PHP class that holds everything for one AI task: its instructions, conversation context, tools, and output schema. Think of it as a controller for your AI logic.

Generate one with Artisan:

php artisan make:agent SupportAssistant

An agent implements the Agent contract and uses the Promptable trait:

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class SupportAssistant implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are an expert customer support analyst. Analyze the provided text and extract the key frustrations.';
    }
}

Calling it is one line:

use App\Ai\Agents\SupportAssistant;

$transcript = "I've been trying to reset my password for three days and the email never arrives!";

$response = SupportAssistant::make()->prompt($transcript);

return (string) $response;

Conversation Memory

Models are stateless, so a chatbot needs its conversation history. Implement Conversational and add the RemembersConversations trait, and the SDK stores the conversation for you:

namespace App\Ai\Agents;

use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Promptable;

class SupportAssistant implements Agent, Conversational
{
    use Promptable, RemembersConversations;

    public function instructions(): string
    {
        return 'You are a friendly support assistant for our app.';
    }
}

Core Concept 2: Tools and Structured Output

Real applications need AI to work with your system and return predictable data.

Tools

Tools are PHP classes the model can call while it works. Generate one:

php artisan make:tool CheckOrderStatus

A tool describes itself, declares its inputs with a schema, and handles the call. Pass in the current user and scope every query to them, so the AI can never read another customer's data:

namespace App\Ai\Tools;

use App\Models\User;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;

class CheckOrderStatus implements Tool
{
    public function __construct(private User $user) {}

    public function description(): string
    {
        return 'Check the shipping status of one of the current customer\'s orders.';
    }

    public function handle(Request $request): string
    {
        $order = $this->user->orders()->find($request['order_id']);

        return $order
            ? "Order {$order->id} is {$order->status}."
            : 'No order with that ID was found for this customer.';
    }

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

Give the agent its tools by implementing HasTools:

use App\Ai\Tools\CheckOrderStatus;
use App\Models\User;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class SupportAssistant implements Agent, HasTools
{
    use Promptable;

    public function __construct(private User $user) {}

    public function instructions(): string
    {
        return 'Help customers with questions about their orders.';
    }

    public function tools(): iterable
    {
        return [
            new CheckOrderStatus($this->user),
        ];
    }
}

make() passes named arguments to the constructor:

$response = SupportAssistant::make(user: $request->user())
    ->prompt('Where is my order 1042?');

The SDK handles the back-and-forth: the model asks for the tool, Laravel runs it, and the result is automatically sent back to the model.

Structured Output

Stop digging JSON out of text. Implement HasStructuredOutput and describe the shape you want:

php artisan make:agent SentimentAnalyzer --structured

namespace App\Ai\Agents;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Promptable;

class SentimentAnalyzer implements Agent, HasStructuredOutput
{
    use Promptable;

    public function instructions(): string
    {
        return 'Classify the sentiment of the customer message.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'sentiment' => $schema->string()->enum(['positive', 'negative', 'neutral'])->required(),
            'confidence' => $schema->number()->min(0)->max(1)->required(),
            'requires_human' => $schema->boolean()->required(),
        ];
    }
}

Read the result like an array:

$result = SentimentAnalyzer::make()->prompt($message);

if ($result['requires_human']) {
    // route the ticket to a person
}

Core Concept 3: Embeddings, Vector Search, and Reranking

The SDK covers the entire retrieval-augmented generation (RAG) flow, so you don't need a separate vector database service:

  • Embeddings (Laravel\Ai\Embeddings) turn text into vectors you can store, for example, in a PostgreSQL column using the pgvector extension.

  • Similarity search finds records that are closest in meaning to a question. The built-in Laravel\Ai\Tools\SimilaritySearch tool lets an agent run that search on its own.

  • Reranking (Laravel\Ai\Reranking) reorders a broad set of results, such as full-text matches, based on how well each one actually answers the query.

  • Stores (Laravel\Ai\Stores) manage collections of documents that the AI can search.

Since Laracon US 2026, embeddings also work for images and audio, so you can search media by meaning instead of by file names or tags. See the Laravel documentation for the exact query methods.

Core Concept 4: Images, Audio, and Documents

The SDK goes well beyond text:

  • Laravel\Ai\Image generates images from a prompt, which you can save to any Laravel disk.

  • Laravel\Ai\Audio turns text into speech.

  • Laravel\Ai\Transcription turns recordings into text for meeting notes or accessibility features.

  • Laravel\Ai\Files\Document attaches files, such as a PDF or transcript, to a prompt.

Core Concept 5: Multi-Agent Workflows and Streaming

Parallel Agents

Run several specialized agents at once with Laravel's Concurrency facade. Return plain strings because results are passed between processes:

use Illuminate\Support\Facades\Concurrency;

[$sentiment, $summary, $entities] = Concurrency::run([
    fn () => (string) SentimentAgent::make()->prompt($text),
    fn () => (string) SummaryAgent::make()->prompt($text),
    fn () => (string) EntityAgent::make()->prompt($text),
]);

Streaming

For long answers, stream the response so users see it appear instead of watching a spinner:

Route::post('/assistant', function (Request $request) {
    return SupportAssistant::make(user: $request->user())
        ->stream($request->input('message'));
});

Agent Middleware

To log every prompt, track token usage, or add checks around each call, generate agent middleware:

php artisan make:agent-middleware LogPrompts

Core Concept 6: Testing with Fakes

Testing AI used to mean mocking HTTP clients and paying for API calls. The SDK has built-in fakes, so your tests never call a real provider:

use App\Ai\Agents\SupportAssistant;

it('analyzes a support ticket', function () {
    SupportAssistant::fake(['The customer is frustrated by missing reset emails.']);

    $this->post('/api/analyze-ticket', ['transcript' => 'My server is down.'])
        ->assertOk();

    SupportAssistant::assertPrompted('My server is down.');
});

Use SupportAssistant::fake()->preventStrayPrompts() to fail the test if anything sends a prompt you didn't expect. The same pattern works for other features: Image::fake(), Audio::fake(), Embeddings::fake(), Reranking::fake(), Files::fake(), and Stores::fake().

Laravel AI SDK vs Laravel Boost: What's the Difference?

They solve different problems, and many teams use both:

  • The Laravel AI SDK is for building AI features into your app: chatbots, agents, summaries, and search.

  • Laravel Boost is for AI coding agents working on your codebase. It gives tools like Claude Code or Cursor the context of your app, so the code they write fits your project.

FAQ

Is the Laravel AI SDK free?

Yes. The package is free and open source. You pay the AI providers you call.

Which AI providers does it support?

Major providers like OpenAI, Anthropic, and Gemini. Since Laracon US 2026, it also works with any OpenAI-compatible provider.

How do I stop an agent from doing something risky?

Scope every tool to the current user, and require human-in-the-loop approval for tools that spend money, email customers, or delete data.

How do I test AI features without paying for API calls?

Fake the agent with YourAgent::fake([...]), then check it with YourAgent::assertPrompted(...). No real API calls are made.

Conclusion: Laravel Is Now AI-Native

The Laravel AI SDK is a big step forward. It standardizes how you talk to AI providers, brings vector search into your Laravel app, and gives you real testing tools. Since Laracon US 2026, it also lets you keep a human in control of risky actions.

You no longer need a separate tech stack to build intelligent features. Agents, tools, RAG pipelines, and multi-agent workflows now live in the same PHP codebase as the rest of your app.

For more, see our overview of Laravel 13 and our list of Laravel AI agent packages.

[Keep your existing "Ready to Code Smarter with Laravel?" CTA block here]

Ready to Speed Up Your Laravel AI Development?

Stop wrestling with boilerplate and start shipping intelligent features faster. Try StackMivo free and build Laravel apps with AI from a plain-English description.