Getting Started with the Laravel AI SDK

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.

What the Laravel AI SDK Gives You

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.

Install the Package and Publish Configuration

A new Laravel AI SDK setup starts like a normal Laravel package: require the package, publish its configuration and migrations, then run migrations if you plan to use conversation storage.

1composer require laravel/ai2 3php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"4 5php 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.

Configure Providers Through Environment Variables

Provider credentials should stay in environment variables and configuration, not inside prompts, controllers, jobs, or agent classes. This keeps deployment, rotation, and provider switching manageable.

1OPENAI_API_KEY=2ANTHROPIC_API_KEY=3GEMINI_API_KEY=4GROQ_API_KEY=5MISTRAL_API_KEY=6OPENROUTER_API_KEY=7OPENAI_COMPATIBLE_API_KEY=8OPENAI_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.

Create a First Agent

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.

1php artisan make:agent SupportSummaryAgent

1<?php2 3namespace App\Ai\Agents;4 5use Laravel\Ai\Attributes\MaxTokens;6use Laravel\Ai\Attributes\Temperature;7use Laravel\Ai\Contracts\Agent;8use Laravel\Ai\Promptable;9 10#[MaxTokens(600)]11#[Temperature(0.2)]12class SupportSummaryAgent implements Agent13{14    use Promptable;15 16    public function instructions(): string17    {18        return <<<'PROMPT'19You summarize customer support messages for an internal Laravel support team.20 21Write concise summaries.22Keep facts from the original message.23Do not invent account status, payment state, or technical causes.24If the message is unclear, say what is missing.25PROMPT;26    }27}

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.

Call the Agent from Application Code

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.

1<?php2 3namespace App\Services;4 5use App\Ai\Agents\SupportSummaryAgent;6use App\Models\SupportTicket;7 8class SummarizeTicket9{10    public function handle(SupportTicket $ticket): string11    {12        $prompt = <<<TEXT13Summarize this support ticket for an internal support agent.14 15Subject: {$ticket->subject}16Message:17{$ticket->message}18TEXT;19 20        $response = (new SupportSummaryAgent)->prompt($prompt);21 22        return trim((string) $response->content);23    }24}

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.

Use Anonymous Agents for Experiments Only

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.

1use function Laravel\Ai\agent;2 3$response = agent(4    instructions: 'You explain Laravel concepts to PHP developers.',5)->prompt('Explain service containers in three bullet points.');

Track Usage from the First Day

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.

1$response = (new SupportSummaryAgent)->prompt($prompt);2 3logger()->info('support_ticket_summary.generated', [4    'ticket_id' => $ticket->id,5    'input_tokens' => $response->usage?->inputTokens,6    'output_tokens' => $response->usage?->outputTokens,7    'total_tokens' => $response->usage?->totalTokens(),8]);9 10return 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.

Design the First Feature Boundary

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.

• Authorization happens before the model call, not after.
• The prompt uses application data, not raw untrusted request payloads when avoidable.
• The output is treated as a draft, classification, suggestion, or structured result—not as a final business decision.
• The feature has a fallback when the provider times out or returns invalid output.
• The model and prompt version are visible in logs.
• Sensitive data is minimized before it enters the prompt.

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.

Where to Go After the First Agent

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.

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.