Back to Blog
Laravel AI SDK 1.0: What Actually Changed for App Code
Laravel's first-party AI package hit 1.0 on 23 Sep 2026. Classification, tool approvals, chat protocols, and a conversation storage format that needs a real upgrade plan.
Back
Engineering
Table of contents
Laravel AI SDK 1.0: What Actually Changed for App Code
Laravel AI SDK (laravel/ai) hit 1.0.0 on 23 Sep 2026. The package was beta since February, and the team has said this is production-ready. I read the docs, the UPGRADE guide, and the Packagist requirements before I would ship it.
This is not Laravel MCP 1.0 (that is laravel/mcp) and not Laravel Boost (the agent tooling product shipped earlier). This post is about laravel/ai, the first-party package for building AI features inside your own Laravel application.
As of 20 Nov 2026 the current release is 1.4.x (Packagist shows v1.4.1). For what shipped after 1.0, see Laravel AI SDK 1.1 Agent Skills.
If you are starting fresh: composer require laravel/ai and follow the docs. If you are already on 0.11.x from beta: schedule the upgrade. The conversation schema changed, and this is not a blind composer update.
Quick Answer
If I had zero AI code on Laravel today: I would try Classification for ticket routing or moderation decisions, and I would keep tool approvals in mind if I build anything destructive.
If I were already on 0.11.x: I would block a week to run the migrations (including a conversation backfill script that replaces tool_calls/tool_results columns with a new steps column), test the middleware signature changes, and resolve any pending human-in-the-loop approvals before the deploy. The Laravel Boost /upgrade-ai-sdk-v1 slash command is designed to walk this process. The UPGRADE guide is on GitHub, and it is not light reading.
What Classification is for
Classification is now a first-class capability alongside text, image, audio, and embeddings. The use case is structured decisions: route a ticket, score sentiment, decide if something is spam.
Classification is experimental in the docs, and its API may change in future minors. It runs on Jev models from TypeSafe (the provider default is jev-latest in the package source), or via OpenRouter per the provider table.
php
use Laravel\Ai\Classification;
use Laravel\Ai\Classification\{Boolean, Choice, Score};
$result = Classification::of($message)
->questions([
'spam' => new Boolean('Is this spam?'),
'sentiment' => new Choice('Sentiment?', [
'positive' => 'Clearly positive tone',
'negative' => 'Clearly negative tone',
'neutral' => 'No strong tone',
]),
'urgency' => new Score('How urgent is it?', ['Low', 'Medium', 'High']),
])
->classify();For a single yes/no, there is a string helper:
php
use Illuminate\Support\Str;
$isSpam = Str::of($message)->decide('Is this spam?');I care about this because the alternative is prompt-engineering json_mode or regex-parsing yes/no strings, both of which I have done and neither of which I enjoyed. Classification gives you typed outputs and a cleaner signature. If you are already doing this with raw completions, this is worth migrating.
Tool approvals: human-in-the-loop for destructive actions
1.0 ships approvable tool calls. The pattern is: tools implement Approvable, the agent pauses when it wants to call one, and you show the user an approval UI. The user can approve, reject, or edit the arguments. The agent resumes after the decision.
The docs call this "human-in-the-loop," which is the correct framing. If your agent can delete records, charge cards, or send emails, you want a gate. The alternative is hoping the LLM never hallucinates a destructive call, which is not a plan.
When the UI resumes the agent, pass a Decisions map keyed by tool call id. Each value is a Decision from Decision::approve(), Decision::reject('reason'), or Decision::edit([...]):
php
use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;
$response = (new FileAssistant)
->continue($conversationId, as: $user)
->prompt(Decisions::from([
'call_id' => Decision::approve(),
]));The message status column on agent_conversation_messages (replacing approval_state from beta) tracks whether the turn is waiting, paused, or failed.
I would use this for any tool that costs money or breaks user data. I would not use it for read-only search or retrieval. The latency of waiting for a human decision is real, so treat this as a safety rail, not a default behavior.
Chat protocols: Vercel Chat and AG-UI
If you want to plug a React or Vue chat UI into a Laravel agent, 1.0 ships Vercel Chat and AG-UI streaming protocols. The signature looks like this:
php
use Laravel\Ai\Vercel\Vercel;
Route::post('/chat', function (Request $request) {
$chat = Vercel::chat($request);
return (new SupportAgent)
->withMessages($chat->history())
->stream($chat)
->usingProtocol($chat->protocol());
});AG-UI uses usingAgentUserInteractionProtocol() or AgentUserInteraction::chat.
The reason these matter: frontend chat libraries expect a specific JSON stream format. Before this, you would write the protocol adapter yourself or ignore the streaming question entirely. Now it is built in.
If you are shipping a customer-facing chat interface, this is the boring plumbing that saves you a day. If you are only building internal agent scripts or API-to-API flows, you will not touch it.
Per-step agent middleware
Agent middleware in 1.0 wraps each generation step (a PendingStep), not once per prompt. This is a breaking change from 0.11.x. If you wrote custom middleware, the signature changed.
Old middleware received the full agent context once. New middleware receives each step as it happens, so you can log, rate-limit, or transform per-generation instead of per-conversation. This is more granular, which is better for observability. It is also a signature change that will break your build if you do not update.
The UPGRADE guide calls this out explicitly. Fix it before you ship.
Conversation storage: the steps column
Conversation tables in 1.0 replace tool_calls and tool_results with a single steps JSON column on agent_conversation_messages. The message approval_state column is replaced by status (a MessageStatus enum).
If you already ran Laravel AI beta migrations, you need a backfill migration before you deploy 1.0. The package does not auto-migrate conversation data. You write the script, test it on staging, and run it before the 1.0 code hits production.
If you have pending tool approvals in flight (conversations stuck waiting for a human decision), resolve or abandon them before the migration. Otherwise you will need to map old states to the new schema by hand.
This is the highest-impact item in the upgrade guide. It is not optional, and it is not automatic.
Usage token rename
promptTokens and completionTokens are now inputTokens and outputTokens. This is a naming alignment with provider APIs (OpenAI, Anthropic, etc.). The new names include cache and reasoning token categories.
If you log or bill on token usage, update your queries and dashboards. The data is the same, the column names changed.
Other breaking changes
The UPGRADE guide lists many more items. A few that matter:
- AWS Bedrock users: the AWS SDK is no longer bundled. You need
composer require aws/aws-sdk-phpseparately. - ToolSearch: deferred tools for OpenAI and Anthropic are now built in. If you wrote a custom workaround, you can remove it.
- CodeExecution: the provider tool is now supported for Anthropic, OpenAI, Azure, Gemini, and xAI. If you need sandboxed code execution, this is the escape hatch.
The package still requires PHP ^8.3 and Laravel 12 or 13 (per Packagist). If you are on PHP 8.2, you are blocked.
My take
Laravel AI SDK 1.0 is a real release with real upgrade costs. Classification and tool approvals are useful. The chat protocol adapters save frontend plumbing. The conversation schema change is not trivial.
If you are starting fresh, install and learn. The docs are clear, and the APIs are stable enough to ship.
If you are on 0.11.x, plan the upgrade like a schema migration, not a composer update. Read the UPGRADE guide, run the conversation backfill on staging, resolve pending approvals, and test the middleware changes before you tell anyone "done." Laravel Boost's /upgrade-ai-sdk-v1 command is designed for this. Use it.
If you are not using AI features yet, wait until you have a real use case. The package is production-ready, but that does not mean you need it today.
Sources
- Laravel AI SDK docs: laravel.com/docs/13.x/ai-sdk
- Package on Packagist: packagist.org/packages/laravel/ai
- GitHub repo: github.com/laravel/ai
- UPGRADE guide: github.com/laravel/ai/blob/1.x/UPGRADE.md
- Laravel News coverage: laravel-news.com/laravel-ai-sdk-1-0 (23 Sep 2026)
- Positioning guide (AI SDK vs Boost vs MCP): laravel.com/blog/laravel-ai-sdk-boost-or-mcp-which-tool-do-you-need
Checked on 20 Nov 2026.
Comments
No comments yet
Loading comments...