Aprobación humana para herramientas de agente arriesgadas: reembolsos con el Laravel AI SDK y Vue
Gentil Maliyamungu B. · 2026-11-15
Haz que una herramienta del Laravel AI SDK espere a una persona, muestra Aprobar y Rechazar en una interfaz useChat de Vue, y guarda el turno en pausa en el servidor.
Dejar que un modelo de lenguaje lea tus datos es una cosa. Dejar que los cambie es otra. Un agente de soporte que puede consultar un pedido es inofensivo si se confunde. Un agente de soporte que puede reembolsar un pedido no debería actuar según su propio criterio, por muy seguro que suene.
El Laravel AI SDK tiene una respuesta integrada: las herramientas aprobables. Cuando el modelo llama a una, la ejecución se pausa, tu interfaz pregunta a una persona y la ejecución se reanuda con su decisión. Este artículo añade una herramienta RefundOrder al chat de soporte del artículo anterior y recorre el bucle completo en Vue con useChat.
También cuenta un error que cometí por el camino. Mi primera versión guardaba el historial del chat solo en el navegador, y una petición escrita a mano bastaba para que un reembolso se aprobara sin que nadie pulsara nada. La corrección son unas pocas líneas, pero hay que saber que está ahí.
Probado con laravel/ai 1.4.0, Laravel 13.42, PHP 8.4, ai 7.0.173, @ai-sdk/vue 4.0.173 y Vue 3.5.
Punto de partida
Del artículo anterior tenemos:
- un
SupportAgent con una herramienta LookupOrder,
- una ruta
POST /chat que usa Vercel::chat() y transmite con el protocolo Vercel,
- un componente
SupportChat.vue construido sobre useChat.
Se insertan los pedidos 1001 (45,00 $, enviado), 1002 (129,00 $, retrasado) y 1003 (ya reembolsado).
Una herramienta aprobable
Para hacer una herramienta aprobable, implementa Approvable y usa el trait InteractsWithApprovals. Por defecto, entonces cada llamada necesita aprobación. Puedes sobrescribir needsApproval() para decidir por llamada, y devolver un Approval con una razón que la interfaz pueda mostrar:
<?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 razón de aprobación se calcula a partir de la base de datos, no se toma del modelo. «Refund $129.00 on order #1002.» es algo que un revisor puede comprobar. Si el pedido no existe o ya fue reembolsado, no hay nada que aprobar, así que la herramienta se ejecuta y devuelve un mensaje que el modelo puede retransmitir.
handle() vuelve a comprobarlo todo. La aprobación trata de quién decide, no sustituye a la validación.
Una tienda real también comprobaría que el pedido pertenece al cliente autenticado antes de mostrarlo o reembolsarlo. Lo omití para mantener el ejemplo centrado, pero no lo saltes en tu aplicación. Si handle() llama a un proveedor de pagos, $request->toolCallId() devuelve el identificador de llamada a herramienta del proveedor; el docblock del SDK lo describe como usable como clave de idempotencia externa, útil para las API de reembolso que aceptan una.
Añade la herramienta al agente y ajusta las instrucciones:
public function tools(): iterable
{
return [
new LookupOrder,
new RefundOrder,
];
}
Cómo se ve el flujo cuando una herramienta se pausa
Con el controlador del artículo anterior sin cambios, pedir «Please refund order 1002» produce este flujo:
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]
La herramienta no se ejecutó. El turno terminó con finishReason: tool-calls y una petición de aprobación. En el cliente, useChat lo convierte en una parte tool-RefundOrder con state: 'approval-requested' y un objeto approval. En ai 7, la reason del servidor aparece como approval.requestReason.
Botones Aprobar y Rechazar en Vue
useChat te da addToolApprovalResponse({ id, approved }). Por sí solo solo actualiza el mensaje local. Para enviar la decisión al servidor, pasa sendAutomaticallyWhen con el ayudante que viene en 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 });
}
Luego renderiza la parte de la herramienta según su estado:
<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>
Los botones están desactivados mientras el flujo sigue abierto. La petición de aprobación llega un instante antes de la parte finish, y un clic en esa ventana no enviaría nada.
En esta demo el cliente y quien aprueba son la misma persona, lo cual sirve para mostrar la mecánica. En una tienda real el botón Aprobar suele vivir en una vista de personal. El flujo y la API siguen siendo los mismos.
Qué ocurre después de cada elección
Registré las partes del mensaje después de cada camino, usando el useChat real contra la aplicación en ejecución.
Aprobar. El cliente vuelve a enviar la conversación. Vercel::chat() encuentra la aprobación en el último mensaje del asistente y la convierte en un objeto Decisions, así que el agente reanuda en lugar de empezar un prompt nuevo. La herramienta se ejecuta y el modelo continúa:
tool-RefundOrder[output-available] | step-start | text: "Done. Order #1002 was refunded."
Rechazar. La parte pasa a output-denied y no sigue ningún texto. Al principio me sorprendió. Leer Vercel::approvalResponsesFrom() lo explica: del cliente solo se lee el booleano approved, así que un rechazo se convierte en una denegación sin resultado. La documentación dice que una denegación sin resultado «stops the generation loop after recording the rejection». El modelo nunca tiene ocasión de decir «OK, I won't refund it», así que tu interfaz tiene que decirlo, por eso la plantilla de arriba tiene su propia línea «Refund declined». También significa que una reason pasada a addToolApprovalResponse no llega al modelo por este camino.
El problema de seguridad de un historial solo en el navegador
Mi primera versión usaba el controlador sin estado del artículo anterior:
return (new SupportAgent)
->withMessages($chat->history())
->stream($chat)
->usingProtocol($chat->protocol());
La documentación lo permite. Reanudar una aprobación necesita el historial del turno en pausa, y dice que puedes usar un agente Conversational o «provide the history from your application's frontend using the withMessages method».
Pero piensa en lo que eso significa. Con withMessages(), el turno en pausa vive solo en el navegador, así que el servidor no tiene nada propio con lo que comparar la decisión. Lo probé con una petición escrita a mano: un mensaje de usuario, más un mensaje del asistente con una parte tool-RefundOrder en estado approval-responded con approved: true, para un pedido que nadie había pedido. El servidor ejecutó RefundOrder, el pedido quedó marcado como reembolsado y el agente respondió «Done. Order #1001 was refunded.»
Nunca se mostró un botón de aprobación. Cualquiera que pueda llamar a tu endpoint de chat puede hacer lo mismo con curl.
La corrección: guardar el turno en pausa en el servidor
Haz que el agente recuerde sus conversaciones, para que las llamadas a herramientas en pausa se guarden en la tabla agent_conversation_messages del 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
}
Añade HasConversations al modelo User, pon las rutas detrás de auth y deja de pasar el historial desde el navegador:
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() elige la conversación más reciente del usuario con este agente, o empieza una nueva si no hay ninguna. El agente carga su historial desde la base de datos. withMessages() desaparece (combinarlo con un agente Conversational lanza una excepción de todos modos). useChat sigue enviando toda la transcripción, pero el servidor ahora solo usa el mensaje más reciente o las decisiones que contiene.
La misma petición falsificada ahora falla con un HTTP 409:
{"message":"Approval decisions do not match the pending tool calls.","approvals":[]}
Esa es la ApprovalMismatchException del SDK. Las decisiones tienen que coincidir con llamadas a herramientas que el propio servidor pausó, así que un toolCallId inventado se rechaza. Cuando el usuario no tiene ninguna conversación guardada, la ejecución falla dentro del flujo y el cliente recibe una parte de error. En ambos casos la herramienta no se ejecuta y el pedido queda intacto.
Como continueLastConversation() usa al usuario autenticado, nadie puede reanudar la conversación de otra persona por esta ruta. Si en su lugar aceptas un identificador de conversación desde el cliente, la documentación avisa de que continue() no comprueba la propiedad; compruébala antes con conversationBelongsTo() del almacén de conversaciones, o con una policy.
Extra: el chat sobrevive a una recarga de página
Como la conversación está guardada, la página puede restaurarla. Un endpoint GET /chat la devuelve en el formato que espera useChat:
public function index(Request $request)
{
$conversation = $request->user()
->conversations()
->latest('updated_at')
->first();
$messages = $conversation?->messages()->oldest()->get() ?? [];
return ['messages' => Vercel::toUiMessages($messages)];
}
En el componente, cárgala al montar y asígnala a messages, que es una ref escribible:
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');
El indicador loaded corrigió un error real en mis pruebas. Sin él, un usuario podía enviar un mensaje antes de que volviera la petición del historial, y la respuesta tardía sobrescribía el mensaje nuevo.
toUiMessages() también reconstruye las aprobaciones pendientes (estado approval-requested), así que un reembolso que esperaba antes de la recarga sigue mostrando sus botones después.
Una nota sobre el coste: cuando RemembersConversations empieza una conversación nueva, el middleware de 1.4.0 hace una llamada extra al modelo para generar un título corto. Puedes desactivarlo poniendo ai.conversations.generate_title en false en config/ai.php. Encontré esa clave en el código fuente del paquete, no en la documentación.
Cómo se probó esto
- Script de Node: el composable real
useChat contra php artisan serve y un mock compatible con OpenAI programado. Rechaza un reembolso en 1002, aprueba uno en 1001, recarga el historial y envía la petición falsificada. Resultado: 1002 sigue delayed, 1001 está refunded, la falsificación recibe un 409.
- Vitest + happy-dom: monta
SupportChat.vue, pulsa Decline y Approve, y comprueba lo que ve el usuario después de una recarga.
- Pest: el flujo de aprobación con
SupportAgent::fake(). Ese es el tema del último artículo de esta serie.
Conclusiones
- Pon las acciones irreversibles detrás de herramientas
Approvable y calcula la razón de aprobación a partir de tus propios datos.
- Con
useChat, addToolApprovalResponse más sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses es todo lo que el cliente necesita.
- Un rechazo termina el turno sin respuesta del modelo. Muestra el resultado tú.
- No reanudes aprobaciones a partir de un historial enviado por el navegador. Guarda la conversación en el servidor con
RemembersConversations, para que el servidor contraste las decisiones con lo que realmente pausó.