Préremplir un formulaire Vue avec la sortie structurée d'un agent Laravel AI SDK
Gentil Maliyamungu B. · 2026-11-15
Utiliser un schéma de sortie structurée du Laravel AI SDK pour proposer des champs de formulaire, les valider côté serveur, et les fusionner dans un formulaire Vue sans écraser les modifications de l'utilisateur.
Toutes les fonctionnalités d'IA n'ont pas besoin d'être une fenêtre de chat. Souvent, le plus utile qu'un modèle puisse faire, c'est remplir un formulaire qu'une personne vérifie ensuite : un ticket de support à partir d'un e-mail client, une fiche produit à partir d'une description fournisseur, une note de frais à partir d'un reçu.
Dans ce tutoriel, un agent de support colle un message client dans un formulaire Vue, clique sur Draft with AI, et obtient l'objet, la catégorie, la priorité, le numéro de commande, le résumé et une réponse suggérée déjà remplis. La personne reste aux commandes :
- la sortie du modèle est validée sur le serveur avec les mêmes règles qu'une saisie humaine, et les champs invalides sont écartés, pas affichés ;
- les champs que la personne a déjà saisis ne sont jamais écrasés ;
- les champs remplis par l'IA sont marqués jusqu'à ce que quelqu'un les modifie ;
- l'enregistrement lance la même validation une seconde fois, donc une requête fabriquée ne peut pas la contourner.
Testé avec laravel/ai 1.4.0, Laravel 13.42, PHP 8.4 et Vue 3.5.
L'agent et son schéma
Le Laravel AI SDK permet à un agent de renvoyer une sortie structurée en implémentant HasStructuredOutput et en décrivant la forme avec le constructeur de schémas 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(),
];
}
}
Les catégories et les priorités sont des constantes de classe, pour que le schéma et les règles de validation partagent une seule liste.
order_number est à la fois nullable() et required(). Cela signifie « toujours inclure la clé, et utiliser null quand il n'y en a pas », ce qui est plus clair pour le modèle que d'omettre la clé. Cela correspond aussi à ce qu'attendent les modes stricts de sortie structurée de fournisseurs comme OpenAI : chaque propriété listée comme requise, les valeurs optionnelles étant exprimées comme nullables.
Ce que le fournisseur reçoit
Je l'ai exécuté contre un point d'accès compatible OpenAI et j'ai journalisé la requête. Le SDK a transformé le schéma en un response_format comme celui-ci (raccourci) :
{
"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
}
}
Remarquez "strict": false. Avec ce driver et les réglages par défaut, on demande cette forme au fournisseur sans l'y forcer. Même en mode strict, maxLength et les règles métier (« this order exists ») sont des choses que vous devriez vérifier vous-même. Donc le serveur traite la réponse du modèle comme une saisie utilisateur.
Le point d'accès : prompt, puis validation
Au début, je prévoyais de streamer la sortie structurée pour que les champs se remplissent au fur et à mesure. En 1.4.0, ce n'est pas encore possible. Appeler stream() sur un agent avec une sortie structurée lève :
InvalidArgumentException: Streaming structured output is not currently supported.
Le point d'accès utilise donc prompt() et renvoie du JSON. Pour un formulaire court, l'attente est en général de quelques secondes, et un état « Drafting… » suffit.
<?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']);
Quelques points :
->toArray() sur la réponse structurée donne les champs décodés. La réponse prend aussi l'accès tableau ($response['subject']).
- Les champs invalides sont écartés, pas « corrigés ». Si le modèle invente une catégorie ou un numéro de commande qui n'existe pas, le client ne voit jamais cette valeur, seulement son nom dans
rejected. La personne le remplit.
- La règle
exists:orders,number est la plus importante. Un schéma peut garantir que order_number est une chaîne. Seule votre base peut dire si cette commande existe.
throttle:ai est un limiteur de débit nommé pour les points d'accès qui coûtent de l'argent (Limit::perMinute(30) par utilisateur ou IP dans AppServiceProvider).
Quand le modèle ignore le schéma
Je voulais savoir ce qui se passe quand un modèle répond en prose au lieu de JSON, donc j'ai fait répondre mon serveur de test « Sure! Here is a ticket for you. » En 1.4.0, les passerelles décodent la sortie structurée de façon souple : elles essaient du JSON brut, puis un bloc de code délimité, et si rien ne marche elles renvoient un tableau vide sans lever d'exception. Mon point d'accès a alors renvoyé :
{"draft":{},"rejected":["subject","category","priority","summary"]}
Rien ne s'est cassé. Le formulaire montre à l'humain que le brouillon a été ignoré. Ce tableau vide est aussi la raison pour laquelle je caste draft en objet : sans le cast, le tableau vide de PHP devient [] en JSON.
Côté Vue : une requête de brouillon où seul le dernier appel gagne
// 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() };
}
Fusionner le brouillon sans écraser l'humain
Le formulaire garde deux ensembles : touched, les champs que la personne a saisis, et aiFilled, les champs que le modèle a remplis et que personne n'a encore modifiés.
<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 fait fonctionner un Set réactif comme on l'espère : aiFilled.has('subject') dans le template se met à jour quand l'ensemble change.
Le gestionnaire edit() s'exécute sur @input et @change. Ces événements ne se déclenchent que lorsqu'une personne interagit avec le champ. Quand le code définit form.subject à partir du brouillon, aucun événement input ne se déclenche, donc les valeurs remplies par l'IA ne comptent pas comme des modifications.
Le template, raccourci à deux champs :
<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>
Désactiver le fieldset pendant que la requête de brouillon tourne évite un cas confus : la personne tape dans un champ, puis le brouillon arrive et remplit les champs autour. Si vous voulez que les gens continuent de taper pendant le brouillon, retirez le disabled. Le contrôle touched protège encore leurs modifications.
Choix de conception à reproduire
Étiqueter le contenu IA jusqu'à ce qu'un humain y touche. Le badge « AI draft » disparaît quand la personne modifie le champ. Il dit au relecteur quelles valeurs personne n'a encore vérifiées.
Garder la réponse suggérée comme un brouillon. Le schéma l'appelle une suggestion, et les instructions disent « not a promise ». Rien dans ce flux ne l'envoie au client. Une personne doit encore la copier ou cliquer sur Send dans votre vrai système de tickets.
Valider deux fois. draft() filtre la sortie du modèle pour que le formulaire n'affiche pas de valeurs invalides. store() valide tout à nouveau parce que le navigateur peut envoyer n'importe quoi. Les deux utilisent la même méthode rules().
Ne pas inventer les données manquantes. Les instructions disent au modèle d'utiliser null quand il n'y a pas de numéro de commande, et la règle exists rattrape les cas où il en invente un quand même.
Le tester
Le SDK peut facticer des agents structurés : passez un tableau de valeurs de champs par prompt attendu. Ces tests Pest couvrent le point d'accès :
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() fait échouer le test si le code interroge l'agent plus souvent que vous n'avez facticé. Combiné à Http::preventStrayRequests() dans tests/Pest.php, aucun test ne peut atteindre un vrai fournisseur par accident.
Les quatre tests du point d'accès (y compris le cas du brouillon vide) passent. J'ai aussi exécuté le composant Vue avec Vitest et happy-dom contre l'application Laravel en cours et un serveur de test OpenAI-compatible scripté. Le test saisit un objet, demande un brouillon, et vérifie que l'objet reste tel quel, que les autres champs sont remplis, et que l'enregistrement affiche « Ticket created. » Un second test vérifie que la commande 7777 est listée comme ignorée et que le champ reste vide.
Pour aller plus loin
- Si votre formulaire est long et que vous voulez que les champs apparaissent progressivement, surveillez le changelog du SDK pour la sortie structurée en flux. En attendant,
prompt() plus un état de chargement est l'option fiable.
- Pour les brouillons plus longs, utilisez la méthode
queue() du SDK et poussez le résultat vers le navigateur avec le broadcasting.
- Journalisez la liste
rejected. Si un champ est souvent rejeté, améliorez les instructions ou la description du schéma pour ce champ.
Le modèle propose, l'humain décide. Ce sont les règles de validation qui font tenir cette séparation.