Stream a Laravel AI SDK Agent into a Vue Chat UI with useChat
Gentil Maliyamungu B. · 2026-11-15
Build a Laravel AI SDK support agent with an order-lookup tool and stream its replies into a Vue 3 chat using useChat from @ai-sdk/vue.
A chat that waits for the full answer before showing anything feels broken. Users stare at a spinner for five or ten seconds, then a wall of text appears at once. Streaming fixes that: the reply shows up word by word, and if the model calls a tool you can show that too.
The Laravel AI SDK (laravel/ai) already knows how to stream. Its docs show a Vercel::chat() helper that speaks the same protocol as the Vercel AI SDK's useChat. Most examples you will find online use the React version of useChat, Livewire, or a hand-written EventSource client. This tutorial does the Vue version from start to finish:
- a Laravel agent that answers customer questions for a small shop,
- a tool the agent calls to look up an order in the database,
- a Vue 3 component that streams the reply and shows the tool call as it happens.
Everything below was built and run against laravel/ai 1.4.0 on Laravel 13.42 and PHP 8.4, with ai 7.0.173, @ai-sdk/vue 4.0.173 and Vue 3.5. The JavaScript side of these libraries changes quickly, so check your installed versions if something does not match.
What we are building
The demo is a support chat for a fictional shop. Three orders are seeded: 1001 (shipped), 1002 (delayed) and 1003 (refunded). When the user asks "Where is order 1001?", the agent calls a LookupOrder tool, reads the result, and streams back a short answer.
There are three pieces:
SupportAgent, a PHP class with instructions and one tool.
POST /chat, a route that turns the useChat request into an agent call and streams the response.
SupportChat.vue, a component that uses useChat to send messages and render the streamed parts.
Out of scope for this post: tools that need a human to approve them (that is the next article), saving conversations in the database, and RAG.
Install the Laravel AI SDK
Start from a fresh Laravel app and follow the installation section of the docs:
composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate
The publish step creates config/ai.php and the migrations for the SDK's conversation tables. We do not use those tables in this article, but running the migration now saves you a surprise later.
Add a provider key to .env, for example OPENAI_API_KEY=... or OPENROUTER_API_KEY=.... The default provider is set in config/ai.php.
Running it without an API key
While writing this I wanted the demo to run on a machine with no key at all, so I made the default provider configurable and pointed it at a small scripted server that speaks the OpenAI Chat Completions format (it is in the repo as mock-llm/server.mjs). The SDK's openai-compatible driver needs a url and, for text, a default model:
// config/ai.php
'default' => env('AI_DEFAULT_PROVIDER', 'openai'),
'providers' => [
// ...
'openai-compatible' => [
'driver' => 'openai-compatible',
'url' => env('OPENAI_COMPATIBLE_URL'),
'key' => env('OPENAI_COMPATIBLE_API_KEY'),
'models' => [
'text' => [
'default' => env('OPENAI_COMPATIBLE_MODEL'),
],
],
],
],
AI_DEFAULT_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_URL=http://127.0.0.1:4010/v1
OPENAI_COMPATIBLE_MODEL=mock-model
The mock is not a model. It follows a few hard-coded rules (if the message contains a four-digit number, call LookupOrder). It is only there so the HTTP, streaming and UI code can be tested for real. Swap in a real provider when you want real answers.
The data
The order table is deliberately small:
Schema::create('orders', function (Blueprint $table) {
$table->id();
$table->string('number')->unique();
$table->string('customer_name');
$table->string('status'); // shipped, delayed, delivered, refunded
$table->date('eta')->nullable();
$table->unsignedInteger('total_cents');
$table->timestamp('refunded_at')->nullable();
$table->timestamps();
});
An OrderSeeder creates the three orders. The Order model casts eta to a date. Nothing about the AI SDK yet.
Create the agent
php artisan make:agent SupportAgent
The generated class implements Agent, Conversational and HasTools, with an empty messages() method. We are going to pass the chat history from the browser with withMessages(), and the SDK does not allow both: calling withMessages() on a Conversational agent throws a LogicException ("Ad-hoc message history may not be combined with a conversational agent."). So remove Conversational and the messages() method:
<?php
namespace App\Ai\Agents;
use App\Ai\Tools\LookupOrder;
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Stringable;
#[MaxSteps(5)]
class SupportAgent implements Agent, HasTools
{
use Promptable;
public function instructions(): Stringable|string
{
return <<<'TEXT'
You are the support assistant for a small online shop.
Use the LookupOrder tool whenever the customer mentions an order number.
Never guess an order status or delivery date: if the tool finds nothing, say so.
Keep answers short and friendly.
TEXT;
}
public function tools(): iterable
{
return [
new LookupOrder,
];
}
}
#[MaxSteps(5)] caps how many model round-trips one turn can take. A tool call costs at least two steps (the call, then the answer), so five leaves room without letting a confused model loop forever.
Create the tool
php artisan make:tool LookupOrder
A tool has three methods: a description the model reads, a JSON schema for its arguments, and handle():
<?php
namespace App\Ai\Tools;
use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;
class LookupOrder implements Tool
{
public function description(): Stringable|string
{
return 'Look up a customer order by its order number and return its status and estimated delivery date.';
}
public function handle(Request $request): Stringable|string
{
$validated = $request->validate([
'order_number' => 'required|string|digits:4',
]);
$order = Order::firstWhere('number', $validated['order_number']);
if (! $order) {
return "No order found with number {$validated['order_number']}.";
}
return json_encode([
'number' => $order->number,
'status' => $order->status,
'eta' => $order->eta?->toDateString(),
]);
}
public function schema(JsonSchema $schema): array
{
return [
'order_number' => $schema->string()
->description('The four-digit order number, without the # sign.')
->required(),
];
}
}
Two details matter here.
First, the schema constrains what the model sends, but it is not validation. $request->validate() is. When validation fails, the SDK sends the validation messages back to the model as the tool result so it can correct itself (Validating Tool Arguments).
Second, the tool's name. Unless you define a name() method, the SDK uses the class basename, so the model sees a function called LookupOrder. That name also ends up in the browser as the part type tool-LookupOrder, which we will use in the Vue template.
The chat route
This is the part the docs cover under Frontend Integration:
<?php
namespace App\Http\Controllers;
use App\Ai\Agents\SupportAgent;
use Illuminate\Http\Request;
use Laravel\Ai\Vercel\Vercel;
class ChatController extends Controller
{
public function store(Request $request)
{
$request->validate([
'messages' => ['required', 'array', 'max:50'],
]);
$chat = Vercel::chat($request);
return (new SupportAgent)
->withMessages($chat->history())
->stream($chat)
->usingProtocol($chat->protocol());
}
}
// routes/web.php
Route::post('/chat', [ChatController::class, 'store'])
->middleware('throttle:ai');
// app/Providers/AppServiceProvider.php, in boot()
RateLimiter::for('ai', function (Request $request) {
return Limit::perMinute(30)->by($request->user()?->id ?: $request->ip());
});
Here is what each line does, based on reading Laravel\Ai\Vercel\Chat in the package:
Vercel::chat($request) reads the messages array that useChat posts.
$chat->history() converts every message before the newest user message into SDK Message objects, including earlier tool calls and results.
- Passing
$chat itself to stream() makes the agent use the newest user message as the prompt. (Later, when tools need approval, the same object carries the user's decisions.)
$chat->protocol() returns the Vercel data protocol, so the response is a stream that useChat can parse.
throttle:ai is a named rate limiter I defined in AppServiceProvider, so every route that calls a model shares one budget per user or IP. With plain throttle:20,1 on several routes, Laravel keys the limit by the logged-in user or the IP, not by the route, so the routes end up sharing one counter anyway. That surprised me in testing.
If you curl this route, you can see what the browser receives. Shortened:
data: {"type":"start","messageId":"01a1deba-..."}
data: {"type":"start-step"}
data: {"type":"tool-input-available","toolCallId":"call_1","toolName":"LookupOrder","input":{"order_number":"1001"}}
data: {"type":"tool-output-available","toolCallId":"call_1","output":"{\"number\":\"1001\",\"status\":\"shipped\",\"eta\":\"2026-11-17\"}"}
data: {"type":"finish-step"}
data: {"type":"start-step"}
data: {"type":"text-delta","id":"01a1deba-...","delta":"Order "}
data: {"type":"text-delta","id":"01a1deba-...","delta":"#1001 "}
...
data: {"type":"finish","finishReason":"stop","messageMetadata":{"usage":{...}}}
data: [DONE]
The response also carries x-vercel-ai-ui-message-stream: v1 and X-Accel-Buffering: no headers. The second one tells Nginx not to buffer the stream.
The Vue component
Install the client packages:
npm install vue ai @ai-sdk/vue
npm install -D @vitejs/plugin-vue
In version 4 of @ai-sdk/vue, useChat is a composable that returns refs (messages, status, error) plus methods such as sendMessage and stop. The older Chat class is still exported but marked as deprecated. The endpoint is configured through a transport:
<script setup>
import { ref, computed } from 'vue';
import { useChat } from '@ai-sdk/vue';
import { DefaultChatTransport } from 'ai';
const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content ?? '';
const { messages, status, error, sendMessage, stop } = useChat({
transport: new DefaultChatTransport({
api: '/chat',
headers: { 'X-CSRF-TOKEN': csrfToken },
}),
});
const input = ref('');
const busy = computed(() => status.value === 'submitted' || status.value === 'streaming');
function submit() {
const text = input.value.trim();
if (!text || busy.value) return;
sendMessage({ text });
input.value = '';
}
</script>
Because /chat is a web route, Laravel's CSRF middleware applies. The Blade layout prints <meta name="csrf-token" content="{{ csrf_token() }}"> and the transport sends it as X-CSRF-TOKEN on every request.
status goes through submitted (request sent, nothing received yet), streaming, then ready, or error. That is enough to show a "Thinking…" hint and swap the Send button for a Stop button:
<template>
<main class="mx-auto max-w-xl p-6">
<ul class="space-y-3">
<li v-for="message in messages" :key="message.id"
:class="message.role === 'user' ? 'text-right' : 'text-left'">
<template v-for="(part, index) in message.parts" :key="index">
<p v-if="part.type === 'text'" class="inline-block whitespace-pre-wrap rounded-lg bg-white px-3 py-2 shadow-sm">
{{ part.text }}
</p>
<div v-else-if="part.type === 'tool-LookupOrder'" class="my-1 rounded border border-dashed px-3 py-2 text-sm text-gray-600">
<span v-if="part.state === 'output-available'">Checked order #{{ part.input.order_number }}</span>
<span v-else-if="part.state === 'output-error'">Lookup failed: {{ part.errorText }}</span>
<span v-else>Looking up order…</span>
</div>
</template>
</li>
</ul>
<p v-if="status === 'submitted'" class="mt-3 text-sm text-gray-500">Thinking…</p>
<p v-if="error" class="mt-3 text-sm text-red-600">Something went wrong. Please try again.</p>
<form class="mt-4 flex gap-2" @submit.prevent="submit">
<input v-model="input" class="flex-1 rounded border px-3 py-2" placeholder="Where is order 1001?" :disabled="busy" />
<button v-if="busy" type="button" class="rounded border px-3" @click="stop">Stop</button>
<button v-else type="submit" class="rounded bg-black px-3 text-white">Send</button>
</form>
</main>
</template>
Each message has a parts array, not a single content string. A turn with a tool call looks like this once it finishes (I logged it from the running app): step-start, tool-LookupOrder with state output-available, another step-start, then a text part. Rendering parts instead of a flattened string is what lets you show "Checked order #1001" between the user's question and the answer.
Ignore the step-start parts unless you want visual separators between steps.
Multi-turn conversations
useChat posts the whole transcript on every request. On the second question ("And order 9999?"), the request contains four messages, and Vercel::chat()->history() turns the first three into context, including the earlier tool call and its result. In my run, the second answer was "No order found with number 9999.", which came straight from the tool's not-found branch.
This is simple and stateless, and it is fine for a read-only tool. But keep in mind that the history comes from the browser, so a user can edit it. Never let that history decide whether something sensitive is allowed to happen. In the next article, a RefundOrder tool needs a human to approve it, and I show why that requires storing the conversation on the server.
How I checked that it works
I did not want to publish code I had only looked at, so the demo has three layers of checks:
- A Pest test that fakes the agent and asserts on the streamed body.
SupportAgent::fake() accepts a list of responses. In the 1.4.0 source, the fake gateway also accepts Laravel\Ai\Responses\Data\ToolCall objects, which makes the loop run the real LookupOrder tool against the test database. That is not in the docs, so treat it as an implementation detail:
SupportAgent::fake([
new ToolCall('call_1', 'LookupOrder', ['order_number' => '1001']),
'Order #1001 has shipped.',
])->preventStrayPrompts();
$body = $this->postJson('/chat', ['messages' => [
['id' => 'u1', 'role' => 'user', 'parts' => [['type' => 'text', 'text' => 'Where is order 1001?']]],
]])->assertOk()->streamedContent();
expect($body)
->toContain('"toolName":"LookupOrder"')
->toContain('\"status\":\"shipped\"')
->toContain('"type":"text-delta"');
- A Node script that runs the real
useChat composable (it works outside a component) against php artisan serve and the mock provider.
- A Vitest test that mounts
SupportChat.vue in happy-dom, types a question, submits the form, sees the Stop button while text is streaming, then checks the final answer and the "Checked order #1001" line.
The fifth article in this series goes deeper into testing agents with Pest.
Production notes
A few things that are easy to miss:
- Buffering. The SDK sets
X-Accel-Buffering: no, but a CDN or a load balancer can still hold the response until it ends. If tokens arrive all at once in production but stream locally, look there first.
- Errors reach the browser. When the provider returns an error in the middle of a stream, the Vercel protocol part I saw contained the provider's message as
errorText. My component shows a generic message instead of printing it.
- Authentication. My demo route is public and only rate-limited, to keep the tutorial short. A real app should put it behind
auth (session or Sanctum).
- No raw response. Streamed responses do not expose the provider's raw HTTP response, so headers like rate-limit counters are not available on this path (Raw HTTP Responses).
- Keys stay on the server. The browser only ever talks to your Laravel route.
Wrapping up
The amount of code is small: one agent class, one tool, a three-line controller method and a Vue component. Most of the work is understanding what moves over the wire. Vercel::chat() reads what useChat sends, usingProtocol() writes what it expects back, and your template renders parts.
The companion demo includes the mock provider, the Pest test and the Vitest test. Next up: adding a RefundOrder tool that pauses until a human clicks Approve, and the security mistake I almost made while building it.