Transmitir un agente de Laravel AI SDK a una interfaz de chat Vue con useChat
Gentil Maliyamungu B. · 2026-11-15
Crear un agente de soporte con Laravel AI SDK y una herramienta de consulta de pedidos, y transmitir sus respuestas a un chat de Vue 3 con useChat de @ai-sdk/vue.
Un chat que espera la respuesta completa antes de mostrar nada parece roto. Los usuarios miran un indicador durante cinco o diez segundos, y entonces aparece de golpe un muro de texto. La transmisión lo corrige: la respuesta sale palabra a palabra, y si el modelo llama a una herramienta también puedes mostrarlo.
El Laravel AI SDK (laravel/ai) ya sabe transmitir. Su documentación muestra un helper Vercel::chat() que habla el mismo protocolo que el useChat del Vercel AI SDK. La mayoría de los ejemplos que encontrarás en línea usan la versión de React de useChat, Livewire, o un cliente EventSource escrito a mano. Este tutorial hace la versión de Vue de principio a fin:
- un agente Laravel que responde preguntas de clientes de una tienda pequeña,
- una herramienta que el agente llama para buscar un pedido en la base de datos,
- un componente Vue 3 que transmite la respuesta y muestra la llamada a la herramienta cuando ocurre.
Todo lo que sigue se construyó y ejecutó con laravel/ai 1.4.0 en Laravel 13.42 y PHP 8.4, con ai 7.0.173, @ai-sdk/vue 4.0.173 y Vue 3.5. La parte JavaScript de estas bibliotecas cambia rápido, así que comprueba las versiones instaladas si algo no coincide.
Qué estamos construyendo
La demo es un chat de soporte para una tienda ficticia. Se insertan tres pedidos: 1001 (enviado), 1002 (retrasado) y 1003 (reembolsado). Cuando el usuario pregunta «Where is order 1001?», el agente llama a una herramienta LookupOrder, lee el resultado y transmite una respuesta breve.
Hay tres piezas:
SupportAgent, una clase PHP con instrucciones y una herramienta.
POST /chat, una ruta que convierte la petición de useChat en una llamada al agente y transmite la respuesta.
SupportChat.vue, un componente que usa useChat para enviar mensajes y renderizar las partes transmitidas.
Queda fuera de este artículo: las herramientas que necesitan la aprobación de una persona (eso es el artículo siguiente), guardar las conversaciones en la base de datos, y el RAG.
Instalar el Laravel AI SDK
Parte de una aplicación Laravel nueva y sigue la sección de instalación de la documentación:
composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate
El paso de publicación crea config/ai.php y las migraciones de las tablas de conversación del SDK. En este artículo no usamos esas tablas, pero ejecutar la migración ahora te evitas una sorpresa más adelante.
Añade una clave de proveedor a .env, por ejemplo OPENAI_API_KEY=... o OPENROUTER_API_KEY=.... El proveedor predeterminado se define en config/ai.php.
Ejecutarlo sin una clave de API
Al escribir esto quería que la demo funcionara en una máquina sin ninguna clave, así que hice configurable el proveedor predeterminado y lo apunté a un pequeño servidor programado que habla el formato OpenAI Chat Completions (está en el repositorio como mock-llm/server.mjs). El controlador openai-compatible del SDK necesita una url y, para el texto, un modelo predeterminado:
// 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
El mock no es un modelo. Sigue unas pocas reglas fijas (si el mensaje contiene un número de cuatro cifras, llama a LookupOrder). Solo está para poder probar de verdad el HTTP, la transmisión y la interfaz. Cámbialo por un proveedor real cuando quieras respuestas reales.
Los datos
La tabla de pedidos es deliberadamente pequeña:
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 crea los tres pedidos. El modelo Order convierte eta en una fecha. Todavía no hay nada del AI SDK.
Crear el agente
php artisan make:agent SupportAgent
La clase generada implementa Agent, Conversational y HasTools, con un método messages() vacío. Vamos a pasar el historial del chat desde el navegador con withMessages(), y el SDK no permite ambas cosas: llamar a withMessages() en un agente Conversational lanza una LogicException («Ad-hoc message history may not be combined with a conversational agent.»). Así que quita Conversational y el método 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)] limita cuántos viajes de ida y vuelta al modelo puede tener un turno. Una llamada a una herramienta cuesta al menos dos pasos (la llamada y luego la respuesta), así que cinco deja margen sin dejar que un modelo confuso entre en un bucle infinito.
Crear la herramienta
php artisan make:tool LookupOrder
Una herramienta tiene tres métodos: una descripción que lee el modelo, un esquema JSON para sus argumentos, y 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(),
];
}
}
Aquí importan dos detalles.
Primero, el esquema limita lo que envía el modelo, pero no es validación. $request->validate() sí lo es. Cuando la validación falla, el SDK devuelve los mensajes de validación al modelo como resultado de la herramienta para que pueda corregirse (Validating Tool Arguments).
Segundo, el nombre de la herramienta. Si no defines un método name(), el SDK usa el nombre base de la clase, así que el modelo ve una función llamada LookupOrder. Ese nombre también llega al navegador como el tipo de parte tool-LookupOrder, que usaremos en la plantilla de Vue.
La ruta de chat
Esta es la parte que la documentación cubre en 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());
});
Esto es lo que hace cada línea, según la lectura de Laravel\Ai\Vercel\Chat en el paquete:
Vercel::chat($request) lee el array messages que envía useChat.
$chat->history() convierte cada mensaje anterior al mensaje de usuario más reciente en objetos Message del SDK, incluidos las llamadas a herramientas y sus resultados anteriores.
- Pasar el propio
$chat a stream() hace que el agente use el mensaje de usuario más reciente como prompt. (Más adelante, cuando las herramientas necesiten aprobación, el mismo objeto lleva las decisiones del usuario.)
$chat->protocol() devuelve el protocolo de datos de Vercel, de modo que la respuesta es un flujo que useChat puede analizar.
throttle:ai es un limitador de ritmo con nombre que definí en AppServiceProvider, para que cada ruta que llama a un modelo comparta un mismo presupuesto por usuario o por IP. Con un simple throttle:20,1 en varias rutas, Laravel clavea el límite por el usuario autenticado o por la IP, no por la ruta, así que las rutas acaban compartiendo un solo contador. Eso me sorprendió al probarlo.
Si haces curl a esta ruta, puedes ver lo que recibe el navegador. Versión abreviada:
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 respuesta también lleva las cabeceras x-vercel-ai-ui-message-stream: v1 y X-Accel-Buffering: no. La segunda le dice a Nginx que no almacene el flujo en búfer.
El componente Vue
Instala los paquetes del cliente:
npm install vue ai @ai-sdk/vue
npm install -D @vitejs/plugin-vue
En la versión 4 de @ai-sdk/vue, useChat es un composable que devuelve refs (messages, status, error) y métodos como sendMessage y stop. La clase Chat anterior sigue exportándose, pero está marcada como obsoleta. El endpoint se configura mediante un transporte:
<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>
Como /chat es una ruta web, se aplica el middleware CSRF de Laravel. La plantilla Blade imprime <meta name="csrf-token" content="{{ csrf_token() }}"> y el transporte lo envía como X-CSRF-TOKEN en cada petición.
status pasa por submitted (petición enviada, aún no se ha recibido nada), streaming, luego ready, o error. Eso basta para mostrar un aviso «Thinking…» y cambiar el botón Send por un botón 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>
Cada mensaje tiene un array parts, no una sola cadena content. Un turno con una llamada a una herramienta queda así cuando termina (lo registré desde la aplicación en ejecución): step-start, tool-LookupOrder con estado output-available, otro step-start y luego una parte text. Renderizar las partes en lugar de una cadena aplanada es lo que permite mostrar «Checked order #1001» entre la pregunta del usuario y la respuesta.
Ignora las partes step-start salvo que quieras separadores visuales entre pasos.
Conversaciones de varios turnos
useChat envía toda la transcripción en cada petición. En la segunda pregunta («And order 9999?»), la petición contiene cuatro mensajes, y Vercel::chat()->history() convierte los tres primeros en contexto, incluida la llamada a la herramienta anterior y su resultado. En mi ejecución, la segunda respuesta fue «No order found with number 9999.», que salió directamente de la rama de no encontrado de la herramienta.
Esto es simple y sin estado, y está bien para una herramienta de solo lectura. Pero ten en cuenta que el historial viene del navegador, así que un usuario puede editarlo. Nunca dejes que ese historial decida si se permite algo sensible. En el artículo siguiente, una herramienta RefundOrder necesita la aprobación de una persona, y muestro por qué eso exige guardar la conversación en el servidor.
Cómo comprobé que funciona
No quería publicar código que solo hubiera leído, así que la demo tiene tres capas de comprobaciones:
- Un test de Pest que falsifica el agente y hace aserciones sobre el cuerpo transmitido.
SupportAgent::fake() acepta una lista de respuestas. En el código fuente de 1.4.0, la pasarela falsa también acepta objetos Laravel\Ai\Responses\Data\ToolCall, lo que hace que el bucle ejecute la herramienta real LookupOrder contra la base de pruebas. Eso no está en la documentación, así que trátalo como un detalle de implementación:
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 de Node que ejecuta el composable real
useChat (funciona fuera de un componente) contra php artisan serve y el proveedor mock.
- Un test de Vitest que monta
SupportChat.vue en happy-dom, escribe una pregunta, envía el formulario, ve el botón Stop mientras el texto se transmite, y luego comprueba la respuesta final y la línea «Checked order #1001».
El quinto artículo de esta serie profundiza en las pruebas de agentes con Pest.
Notas para producción
Algunas cosas fáciles de pasar por alto:
- El búfer. El SDK establece
X-Accel-Buffering: no, pero un CDN o un balanceador todavía puede retener la respuesta hasta que termina. Si los tokens llegan de golpe en producción pero se transmiten en local, mira ahí primero.
- Los errores llegan al navegador. Cuando el proveedor devuelve un error a mitad de un flujo, la parte del protocolo Vercel que vi contenía el mensaje del proveedor como
errorText. Mi componente muestra un mensaje genérico en lugar de imprimirlo.
- Autenticación. Mi ruta de demo es pública y solo tiene límite de ritmo, para mantener el tutorial corto. Una aplicación real debería ponerla detrás de
auth (sesión o Sanctum).
- Sin respuesta en bruto. Las respuestas transmitidas no exponen la respuesta HTTP en bruto del proveedor, así que cabeceras como los contadores de límite no están disponibles en este camino (Raw HTTP Responses).
- Las claves se quedan en el servidor. El navegador solo habla con tu ruta de Laravel.
Cierre
La cantidad de código es pequeña: una clase de agente, una herramienta, un método de controlador de tres líneas y un componente Vue. La mayor parte del trabajo es entender qué circula por el cable. Vercel::chat() lee lo que envía useChat, usingProtocol() escribe lo que espera de vuelta, y tu plantilla renderiza parts.
La demo de acompañamiento incluye el proveedor mock, el test de Pest y el test de Vitest. A continuación: añadir una herramienta RefundOrder que se pausa hasta que una persona pulsa Approve, y el error de seguridad que casi cometí al construirla.