Trois façons de streamer des jetons de LLM dans Vue : fetch, useChat et Laravel Echo
Gentil Maliyamungu B. · 2026-11-15
Le même agent Laravel AI SDK streamé dans Vue de trois façons : fetch avec SSE, useChat, et une exécution en file via Reverb et Echo, avec les compromis.
Quand une application Vue parle à un backend Laravel qui appelle un modèle de langage, « stream the answer » peut vouloir dire trois choses assez différentes :
- Le navigateur fait un POST et lit le corps de la réponse à mesure qu'il arrive (Server-Sent Events via
fetch).
- Le navigateur utilise une bibliothèque de chat qui parle un protocole plus riche sur le même type de flux HTTP (
useChat de @ai-sdk/vue).
- Le navigateur fait un POST, reçoit un 202, et écoute un WebSocket pendant qu'un worker de file exécute le modèle et diffuse les événements (Laravel Reverb et Echo).
Le Laravel AI SDK prend en charge les trois d'emblée. J'ai placé le même petit agent de support (il peut chercher une commande avec un outil LookupOrder) derrière trois routes, écrit un client Vue pour chacune, et les ai toutes exécutées contre une application Laravel locale. Cet article les compare avec du code qui fonctionne et les détails qui n'apparaissent que quand on les lance.
Testé avec laravel/ai 1.4.0, Laravel 13.42, Reverb 1.13, ai 7.0.173, @ai-sdk/vue 4.0.173, @laravel/echo-vue 2.6.3 et Vue 3.5.
Les trois routes
use App\Ai\Agents\SupportAgent;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Http\Request;
// A: the SDK's default SSE event format.
Route::post('/chat/raw', function (Request $request) {
$validated = $request->validate(['message' => ['required', 'string', 'max:2000']]);
return (new SupportAgent)->stream($validated['message']);
})->middleware('throttle:ai');
// B: the Vercel UI message stream that useChat expects.
Route::post('/chat', [ChatController::class, 'store'])->middleware('throttle:ai');
// C: run on a queue, broadcast over Reverb.
Route::post('/chat/queued', function (Request $request) {
$validated = $request->validate(['message' => ['required', 'string', 'max:2000']]);
(new SupportAgent)->broadcastOnQueue(
$validated['message'],
new PrivateChannel('App.Models.User.'.$request->user()->id),
);
return response()->noContent(202);
})->middleware(['auth', 'throttle:ai']);
Le contrôleur de la route B est Vercel::chat($request) plus ->stream($chat)->usingProtocol($chat->protocol()), détaillé dans le premier article de cette série. Ici je me concentre sur le côté client de chacune.
A : fetch et le format SSE par défaut
Renvoyer ->stream() depuis une route envoie text/event-stream avec un objet JSON par ligne data:. Pour « Where is order 1002? », les types d'événements, dans l'ordre, étaient :
stream_start, tool_call, tool_result, stream_start, text_start,
text_delta (x9), text_end, stream_end, [DONE]
Il y a un stream_start par étape du modèle (l'appel d'outil est l'étape un, la réponse est l'étape deux) mais un seul stream_end, tout à la fin. Un text_delta ressemble à ceci :
{"id":"01a1debe-...","invocation_id":"01a1debe-...","type":"text_delta","message_id":"01a1debe-...","delta":"Order ","timestamp":1794738385}
L'EventSource du navigateur ne fait que des requêtes GET, et vous ne voulez pas le message de l'utilisateur dans une chaîne de requête. Lisez donc le flux avec fetch :
// resources/js/composables/useFetchStream.js
import { ref } from 'vue';
export function useFetchStream(url) {
const text = ref('');
const tools = ref([]);
const status = ref('ready'); // ready | streaming | error
const error = ref(null);
let controller = null;
function handle(event) {
// Provider errors put the provider's error code in `type`, so detect them by shape.
if ('recoverable' in event && 'message' in event) {
throw new Error(event.message);
}
switch (event.type) {
case 'text_delta':
text.value += event.delta;
break;
case 'tool_call':
tools.value.push({ id: event.tool_id, name: event.tool_name, input: event.arguments, result: null });
break;
case 'tool_result': {
const call = tools.value.find((t) => t.id === event.tool_id);
if (call) call.result = event.successful ? event.result : `Failed: ${event.error}`;
break;
}
}
}
async function send(message) {
controller = new AbortController();
text.value = '';
tools.value = [];
error.value = null;
status.value = 'streaming';
let finished = false;
try {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'text/event-stream',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content ?? '',
},
body: JSON.stringify({ message }),
signal: controller.signal,
});
if (!response.ok) throw new Error(`Request failed with ${response.status}`);
const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffer += value;
// SSE frames are separated by a blank line.
let boundary;
while ((boundary = buffer.indexOf('\n\n')) !== -1) {
const frame = buffer.slice(0, boundary);
buffer = buffer.slice(boundary + 2);
for (const line of frame.split('\n')) {
if (!line.startsWith('data: ')) continue;
const data = line.slice(6);
if (data === '[DONE]') { finished = true; continue; }
handle(JSON.parse(data));
}
}
}
if (!finished) throw new Error('The stream ended before the server finished.');
status.value = 'ready';
} catch (e) {
if (e.name === 'AbortError') {
status.value = 'ready';
return;
}
error.value = e;
status.value = 'error';
}
}
const stop = () => controller?.abort();
return { text, tools, status, error, send, stop };
}
Deux choses là-dedans viennent de l'avoir exécuté, pas de la lecture de la documentation :
- Les erreurs ne sont pas
type: "error". Quand j'ai fait échouer le fournisseur en milieu de flux, l'événement était {"type":"server_error","message":"The mock provider failed on purpose.","recoverable":false,...}. Le type est le code d'erreur propre au fournisseur. La section broadcasting de la documentation dit la même chose des erreurs diffusées (« the provider's own error code is available in the payload's type key »). Sur le flux brut, je détecte les erreurs par la présence de message et recoverable.
- Un flux en échec n'a pas de
[DONE]. La connexion se ferme simplement. Traitez « the body ended without [DONE] » comme un échec, sinon une réponse à moitié écrite paraîtra complète.
Les trames peuvent aussi être découpées entre plusieurs morceaux réseau, c'est pourquoi le code met en tampon jusqu'à une ligne vide au lieu d'analyser chaque morceau directement.
Indiqué pour : un petit widget, un bouton ponctuel « summarize this », ou un client où vous ne voulez pas de dépendance. Vous maîtrisez l'analyse, l'historique et le rendu des outils.
B : useChat
useChat fait tout cela pour vous, face au protocole de messages UI Vercel :
import { useChat } from '@ai-sdk/vue';
import { DefaultChatTransport } from 'ai';
const { messages, status, error, sendMessage, stop } = useChat({
transport: new DefaultChatTransport({
api: '/chat',
headers: { 'X-CSRF-TOKEN': csrfToken },
}),
});
Vous obtenez messages avec des parts typées (text, tool-LookupOrder avec des états comme input-available et output-available, reasoning, et ainsi de suite), une ref status (submitted, streaming, ready, error), stop(), et un historique de conversation envoyé à chaque requête. Les erreurs arrivent comme une partie de protocole ({"type":"error","errorText":"..."}) et aboutissent dans error.
Le vrai avantage apparaît avec les outils. L'approbation humaine pour les outils risqués est intégrée au protocole : le serveur envoie une partie tool-approval-request, et le client répond avec addToolApprovalResponse(). Avec le format SSE brut, vous devriez tout cela le concevoir vous-même.
Le compromis : le protocole est défini par le Vercel AI SDK, qui évolue vite. Entre versions majeures, l'API client a changé (DefaultChatTransport, sendMessage, parts au lieu de content), donc épinglez vos versions et lisez le changelog quand vous mettez à jour.
Indiqué pour : la plupart des interfaces de chat où vous contrôlez à la fois la route Laravel et l'application Vue.
C : exécutions en file diffusées avec Reverb et Echo
Les deux premières options gardent une requête HTTP ouverte pendant toute l'exécution, et le worker PHP qui la sert aussi. Si une exécution peut durer longtemps, ou si vous voulez qu'elle continue quand l'utilisateur ferme l'onglet, placez l'agent dans une file. broadcastOnQueue() dispatche un job, et le job diffuse chaque événement de flux sur le canal que vous lui donnez.
Côté Laravel, il vous faut le broadcasting et un worker de file :
php artisan install:broadcasting --reverb
php artisan reverb:start
php artisan queue:work
Le routes/channels.php par défaut autorise déjà App.Models.User.{id} pour l'utilisateur correspondant, donc je diffuse sur ce canal privé.
Les événements sont diffusés sous leur type, avec des noms personnalisés, donc les écouteurs Echo ont besoin d'un point en tête. Avec @laravel/echo-vue, useEcho gère l'abonnement au montage et le départ au démontage :
// resources/js/composables/useQueuedChat.js
import { ref } from 'vue';
import { useEcho } from '@laravel/echo-vue';
export function useQueuedChat(userId) {
const text = ref('');
const status = ref('ready'); // ready | waiting | streaming | error
const error = ref(null);
const channel = `App.Models.User.${userId}`;
useEcho(channel, '.text_delta', (event) => {
status.value = 'streaming';
text.value += event.delta;
});
useEcho(channel, '.stream_end', () => {
status.value = 'ready';
});
useEcho(channel, '.error', (event) => {
error.value = new Error(event.message);
status.value = 'error';
});
useEcho(channel, '.stream_failed', (event) => {
// A provider error is followed by stream_failed; keep the more specific message.
error.value ??= new Error(event.message ?? 'The queued run failed.');
status.value = 'error';
});
async function send(message) {
text.value = '';
error.value = null;
status.value = 'waiting';
const response = await fetch('/chat/queued', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content ?? '',
},
body: JSON.stringify({ message }),
});
if (response.status !== 202) {
error.value = new Error(`Request failed with ${response.status}`);
status.value = 'error';
}
}
return { text, status, error, send };
}
Et configurez Echo une fois, dans le fichier d'entrée de votre application :
import { configureEcho } from '@laravel/echo-vue';
configureEcho({ broadcaster: 'reverb' });
Avec seulement le nom du broadcaster, @laravel/echo-vue 2.6 complète la clé, l'hôte, le port et le schéma à partir des variables VITE_REVERB_* que install:broadcasting écrit dans votre .env.
Les charges utiles sont les mêmes objets JSON que dans l'option A, donc event.delta fonctionne de la même façon. Voici ce que j'ai vu en l'exécutant :
- Avec un appel d'outil, la séquence broadcast était la même que sur le flux HTTP : deux
stream_start, un tool_call, un tool_result, les événements de texte, et un stream_end.
- Quand le fournisseur a échoué, Echo a reçu à la fois
.error (avec le message du fournisseur) et .stream_failed (avec « The stream failed. »). Le ??= garde le message utile.
- Le canal est par utilisateur, pas par exécution. Si le même utilisateur lance deux exécutions à la fois (deux onglets), leurs événements se mélangent. Chaque charge utile inclut un
invocation_id, donc vous pouvez vous accrocher au premier que vous voyez après l'envoi et ignorer le reste. Ou n'autoriser qu'une exécution à la fois, comme le suppose ce composable.
Il n'y a pas de « stop » intégré ici. Annuler, c'est annuler un job en file, ce qu'il vous faudrait construire.
Indiqué pour : les exécutions longues, le travail en arrière-plan que l'utilisateur peut quitter, ou les agents que vous déclenchez déjà depuis des jobs. Le coût, c'est deux processus de plus (Reverb et un worker) et davantage à surveiller.
Côte à côte
| A : fetch + SSE | B : useChat | C : file + Echo |
| Requête | POST, réponse streamée | POST, réponse streamée | POST renvoie 202, événements en WebSocket |
| Code Laravel | ->stream() | Vercel::chat() + usingProtocol() | ->broadcastOnQueue() |
| Infra en plus | aucune | aucune | Reverb (ou Pusher/Ably) + worker de file |
| Appels d'outils dans l'UI | analyser tool_call / tool_result soi-même | parties tool-* avec des états | analyser les événements broadcast soi-même |
| Approbation humaine | à construire soi-même | intégrée au protocole | les événements existent (tool_approval_request), le branchement est à vous |
| Stop / abort | AbortController | stop() | pas de moyen intégré |
| Survit à la fermeture de l'onglet | non | non | oui, le job continue |
| Signal d'erreur | événement avec message + recoverable, puis le corps se termine sans [DONE] | partie error, ref error | .error puis .stream_failed |
| Dépendances client | aucune | ai, @ai-sdk/vue | laravel-echo, pusher-js, @laravel/echo-vue |
Celui que je choisirais
- Commencez par
useChat si vous contrôlez les deux bouts. Vous obtenez les parties d'outils, les approbations et la gestion de l'historique en quelques lignes de code.
- Descendez à fetch + SSE pour un petit widget qui n'affiche que du texte, ou quand vous ne pouvez pas ajouter les paquets AI SDK.
- Utilisez la file et Echo quand l'exécution doit survivre à la requête, ou que l'agent est déjà déclenché depuis un job, un webhook ou une tâche planifiée.
Quoi que vous choisissiez, vérifiez la mise en tampon en production. Les trois dépendent de ce que quelque chose entre PHP et le navigateur ne retienne pas les données : un proxy ou un CDN pour A et B, le chemin WebSocket pour C.
Comment les exemples ont été testés
Les trois clients ont tourné contre une application Laravel 13 locale avec php artisan serve, reverb:start, queue:work, et un petit serveur OpenAI-compatible scripté à la place d'un fournisseur payant. Vitest avec happy-dom a exécuté les composables et les composants :
- A : la réponse de consultation de commande et l'appel d'outil ont été analysés correctement, et une erreur de fournisseur forcée a produit
status: 'error' avec le message du fournisseur.
- B :
SupportChat.vue a streamé la réponse (le bouton Stop était visible en cours de flux), et une erreur a affiché le message d'erreur.
- C :
useQueuedChat dans un composant monté a reçu la réponse en file via Reverb, puis a reçu .error et .stream_failed pour un échec forcé.
La démo d'accompagnement inclut le code de chaque approche, avec une couverture Vitest pour les trois clients Vue.