Streamer un agent Laravel AI SDK dans une interface de chat Vue avec useChat
Gentil Maliyamungu B. · 2026-11-15
Construire un agent de support Laravel AI SDK avec un outil de consultation de commande, et streamer ses réponses dans un chat Vue 3 avec useChat de @ai-sdk/vue.
Un chat qui attend la réponse complète avant d'afficher quoi que ce soit donne une impression de panne. Les utilisateurs regardent un spinner pendant cinq ou dix secondes, puis un mur de texte apparaît d'un coup. Le streaming corrige cela : la réponse s'affiche mot par mot, et si le modèle appelle un outil, vous pouvez le montrer aussi.
Le Laravel AI SDK (laravel/ai) sait déjà streamer. Sa documentation présente un helper Vercel::chat() qui parle le même protocole que le useChat du Vercel AI SDK. La plupart des exemples que l'on trouve en ligne utilisent la version React de useChat, Livewire, ou un client EventSource écrit à la main. Ce tutoriel fait la version Vue de bout en bout :
- un agent Laravel qui répond aux questions des clients d'une petite boutique,
- un outil que l'agent appelle pour chercher une commande dans la base,
- un composant Vue 3 qui streame la réponse et affiche l'appel d'outil au moment où il a lieu.
Tout ce qui suit a été construit et exécuté avec laravel/ai 1.4.0, Laravel 13.42 et PHP 8.4, ainsi que ai 7.0.173, @ai-sdk/vue 4.0.173 et Vue 3.5. Le côté JavaScript de ces bibliothèques évolue vite : vérifiez vos versions installées si quelque chose ne correspond pas.
Ce que nous construisons
La démo est un chat de support pour une boutique fictive. Trois commandes sont insérées : 1001 (expédiée), 1002 (en retard) et 1003 (remboursée). Quand l'utilisateur demande « Where is order 1001? », l'agent appelle un outil LookupOrder, lit le résultat et streame une courte réponse.
Il y a trois pièces :
SupportAgent, une classe PHP avec des instructions et un outil.
POST /chat, une route qui transforme la requête useChat en appel d'agent et streame la réponse.
SupportChat.vue, un composant qui utilise useChat pour envoyer les messages et rendre les parties streamées.
Hors sujet dans cet article : les outils qui ont besoin d'une approbation humaine (c'est l'article suivant), l'enregistrement des conversations en base, et le RAG.
Installer le Laravel AI SDK
Partez d'une application Laravel neuve et suivez la section d'installation de la documentation :
composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate
L'étape de publication crée config/ai.php et les migrations des tables de conversation du SDK. Nous ne les utilisons pas dans cet article, mais lancer la migration maintenant vous évite une surprise plus tard.
Ajoutez une clé de fournisseur dans .env, par exemple OPENAI_API_KEY=... ou OPENROUTER_API_KEY=.... Le fournisseur par défaut se configure dans config/ai.php.
L'exécuter sans clé d'API
En écrivant cet article, je voulais que la démo tourne sur une machine sans aucune clé. J'ai donc rendu le fournisseur par défaut configurable, et je l'ai pointé vers un petit serveur scripté qui parle le format OpenAI Chat Completions (il se trouve dans le dépôt sous mock-llm/server.mjs). Le driver openai-compatible du SDK a besoin d'une url et, pour le texte, d'un modèle par défaut :
// 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
Le mock n'est pas un modèle. Il suit quelques règles en dur (si le message contient un nombre à quatre chiffres, appeler LookupOrder). Il sert uniquement à tester pour de bon le HTTP, le streaming et l'interface. Remplacez-le par un vrai fournisseur quand vous voudrez de vraies réponses.
Les données
La table des commandes est volontairement petite :
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();
});
Un OrderSeeder crée les trois commandes. Le modèle Order caste eta en date. Rien sur le AI SDK pour l'instant.
Créer l'agent
php artisan make:agent SupportAgent
La classe générée implémente Agent, Conversational et HasTools, avec une méthode messages() vide. Nous allons passer l'historique du chat depuis le navigateur avec withMessages(), et le SDK n'autorise pas les deux : appeler withMessages() sur un agent Conversational lève une LogicException (« Ad-hoc message history may not be combined with a conversational agent. »). Il faut donc retirer Conversational et la méthode messages() :
<?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)] limite le nombre d'allers-retours au modèle pour un tour. Un appel d'outil coûte au moins deux étapes (l'appel, puis la réponse), donc cinq laisse de la marge sans laisser un modèle perdu boucler indéfiniment.
Créer l'outil
php artisan make:tool LookupOrder
Un outil a trois méthodes : une description que le modèle lit, un schéma JSON pour ses arguments, et 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(),
];
}
}
Deux détails comptent ici.
D'abord, le schéma contraint ce que le modèle envoie, mais ce n'est pas de la validation. $request->validate() l'est. Quand la validation échoue, le SDK renvoie les messages de validation au modèle comme résultat de l'outil, pour qu'il puisse se corriger (Validating Tool Arguments).
Ensuite, le nom de l'outil. Sauf si vous définissez une méthode name(), le SDK utilise le nom de base de la classe, donc le modèle voit une fonction appelée LookupOrder. Ce nom arrive aussi dans le navigateur comme type de partie tool-LookupOrder, que nous utiliserons dans le template Vue.
La route de chat
C'est la partie que la documentation couvre sous 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());
});
Voici ce que fait chaque ligne, d'après la lecture de Laravel\Ai\Vercel\Chat dans le paquet :
Vercel::chat($request) lit le tableau messages que useChat envoie.
$chat->history() convertit chaque message avant le plus récent message utilisateur en objets Message du SDK, y compris les appels d'outils et leurs résultats précédents.
- Passer
$chat lui-même à stream() fait utiliser le plus récent message utilisateur comme prompt. (Plus tard, quand des outils demanderont une approbation, le même objet portera les décisions de l'utilisateur.)
$chat->protocol() renvoie le protocole de données Vercel, pour que la réponse soit un flux que useChat peut analyser.
throttle:ai est un limiteur de débit nommé que j'ai défini dans AppServiceProvider, pour que chaque route qui appelle un modèle partage un même budget par utilisateur ou par IP. Avec un simple throttle:20,1 sur plusieurs routes, Laravel clé la limite par l'utilisateur connecté ou par l'IP, pas par la route, donc les routes finissent par partager un seul compteur. Cela m'a surpris pendant les tests.
Si vous faites un curl sur cette route, vous voyez ce que le navigateur reçoit. Version raccourcie :
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]
La réponse porte aussi les en-têtes x-vercel-ai-ui-message-stream: v1 et X-Accel-Buffering: no. Le second dit à Nginx de ne pas mettre le flux en tampon.
Le composant Vue
Installez les paquets client :
npm install vue ai @ai-sdk/vue
npm install -D @vitejs/plugin-vue
Dans la version 4 de @ai-sdk/vue, useChat est un composable qui renvoie des refs (messages, status, error) et des méthodes comme sendMessage et stop. L'ancienne classe Chat est encore exportée, mais marquée comme dépréciée. Le point d'accès se configure via un 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>
Comme /chat est une route web, le middleware CSRF de Laravel s'applique. Le layout Blade affiche <meta name="csrf-token" content="{{ csrf_token() }}"> et le transport l'envoie en X-CSRF-TOKEN à chaque requête.
status passe par submitted (requête envoyée, rien reçu encore), streaming, puis ready, ou error. Cela suffit pour afficher un indice « Thinking… » et remplacer le bouton Send par un bouton Stop :
<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>
Chaque message a un tableau parts, pas une seule chaîne content. Un tour avec un appel d'outil ressemble à ceci une fois terminé (je l'ai journalisé depuis l'application en cours d'exécution) : step-start, tool-LookupOrder avec l'état output-available, un autre step-start, puis une partie text. Rendre les parties plutôt qu'une chaîne aplatie, c'est ce qui permet d'afficher « Checked order #1001 » entre la question de l'utilisateur et la réponse.
Ignorez les parties step-start, sauf si vous voulez des séparateurs visuels entre les étapes.
Conversations à plusieurs tours
useChat envoie tout le transcript à chaque requête. À la deuxième question (« And order 9999? »), la requête contient quatre messages, et Vercel::chat()->history() transforme les trois premiers en contexte, y compris l'appel d'outil précédent et son résultat. Dans mon exécution, la deuxième réponse était « No order found with number 9999. », qui venait directement de la branche « introuvable » de l'outil.
C'est simple et sans état, et cela convient à un outil en lecture seule. Mais gardez en tête que l'historique vient du navigateur, donc un utilisateur peut le modifier. Ne laissez jamais cet historique décider si une action sensible a le droit d'avoir lieu. Dans l'article suivant, un outil RefundOrder a besoin d'une approbation humaine, et je montre pourquoi cela exige de stocker la conversation côté serveur.
Comment j'ai vérifié que cela fonctionne
Je ne voulais pas publier du code que j'avais seulement lu, donc la démo a trois couches de vérifications :
- Un test Pest qui factice l'agent et fait des assertions sur le corps streamé.
SupportAgent::fake() accepte une liste de réponses. Dans le code source de la 1.4.0, la passerelle factice accepte aussi des objets Laravel\Ai\Responses\Data\ToolCall, ce qui fait exécuter la vraie boucle de l'outil LookupOrder contre la base de test. Ce n'est pas dans la documentation : considérez-le comme un détail d'implémentation :
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"');
- Un script Node qui exécute le vrai composable
useChat (il fonctionne hors d'un composant) contre php artisan serve et le fournisseur mock.
- Un test Vitest qui monte
SupportChat.vue dans happy-dom, saisit une question, envoie le formulaire, voit le bouton Stop pendant que le texte streame, puis vérifie la réponse finale et la ligne « Checked order #1001 ».
Le cinquième article de cette série va plus loin dans les tests d'agents avec Pest.
Notes pour la production
Quelques points faciles à manquer :
- La mise en tampon. Le SDK définit
X-Accel-Buffering: no, mais un CDN ou un équilibreur de charge peut quand même retenir la réponse jusqu'à la fin. Si les jetons arrivent d'un seul coup en production alors qu'ils streamment en local, commencez par regarder de ce côté.
- Les erreurs arrivent au navigateur. Quand le fournisseur renvoie une erreur au milieu d'un flux, la partie de protocole Vercel que j'ai vue contenait le message du fournisseur dans
errorText. Mon composant affiche un message générique au lieu de l'imprimer.
- L'authentification. Ma route de démo est publique et seulement limitée en débit, pour garder le tutoriel court. Une vraie application devrait la placer derrière
auth (session ou Sanctum).
- Pas de réponse brute. Les réponses streamées n'exposent pas la réponse HTTP brute du fournisseur, donc des en-têtes comme les compteurs de limite de débit ne sont pas disponibles sur ce chemin (Raw HTTP Responses).
- Les clés restent sur le serveur. Le navigateur ne parle jamais qu'à votre route Laravel.
Pour conclure
La quantité de code est petite : une classe d'agent, un outil, une méthode de contrôleur de trois lignes et un composant Vue. L'essentiel du travail, c'est de comprendre ce qui circule sur le fil. Vercel::chat() lit ce que useChat envoie, usingProtocol() écrit ce qu'il attend en retour, et votre template rend parts.
La démo d'accompagnement inclut le fournisseur mock, le test Pest et le test Vitest. La suite : ajouter un outil RefundOrder qui s'interrompt jusqu'à ce qu'un humain clique sur Approve, et l'erreur de sécurité que j'ai failli commettre en le construisant.