Rellenar un formulario Vue con la salida estructurada de un agente Laravel AI SDK
Gentil Maliyamungu B. · 2026-11-15
Usa un esquema de salida estructurada del Laravel AI SDK para proponer campos de formulario, validarlos en el servidor y fusionarlos en un formulario Vue sin sobrescribir las ediciones del usuario.
No toda función de IA tiene que ser una ventana de chat. A menudo lo más útil que puede hacer un modelo es rellenar un formulario que luego revisa una persona: un ticket de soporte a partir de un correo del cliente, una ficha de producto a partir de la descripción de un proveedor, un gasto a partir de un recibo.
En este tutorial, un agente de soporte pega un mensaje del cliente en un formulario Vue, pulsa Draft with AI, y obtiene el asunto, la categoría, la prioridad, el número de pedido, el resumen y una respuesta sugerida ya rellenados. La persona sigue al mando:
- la salida del modelo se valida en el servidor con las mismas reglas que un envío humano, y los campos no válidos se descartan, no se muestran;
- los campos que la persona ya escribió nunca se sobrescriben;
- los campos rellenados por la IA quedan marcados hasta que alguien los edita;
- al guardar se ejecuta la misma validación otra vez, así que una petición fabricada no puede saltársela.
Probado con laravel/ai 1.4.0, Laravel 13.42, PHP 8.4 y Vue 3.5.
El agente y su esquema
El Laravel AI SDK permite que un agente devuelva salida estructurada implementando HasStructuredOutput y describiendo la forma con el constructor de esquemas JSON de Laravel:
php artisan make:agent TicketDraftAgent --structured
<?php
namespace App\Ai\Agents;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Promptable;
use Stringable;
class TicketDraftAgent implements Agent, HasStructuredOutput
{
use Promptable;
public const CATEGORIES = ['shipping', 'damaged_item', 'refund', 'other'];
public const PRIORITIES = ['low', 'normal', 'high'];
public function instructions(): Stringable|string
{
return <<<'TEXT'
You turn a customer's message into a draft support ticket for a small online shop.
Write the subject and summary in plain English, without inventing facts.
Only fill order_number if the customer wrote one; otherwise use null.
The suggested reply is a first draft for a human agent, not a promise.
TEXT;
}
public function schema(JsonSchema $schema): array
{
return [
'subject' => $schema->string()->max(80)->required(),
'category' => $schema->string()->enum(self::CATEGORIES)->required(),
'priority' => $schema->string()->enum(self::PRIORITIES)->required(),
'order_number' => $schema->string()->nullable()->required(),
'summary' => $schema->string()->required(),
'suggested_reply' => $schema->string()->required(),
];
}
}
Las categorías y las prioridades son constantes de clase para que el esquema y las reglas de validación compartan una sola lista.
order_number es a la vez nullable() y required(). Eso significa «incluye siempre la clave, y usa null cuando no hay ninguna», lo cual es más claro para el modelo que omitir la clave. También coincide con lo que esperan los modos estrictos de salida estructurada de proveedores como OpenAI: cada propiedad listada como requerida, con los valores opcionales expresados como anulables.
Lo que recibe el proveedor
Lo ejecuté contra un endpoint compatible con OpenAI y registré la petición. El SDK convirtió el esquema en un response_format como este (recortado):
{
"type": "json_schema",
"json_schema": {
"name": "schema_definition",
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"subject": { "type": "string", "maxLength": 80 },
"category": { "type": "string", "enum": ["shipping", "damaged_item", "refund", "other"] },
"priority": { "type": "string", "enum": ["low", "normal", "high"] },
"order_number": { "type": ["string", "null"] },
"summary": { "type": "string" },
"suggested_reply": { "type": "string" }
},
"required": ["subject", "category", "priority", "order_number", "summary", "suggested_reply"]
},
"strict": false
}
}
Fíjate en "strict": false. Con ese controlador y los ajustes predeterminados, se pide esta forma al proveedor pero no se le obliga. Incluso en modo estricto, maxLength y las reglas de negocio («this order exists») son cosas que deberías comprobar tú. Así que el servidor trata la respuesta del modelo como entrada de usuario.
El endpoint: prompt, luego validar
Al principio planeé transmitir la salida estructurada para que los campos se rellenaran a medida que se generaban. En 1.4.0 eso aún no es posible. Llamar a stream() en un agente con salida estructurada lanza:
InvalidArgumentException: Streaming structured output is not currently supported.
Así que el endpoint usa prompt() y devuelve JSON. Para un formulario corto la espera suele ser de unos segundos, y un estado «Drafting…» basta.
<?php
namespace App\Http\Controllers;
use App\Ai\Agents\TicketDraftAgent;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
class TicketController extends Controller
{
/**
* The rules a ticket must pass, whether a human or the model filled it in.
*/
protected function rules(): array
{
return [
'subject' => ['required', 'string', 'max:80'],
'category' => ['required', Rule::in(TicketDraftAgent::CATEGORIES)],
'priority' => ['required', Rule::in(TicketDraftAgent::PRIORITIES)],
'order_number' => ['nullable', 'digits:4', 'exists:orders,number'],
'summary' => ['required', 'string', 'max:2000'],
'suggested_reply' => ['nullable', 'string', 'max:2000'],
];
}
public function draft(Request $request)
{
$validated = $request->validate([
'message' => ['required', 'string', 'max:5000'],
]);
$draft = (new TicketDraftAgent)->prompt($validated['message'])->toArray();
$errors = Validator::make($draft, $this->rules())->errors()->toArray();
return response()->json([
// Cast so an empty draft is still a JSON object, not [].
'draft' => (object) array_diff_key($draft, $errors),
'rejected' => array_keys($errors),
]);
}
public function store(Request $request)
{
$ticket = $request->validate($this->rules());
// A real app would create a Ticket model here.
return response()->json(['ticket' => $ticket], 201);
}
}
Route::view('/tickets/new', 'tickets');
Route::post('/tickets/draft', [TicketController::class, 'draft'])->middleware('throttle:ai');
Route::post('/tickets', [TicketController::class, 'store']);
Algunos puntos:
->toArray() sobre la respuesta estructurada da los campos decodificados. La respuesta también admite acceso de array ($response['subject']).
- Los campos no válidos se descartan, no se «arreglan». Si el modelo inventa una categoría o un número de pedido que no existe, el cliente nunca ve ese valor, solo su nombre en
rejected. La persona lo rellena.
- La regla
exists:orders,number es la que más importa. Un esquema puede asegurar que order_number es una cadena. Solo tu base de datos puede decirte si ese pedido existe.
throttle:ai es un limitador de ritmo con nombre para los endpoints que cuestan dinero (Limit::perMinute(30) por usuario o IP en AppServiceProvider).
Cuando el modelo ignora el esquema
Quería saber qué ocurre cuando un modelo responde en prosa en lugar de JSON, así que hice que mi servidor de prueba contestara «Sure! Here is a ticket for you.» En 1.4.0, las pasarelas decodifican la salida estructurada con indulgencia: prueban JSON plano, luego un bloque de código delimitado, y si nada funciona devuelven un array vacío sin lanzar una excepción. Mi endpoint entonces devolvió:
{"draft":{},"rejected":["subject","category","priority","summary"]}
No se rompió nada. El formulario muestra a la persona que el borrador se ignoró. Ese array vacío es también por lo que convierto draft a un objeto: sin la conversión, el array vacío de PHP se convierte en [] en JSON.
El lado Vue: una petición de borrador en la que solo gana la última llamada
// resources/js/composables/useTicketDraft.js
import { ref } from 'vue';
const csrf = () => document.querySelector('meta[name="csrf-token"]')?.content ?? '';
export function useTicketDraft() {
const loading = ref(false);
const error = ref(null);
let controller = null;
async function requestDraft(message) {
controller?.abort(); // a new request replaces an old one
controller = new AbortController();
loading.value = true;
error.value = null;
try {
const response = await fetch('/tickets/draft', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'X-CSRF-TOKEN': csrf() },
body: JSON.stringify({ message }),
signal: controller.signal,
});
if (!response.ok) throw new Error(`Draft failed with ${response.status}`);
return await response.json(); // { draft, rejected }
} catch (e) {
if (e.name !== 'AbortError') error.value = e;
return null;
} finally {
loading.value = false;
}
}
return { loading, error, requestDraft, cancel: () => controller?.abort() };
}
Fusionar el borrador sin sobrescribir a la persona
El formulario guarda dos conjuntos: touched, los campos que escribió la persona, y aiFilled, los campos que rellenó el modelo y que nadie ha editado todavía.
<script setup>
import { reactive, ref } from 'vue';
import { useTicketDraft } from '../composables/useTicketDraft';
const fields = ['subject', 'category', 'priority', 'order_number', 'summary', 'suggested_reply'];
const customerMessage = ref('');
const form = reactive({ subject: '', category: '', priority: 'normal', order_number: '', summary: '', suggested_reply: '' });
const touched = reactive(new Set());
const aiFilled = reactive(new Set());
const rejected = ref([]);
const errors = ref({});
const saved = ref(false);
const { loading, error, requestDraft } = useTicketDraft();
function edit(field) {
touched.add(field);
aiFilled.delete(field);
}
async function draft() {
const result = await requestDraft(customerMessage.value);
if (!result) return;
for (const field of fields) {
// Never overwrite what the human already typed.
if (touched.has(field) || !(field in result.draft)) continue;
form[field] = result.draft[field] ?? '';
aiFilled.add(field);
}
rejected.value = result.rejected;
}
async function save() {
errors.value = {};
const response = await fetch('/tickets', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content ?? '',
},
body: JSON.stringify({ ...form, order_number: form.order_number || null }),
});
if (response.status === 422) {
errors.value = (await response.json()).errors;
return;
}
saved.value = response.ok;
}
</script>
Vue 3 hace que un Set reactivo funcione como esperarías: aiFilled.has('subject') en la plantilla se actualiza cuando cambia el conjunto.
El manejador edit() se ejecuta en @input y @change. Esos eventos solo se disparan cuando una persona interactúa con el campo. Cuando el código asigna form.subject desde el borrador, no se dispara ningún evento input, así que los valores rellenados por la IA no cuentan como ediciones.
La plantilla, acortada a dos campos:
<template>
<form class="space-y-3" @submit.prevent="save">
<label>
Customer message
<textarea v-model="customerMessage" name="message" rows="3" />
</label>
<button type="button" name="draft" :disabled="loading || !customerMessage.trim()" @click="draft">
{{ loading ? 'Drafting…' : 'Draft with AI' }}
</button>
<p v-if="error">Could not draft this ticket. Fill it in by hand.</p>
<p v-if="rejected.length">Ignored suggestions for: {{ rejected.join(', ') }}</p>
<fieldset :disabled="loading">
<label>
Subject <span v-if="aiFilled.has('subject')">AI draft</span>
<input v-model="form.subject" name="subject" @input="edit('subject')" />
</label>
<label>
Category <span v-if="aiFilled.has('category')">AI draft</span>
<select v-model="form.category" name="category" @change="edit('category')">
<option value="" disabled>Choose…</option>
<option value="shipping">Shipping</option>
<option value="damaged_item">Damaged item</option>
<option value="refund">Refund</option>
<option value="other">Other</option>
</select>
</label>
<!-- priority, order_number, summary, suggested_reply follow the same pattern -->
</fieldset>
<ul v-if="Object.keys(errors).length">
<li v-for="(messages, field) in errors" :key="field">{{ field }}: {{ messages[0] }}</li>
</ul>
<button type="submit" :disabled="loading">Create ticket</button>
<p v-if="saved">Ticket created.</p>
</form>
</template>
Desactivar el fieldset mientras corre la petición de borrador evita un caso confuso: la persona escribe en un campo, luego llega el borrador y rellena los campos de alrededor. Si quieres que sigan escribiendo mientras corre el borrador, quita el disabled. La comprobación touched sigue protegiendo sus ediciones.
Decisiones de diseño que conviene copiar
Etiqueta el contenido de IA hasta que una persona lo toque. La insignia «AI draft» desaparece cuando la persona edita el campo. Le dice al revisor qué valores nadie ha comprobado aún.
Mantén la respuesta sugerida como un borrador. El esquema la llama sugerencia, y las instrucciones dicen «not a promise». Nada en este flujo la envía al cliente. Una persona todavía tiene que copiarla o pulsar Send en tu sistema real de tickets.
Valida dos veces. draft() filtra la salida del modelo para que el formulario no muestre valores no válidos. store() valida todo otra vez porque el navegador puede enviar cualquier cosa. Ambos usan el mismo método rules().
No inventes datos que faltan. Las instrucciones dicen al modelo que use null cuando no hay número de pedido, y la regla exists atrapa los casos en los que lo inventa de todos modos.
Probarlo
El SDK puede falsificar agentes estructurados: pasa un array de valores de campo por cada prompt esperado. Estos tests de Pest cubren el endpoint:
use App\Ai\Agents\TicketDraftAgent;
it('returns the structured draft from the agent', function () {
TicketDraftAgent::fake([[
'subject' => 'Cracked screen',
'category' => 'damaged_item',
'priority' => 'high',
'order_number' => '1002',
'summary' => 'Phone arrived cracked.',
'suggested_reply' => 'Sorry! Can you send a photo?',
]])->preventStrayPrompts();
$this->postJson('/tickets/draft', ['message' => 'My phone from order 1002 is cracked'])
->assertOk()
->assertJsonPath('draft.category', 'damaged_item')
->assertJsonPath('draft.order_number', '1002')
->assertJsonPath('rejected', []);
TicketDraftAgent::assertPrompted(fn ($prompt) => $prompt->contains('cracked'));
});
it('drops fields that fail validation', function () {
TicketDraftAgent::fake([[
'subject' => 'Broken item',
'category' => 'complaint', // not an allowed category
'priority' => 'high',
'order_number' => '7777', // no such order
'summary' => 'Arrived broken.',
'suggested_reply' => 'Sorry!',
]])->preventStrayPrompts();
$this->postJson('/tickets/draft', ['message' => 'Order 7777 arrived broken'])
->assertOk()
->assertJsonMissingPath('draft.category')
->assertJsonMissingPath('draft.order_number')
->assertJsonPath('rejected', ['category', 'order_number']);
});
preventStrayPrompts() hace fallar el test si el código pregunta al agente más veces de las que falsificaste. Combinado con Http::preventStrayRequests() en tests/Pest.php, ningún test puede alcanzar un proveedor real por accidente.
Los cuatro tests del endpoint (incluido el caso del borrador vacío) pasan. También ejecuté el componente Vue con Vitest y happy-dom contra la app Laravel en ejecución y un servidor de prueba compatible con OpenAI programado. El test escribe un asunto, pide un borrador, y comprueba que el asunto se queda como se escribió, que los demás campos se rellenan, y que al guardar aparece «Ticket created.» Un segundo test comprueba que el pedido 7777 aparece como ignorado y que el campo se queda vacío.
Por dónde seguir
- Si tu formulario es largo y quieres que los campos aparezcan de forma progresiva, vigila el changelog del SDK por si llega la salida estructurada en streaming. Hasta entonces,
prompt() más un estado de carga es la opción fiable.
- Para borradores que tardan más, usa el método
queue() del SDK y empuja el resultado al navegador con broadcasting.
- Registra la lista
rejected. Si un campo se rechaza a menudo, mejora las instrucciones o la descripción del esquema de ese campo.
El modelo redacta y la persona decide. Las reglas de validación son lo que sostiene esa separación.