The Laravel AI SDK is Laravel's first-party package for building AI-powered application features without turning your codebase into a collection of provider-specific HTTP calls.
It gives Laravel developers one consistent place to configure providers, define agents, call models, use tools, request structured output, and track usage.
The important mental shift is this: the SDK is not the product feature by itself. It is the integration layer.
Your Laravel application still owns the use case, authorization, validation, persistence, queues, logs, and user experience. The SDK gives you a Laravel-native way to connect those responsibilities to AI providers.
Start with one narrow feature: Do not begin by building a general assistant. Begin with a small task such as support-ticket summarization, product description improvement, review classification, or internal document Q&A. A narrow feature makes the prompt, output, fallback, cost, and success criteria much easier to control.
Before the SDK, many Laravel applications integrated AI with raw HTTP clients, direct provider SDKs, or small wrapper services.
That works for a prototype, but it becomes messy once the product needs multiple providers, conversation context, structured output, tools, streaming, cost tracking, testing, and failover.
The SDK gives you several production-friendly building blocks:
A new Laravel AI SDK setup starts like a normal Laravel package:
composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate
The migration step matters because SDK features such as remembered conversations need database tables.
If your first feature is a stateless classification or summarization endpoint, you may not use conversation storage immediately, but publishing configuration early keeps provider and model choices visible.
Provider credentials should stay in environment variables and configuration, not inside prompts, controllers, jobs, or agent classes.
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GEMINI_API_KEY=
GROQ_API_KEY=
MISTRAL_API_KEY=
OPENROUTER_API_KEY=
OPENAI_COMPATIBLE_API_KEY=
OPENAI_COMPATIBLE_URL=
A useful first production habit is to define a default provider and model per environment.
Local development may use a cheap or local model. Staging may use a stable low-cost model. Production may pin a specific model for predictable behavior and pricing.
Do not hide model choice: The selected provider and model affect quality, latency, cost, context window, supported tools, and output behavior. Treat model selection like infrastructure configuration, not like a random string inside a controller.
The SDK's main application-facing concept is the agent.
An agent is a PHP class with a responsibility. For a first feature, imagine a SupportSummaryAgent that turns a long support message into a short internal summary.
php artisan make:agent SupportSummaryAgent
php
<?php
namespace App\Ai\Agents;
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;
#[MaxTokens(600)]
#[Temperature(0.2)]
class SupportSummaryAgent implements Agent
{
use Promptable;
public function instructions(): string
{
return <<<'PROMPT'
You summarize customer support messages for an internal Laravel support team.
Write concise summaries.
Keep facts from the original message.
Do not invent account status, payment state, or technical causes.
If the message is unclear, say what is missing.
PROMPT;
}
}
Notice that the instructions describe the job and the boundary.
The agent may summarize and identify missing information, but it must not invent account state or technical root cause. That kind of language is not decoration; it is part of the application contract.
A controller should not become the place where prompts, provider decisions, validation, persistence, and response formatting all mix together.
Keep the HTTP layer thin and call a service or action that owns the use case.
<?php
namespace App\Services;
use App\Ai\Agents\SupportSummaryAgent;
use App\Models\SupportTicket;
class SummarizeTicket
{
public function handle(SupportTicket $ticket): string
{
$prompt = <<<TEXT
Summarize this support ticket for an internal support agent.
Subject: {$ticket->subject}
Message:
{$ticket->message}
TEXT;
$response = (new SupportSummaryAgent)->prompt($prompt);
return trim((string) $response->content);
}
}
The first Laravel AI SDK request lifecycle usually looks like this:
The prompt should contain only the data required for the task.
If the summary does not need billing history, do not send billing history. If the user cannot access a record, the model should not receive that record either.
The SDK also supports anonymous agents through the agent() helper.
This is useful for experiments, prototypes, and one-off internal scripts. For product features, a named class is usually easier to review, test, version, and observe.
use function Laravel\Ai\agent;
$response = agent(
instructions: 'You explain Laravel concepts to PHP developers.',
)->prompt('Explain service containers in three bullet points.');
Prototype fast, promote carefully: Anonymous agents are good for learning the SDK. Once a workflow affects users, money, records, support decisions, or private data, move the behavior into a named agent and a domain service.
AI features create a new operational dimension: token usage.
A feature can be correct and still be too expensive. The SDK response exposes usage information reported by the provider, including input tokens, output tokens, and totals.
$response = (new SupportSummaryAgent)->prompt($prompt);
logger()->info('support_ticket_summary.generated', [
'ticket_id' => $ticket->id,
'input_tokens' => $response->usage?->inputTokens,
'output_tokens' => $response->usage?->outputTokens,
'total_tokens' => $response->usage?->totalTokens(),
]);
return trim((string) $response->content);
At minimum, log provider, model, prompt version, feature name, response time, token usage, validation result, and failure reason.
Later, these logs answer practical questions: which customer costs the most, which prompt version became slower, which provider fails most often, and whether a cheaper model is good enough.
A good first Laravel AI SDK feature has a boring boundary.
It accepts trusted application data, sends minimal context, asks for a limited result, validates or reviews that result, and stores enough metadata to debug it later.
For example, a ticket summary can safely fail by showing "summary unavailable" and letting the support agent read the original ticket.
A payment decision cannot safely fail open. The first feature should teach the team how AI behaves without putting core business state at risk.
Once the first feature works, the next step is not automatically "more AI."
The next step is better engineering around the same narrow use case: structured output, tests, retries, provider failover, prompt versioning, queueing, and user feedback.
A sensible learning path:
This episode gives you the first working shape: install the SDK, configure providers, create an agent, call it from Laravel code, and observe the result.
In the next episode, we will go deeper into agents themselves: what belongs inside an agent, what belongs in Laravel services, how tools enter the loop, and how to keep agent behavior understandable as the feature grows.
If you found this useful, follow me for the next article in the AI Engineering with Laravel series.