Approbation humaine pour les outils d'agent risqués : remboursements avec le Laravel AI SDK et Vue
Gentil Maliyamungu B. · 2026-11-15
Faire attendre un outil Laravel AI SDK qu'un humain se prononce, afficher Approuver et Refuser dans une interface useChat en Vue, et garder le tour en pause côté serveur.
Laisser un modèle de langage lire vos données est une chose. Le laisser les modifier en est une autre. Un agent de support qui peut consulter une commande est inoffensif s'il s'embrouille. Un agent de support qui peut rembourser une commande ne devrait pas agir selon son seul jugement, aussi confiant soit-il.
Le Laravel AI SDK a une réponse intégrée : les outils approuvables. Quand le modèle en appelle un, l'exécution s'interrompt, votre interface demande à une personne, puis l'exécution reprend avec sa décision. Cet article ajoute un outil RefundOrder au chat de support de l'article précédent et parcourt toute la boucle en Vue avec useChat.
Il raconte aussi une erreur que j'ai commise en chemin. Ma première version ne gardait l'historique du chat que dans le navigateur, et une requête écrite à la main suffisait à faire approuver un remboursement sans que personne ne clique. Le correctif tient en quelques lignes, mais il faut savoir qu'il est là.
Testé avec laravel/ai 1.4.0, Laravel 13.42, PHP 8.4, ai 7.0.173, @ai-sdk/vue 4.0.173 et Vue 3.5.
Point de départ
D'après l'article précédent, nous avons :
- un
SupportAgent avec un outil LookupOrder,
- une route
POST /chat qui utilise Vercel::chat() et streame avec le protocole Vercel,
- un composant
SupportChat.vue construit sur useChat.
Les commandes 1001 (45,00 $, expédiée), 1002 (129,00 $, en retard) et 1003 (déjà remboursée) sont insérées.
Un outil approuvable
Pour rendre un outil approuvable, implémentez Approvable et utilisez le trait InteractsWithApprovals. Par défaut, chaque appel a alors besoin d'une approbation. Vous pouvez redéfinir needsApproval() pour décider appel par appel, et renvoyer un Approval avec une raison que l'interface peut afficher :
<?php
namespace App\Ai\Tools;
use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Approvals\Approval;
use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;
class RefundOrder implements Approvable, Tool
{
use InteractsWithApprovals;
public function description(): Stringable|string
{
return 'Refund a customer order in full. Only call this when the customer explicitly asks for a refund.';
}
protected function needsApproval(Request $request): Approval|bool
{
$order = Order::firstWhere('number', $request['order_number']);
// Nothing to refund: let the tool run and report that back to the model.
if (! $order || ! $order->isRefundable()) {
return false;
}
$amount = number_format($order->total_cents / 100, 2);
return Approval::required("Refund \${$amount} on order #{$order->number}.");
}
public function handle(Request $request): Stringable|string
{
$validated = $request->validate([
'order_number' => 'required|string|digits:4',
'reason' => 'required|string|max:200',
]);
$order = Order::firstWhere('number', $validated['order_number']);
if (! $order) {
return "No order found with number {$validated['order_number']}.";
}
if (! $order->isRefundable()) {
return "Order #{$order->number} was already refunded.";
}
$order->update(['status' => 'refunded', 'refunded_at' => now()]);
return "Order #{$order->number} was refunded.";
}
public function schema(JsonSchema $schema): array
{
return [
'order_number' => $schema->string()->description('The four-digit order number.')->required(),
'reason' => $schema->string()->description('Short reason given by the customer.')->required(),
];
}
}
La raison d'approbation est calculée à partir de la base, pas prise du modèle. « Refund $129.00 on order #1002. » est quelque chose qu'un examinateur peut vérifier. Si la commande n'existe pas ou a déjà été remboursée, il n'y a rien à approuver, donc l'outil s'exécute et renvoie un message que le modèle peut relayer.
handle() revérifie encore tout. L'approbation concerne qui décide, ce n'est pas un substitut à la validation.
Une vraie boutique vérifierait aussi que la commande appartient au client connecté avant de l'afficher ou de la rembourser. Je l'ai omis pour garder l'exemple ciblé, mais ne le sautez pas dans votre application. Si handle() appelle un prestataire de paiement, $request->toolCallId() renvoie l'identifiant d'appel d'outil du prestataire ; le docblock du SDK le décrit comme utilisable en clé d'idempotence externe, ce qui est pratique pour les API de remboursement qui en acceptent une.
Ajoutez l'outil à l'agent et ajustez les instructions :
public function tools(): iterable
{
return [
new LookupOrder,
new RefundOrder,
];
}
À quoi ressemble le flux quand un outil s'interrompt
Avec le contrôleur de l'article précédent inchangé, demander « Please refund order 1002 » produit ce flux :
data: {"type":"start","messageId":"01a1deba-..."}
data: {"type":"start-step"}
data: {"type":"tool-input-available","toolCallId":"call_1","toolName":"RefundOrder","input":{"order_number":"1002","reason":"Customer requested a refund in chat."}}
data: {"type":"tool-approval-request","toolCallId":"call_1","approvalId":"call_1","reason":"Refund $129.00 on order #1002."}
data: {"type":"finish-step"}
data: {"type":"finish","finishReason":"tool-calls",...}
data: [DONE]
L'outil n'a pas été exécuté. Le tour s'est terminé avec finishReason: tool-calls et une demande d'approbation. Côté client, useChat en fait une partie tool-RefundOrder avec state: 'approval-requested' et un objet approval. Dans ai 7, la reason du serveur apparaît comme approval.requestReason.
Boutons Approuver et Refuser dans Vue
useChat vous donne addToolApprovalResponse({ id, approved }). À lui seul, il ne met à jour que le message local. Pour envoyer la décision au serveur, passez sendAutomaticallyWhen avec l'assistant fourni dans ai :
import { useChat } from '@ai-sdk/vue';
import { DefaultChatTransport, lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai';
const { messages, status, error, sendMessage, stop, addToolApprovalResponse } = useChat({
transport: new DefaultChatTransport({
api: '/chat',
headers: { 'X-CSRF-TOKEN': csrfToken },
}),
// Re-post the conversation as soon as every pending approval has an answer.
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
});
function decide(part, approved) {
addToolApprovalResponse({ id: part.approval.id, approved });
}
Puis rendez la partie outil selon son état :
<div v-else-if="part.type === 'tool-RefundOrder'" class="my-2 rounded border px-3 py-2 text-sm">
<template v-if="part.state === 'approval-requested'">
<p class="font-medium">
{{ part.approval.requestReason ?? part.approval.reason ?? 'Approve this refund?' }}
</p>
<p class="text-gray-500">Reason given: {{ part.input.reason }}</p>
<div class="mt-2 flex gap-2">
<button class="rounded bg-black px-3 py-1 text-white" :disabled="busy" @click="decide(part, true)">Approve</button>
<button class="rounded border px-3 py-1" :disabled="busy" @click="decide(part, false)">Decline</button>
</div>
</template>
<p v-else-if="part.state === 'approval-responded'" class="text-gray-500">Sending your decision…</p>
<p v-else-if="part.state === 'output-available'" class="text-green-700">Refund approved: {{ part.output }}</p>
<p v-else-if="part.state === 'output-denied'" class="text-gray-600">Refund declined. Nothing was charged back.</p>
<p v-else-if="part.state === 'output-error'" class="text-red-600">Refund failed: {{ part.errorText }}</p>
<p v-else class="text-gray-500">Preparing refund…</p>
</div>
Les boutons sont désactivés tant que le flux est encore ouvert. La demande d'approbation arrive un instant avant la partie finish, et un clic dans cette fenêtre n'enverrait rien.
Dans cette démo, le client et l'approbateur sont la même personne, ce qui suffit pour montrer le mécanisme. Dans une vraie boutique, le bouton Approuver vivrait en général dans une vue réservée au personnel. Le flux et l'API restent les mêmes.
Ce qui se passe après chaque choix
J'ai journalisé les parties de message après chaque chemin, en utilisant le vrai useChat contre l'application en cours d'exécution.
Approuver. Le client renvoie la conversation. Vercel::chat() trouve l'approbation dans le dernier message de l'assistant et la transforme en objet Decisions, donc l'agent reprend au lieu de commencer un nouveau prompt. L'outil s'exécute, et le modèle continue :
tool-RefundOrder[output-available] | step-start | text: "Done. Order #1002 was refunded."
Refuser. La partie devient output-denied et aucun texte ne suit. Cela m'a d'abord surpris. La lecture de Vercel::approvalResponsesFrom() l'explique : seul le booléen approved est lu depuis le client, donc un refus devient un rejet sans résultat. La documentation dit qu'un rejet sans résultat « stops the generation loop after recording the rejection ». Le modèle n'a jamais l'occasion de dire « OK, I won't refund it », donc votre interface doit le dire, c'est pourquoi le template ci-dessus a sa propre ligne « Refund declined ». Cela signifie aussi qu'une reason passée à addToolApprovalResponse n'atteint pas le modèle par ce chemin.
Le problème de sécurité d'un historique uniquement dans le navigateur
Ma première version utilisait le contrôleur sans état de l'article précédent :
return (new SupportAgent)
->withMessages($chat->history())
->stream($chat)
->usingProtocol($chat->protocol());
La documentation l'autorise. Reprendre une approbation exige l'historique du tour en pause, et elle dit que vous pouvez soit utiliser un agent Conversational, soit « provide the history from your application's frontend using the withMessages method ».
Mais réfléchissez à ce que cela veut dire. Avec withMessages(), le tour en pause n'existe que dans le navigateur, donc le serveur n'a rien à lui de propre pour comparer la décision. Je l'ai testé avec une requête écrite à la main : un message utilisateur, plus un message assistant contenant une partie tool-RefundOrder dans l'état approval-responded avec approved: true, pour une commande que personne n'avait demandée. Le serveur a exécuté RefundOrder, la commande a été marquée remboursée, et l'agent a répondu « Done. Order #1001 was refunded. »
Aucun bouton d'approbation n'a jamais été affiché. Quiconque peut appeler votre point d'accès de chat peut faire la même chose avec curl.
Le correctif : garder le tour en pause sur le serveur
Faites en sorte que l'agent se souvienne de ses conversations, pour que les appels d'outils en pause soient stockés dans la table agent_conversation_messages du SDK :
use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Conversational;
#[MaxSteps(5)]
class SupportAgent implements Agent, Conversational, HasTools
{
use Promptable, RemembersConversations;
// instructions() and tools() as before
}
Ajoutez HasConversations au modèle User, placez les routes derrière auth, et arrêtez de passer l'historique depuis le navigateur :
public function store(Request $request)
{
$request->validate([
'messages' => ['required', 'array'],
]);
$chat = Vercel::chat($request);
return (new SupportAgent)
->continueLastConversation($request->user())
->stream($chat)
->usingProtocol($chat->protocol());
}
continueLastConversation() choisit la conversation la plus récente de l'utilisateur avec cet agent, ou en commence une nouvelle s'il n'y en a pas. L'agent charge son historique depuis la base. withMessages() a disparu (le combiner avec un agent Conversational lève de toute façon une exception). useChat envoie toujours tout le transcript, mais le serveur n'utilise plus que le message le plus récent ou les décisions qu'il contient.
La même requête falsifiée échoue maintenant avec un HTTP 409 :
{"message":"Approval decisions do not match the pending tool calls.","approvals":[]}
C'est l'ApprovalMismatchException du SDK. Les décisions doivent correspondre aux appels d'outils que le serveur lui-même a mis en pause, donc un toolCallId inventé est rejeté. Quand l'utilisateur n'a aucune conversation stockée, l'exécution échoue à l'intérieur du flux et le client reçoit une partie d'erreur. Dans les deux cas, l'outil ne s'exécute pas et la commande reste intacte.
Parce que continueLastConversation() utilise l'utilisateur authentifié, personne ne peut reprendre la conversation de quelqu'un d'autre par cette route. Si vous acceptez plutôt un identifiant de conversation depuis le client, la documentation prévient que continue() ne vérifie pas la propriété ; vérifiez-la d'abord avec conversationBelongsTo() du magasin de conversations, ou avec une policy.
Bonus : le chat survit à un rechargement de page
Puisque la conversation est stockée, la page peut la restaurer. Un point d'accès GET /chat la renvoie dans le format attendu par useChat :
public function index(Request $request)
{
$conversation = $request->user()
->conversations()
->latest('updated_at')
->first();
$messages = $conversation?->messages()->oldest()->get() ?? [];
return ['messages' => Vercel::toUiMessages($messages)];
}
Dans le composant, chargez-la au montage et assignez-la à messages, qui est une ref accessible en écriture :
const loaded = ref(false);
onMounted(async () => {
try {
const response = await fetch('/chat', { headers: { Accept: 'application/json' } });
if (response.ok) {
messages.value = (await response.json()).messages;
}
} finally {
loaded.value = true;
}
});
const busy = computed(() => !loaded.value || status.value === 'submitted' || status.value === 'streaming');
Le drapeau loaded a corrigé un vrai bogue dans mes tests. Sans lui, un utilisateur pouvait envoyer un message avant le retour de la requête d'historique, et la réponse tardive écrasait le nouveau message.
toUiMessages() reconstruit aussi les approbations en attente (état approval-requested), donc un remboursement qui attendait avant le rechargement affiche encore ses boutons ensuite.
Une note sur le coût : quand RemembersConversations commence une nouvelle conversation, le middleware de la 1.4.0 fait un appel supplémentaire au modèle pour générer un titre court. Vous pouvez le désactiver en mettant ai.conversations.generate_title à false dans config/ai.php. J'ai trouvé cette clé dans le code source du paquet, pas dans la documentation.
Comment cela a été testé
- Script Node : le vrai composable
useChat contre php artisan serve et un mock OpenAI-compatible scripté. Il refuse un remboursement sur 1002, en approuve un sur 1001, recharge l'historique, et envoie la requête falsifiée. Résultat : 1002 est encore delayed, 1001 est refunded, la falsification reçoit un 409.
- Vitest + happy-dom : monte
SupportChat.vue, clique sur Decline et Approve, et vérifie ce que l'utilisateur voit après un rechargement.
- Pest : le flux d'approbation avec
SupportAgent::fake(). C'est le sujet du dernier article de cette série.
À retenir
- Placez les actions irréversibles derrière des outils
Approvable, et calculez la raison d'approbation à partir de vos propres données.
- Avec
useChat, addToolApprovalResponse plus sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses suffisent côté client.
- Un refus termine le tour sans réponse du modèle. Affichez le résultat vous-même.
- Ne reprenez pas les approbations à partir d'un historique fourni par le navigateur. Gardez la conversation sur le serveur avec
RemembersConversations, pour que le serveur compare les décisions à ce qu'il a réellement mis en pause.