Human Approval for Risky Agent Tools: Refunds with the Laravel AI SDK and Vue
Gentil Maliyamungu B. · 2026-11-15
Make a Laravel AI SDK tool wait for a human, render Approve and Decline in a Vue useChat UI, and keep the paused turn on the server.
Letting a language model read your data is one thing. Letting it change your data is another. A support agent that can look up an order is harmless if it gets confused. A support agent that can refund an order should not act on its own judgment, however confident it sounds.
The Laravel AI SDK has a built-in answer: approvable tools. When the model calls one, the run pauses, your UI asks a person, and the run resumes with their decision. This article adds a RefundOrder tool to the support chat from the previous post and walks through the full loop in Vue with useChat.
It also covers a mistake I made on the way. My first version kept the chat history only in the browser, and a hand-written request was enough to get a refund approved without anyone clicking anything. The fix is a few lines, but you need to know it is there.
Tested with laravel/ai 1.4.0, Laravel 13.42, PHP 8.4, ai 7.0.173, @ai-sdk/vue 4.0.173 and Vue 3.5.
Starting point
From the previous article we have:
- a
SupportAgent with a LookupOrder tool,
- a
POST /chat route that uses Vercel::chat() and streams with the Vercel protocol,
- a
SupportChat.vue component built on useChat.
Orders 1001 ($45.00, shipped), 1002 ($129.00, delayed) and 1003 (already refunded) are seeded.
An approvable tool
To make a tool approvable, implement Approvable and use the InteractsWithApprovals trait. By default every call then needs approval. You can override needsApproval() to decide per call, and return an Approval with a reason that the UI can show:
<?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(),
];
}
}
The approval reason is computed from the database, not taken from the model. "Refund $129.00 on order #1002." is something a reviewer can check. If the order does not exist or was already refunded, there is nothing to approve, so the tool runs and returns a message the model can relay.
handle() still re-checks everything. Approval is about who decides, not a replacement for validation.
A real shop would also check that the order belongs to the logged-in customer before showing or refunding it. I left that out to keep the example focused, but do not skip it in your app. If handle() calls a payment provider, $request->toolCallId() returns the provider's tool-call ID; the SDK's docblock describes it as usable as an external idempotency key, which is handy for refund APIs that accept one.
Add the tool to the agent and adjust the instructions:
public function tools(): iterable
{
return [
new LookupOrder,
new RefundOrder,
];
}
What the stream looks like when a tool pauses
With the controller from the previous article unchanged, asking "Please refund order 1002" produces this stream:
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]
The tool did not run. The turn finished with finishReason: tool-calls and an approval request. On the client, useChat turns this into a tool-RefundOrder part with state: 'approval-requested' and an approval object. In ai 7, the server's reason shows up as approval.requestReason.
Approve and Decline buttons in Vue
useChat gives you addToolApprovalResponse({ id, approved }). On its own it only updates the local message. To send the decision to the server, pass sendAutomaticallyWhen with the helper that ships in 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 });
}
Then render the tool part by state:
<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>
The buttons are disabled while the stream is still open. The approval request arrives a moment before the finish part, and a click in that window would not send anything.
In this demo the customer and the approver are the same person, which is fine for showing the mechanics. In a real shop the Approve button would usually live in a staff view. The flow and the API stay the same.
What happens after each choice
I logged the message parts after each path, using the real useChat against the running app.
Approve. The client re-posts the conversation. Vercel::chat() finds the approval in the last assistant message and turns it into a Decisions object, so the agent resumes instead of starting a new prompt. The tool runs, and the model continues:
tool-RefundOrder[output-available] | step-start | text: "Done. Order #1002 was refunded."
Decline. The part becomes output-denied and no text follows. That surprised me at first. Reading Vercel::approvalResponsesFrom() explains it: only the approved boolean is read from the client, so a decline becomes a rejection without a result. The docs say a rejection without a result "stops the generation loop after recording the rejection". The model never gets a chance to say "OK, I won't refund it", so your UI has to say it, which is why the template above has its own "Refund declined" line. It also means a reason passed to addToolApprovalResponse does not reach the model through this path.
The security problem with browser-only history
My first version used the stateless controller from the previous article:
return (new SupportAgent)
->withMessages($chat->history())
->stream($chat)
->usingProtocol($chat->protocol());
The docs allow this. Resuming an approval needs the paused turn's history, and they say you can either use a Conversational agent or "provide the history from your application's frontend using the withMessages method".
But think about what that means. With withMessages(), the paused turn lives only in the browser, so the server has nothing of its own to compare the decision against. I tested it with a hand-written request: one user message, plus an assistant message containing a tool-RefundOrder part in state approval-responded with approved: true, for an order nobody had asked about. The server ran RefundOrder, the order was marked refunded, and the agent replied "Done. Order #1001 was refunded."
No approval button was ever shown. Anyone who can call your chat endpoint can do the same with curl.
The fix: keep the paused turn on the server
Make the agent remember its conversations, so the paused tool calls are stored in the SDK's agent_conversation_messages table:
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
}
Add HasConversations to the User model, put the routes behind auth, and stop passing history from the browser:
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() picks the user's most recent conversation with this agent, or starts a new one if there is none. The agent loads its history from the database. withMessages() is gone (combining it with a Conversational agent throws anyway). useChat still posts the whole transcript, but the server now only uses the newest message or the decisions in it.
The same forged request now fails with HTTP 409:
{"message":"Approval decisions do not match the pending tool calls.","approvals":[]}
That is the SDK's ApprovalMismatchException. Decisions have to match tool calls that the server itself paused on, so a made-up toolCallId is rejected. When the user has no stored conversation at all, the run fails inside the stream instead and the client gets an error part. In both cases the tool does not run and the order stays untouched.
Because continueLastConversation() uses the authenticated user, nobody can resume someone else's conversation through this route. If you accept a conversation ID from the client instead, the docs warn that continue() does not check ownership; check it with the conversation store's conversationBelongsTo() or a policy first.
Bonus: the chat survives a page reload
Since the conversation is stored, the page can restore it. A GET /chat endpoint returns it in the format useChat expects:
public function index(Request $request)
{
$conversation = $request->user()
->conversations()
->latest('updated_at')
->first();
$messages = $conversation?->messages()->oldest()->get() ?? [];
return ['messages' => Vercel::toUiMessages($messages)];
}
In the component, load it on mount and assign it to messages, which is a writable ref:
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');
The loaded flag fixed a real bug in my tests. Without it, a user could send a message before the history request returned, and the late response would overwrite the new message.
toUiMessages() also rebuilds pending approvals (state approval-requested), so a refund that was waiting before the reload still shows its buttons afterwards.
One cost note: when RemembersConversations starts a new conversation, the 1.4.0 middleware makes an extra call to the model to generate a short title. You can turn it off with ai.conversations.generate_title set to false in config/ai.php. I found that key in the package source, not in the docs.
How this was tested
- Node script: the real
useChat composable against php artisan serve and a scripted OpenAI-compatible mock. It declines a refund on 1002, approves one on 1001, reloads the history, and sends the forged request. Result: 1002 is still delayed, 1001 is refunded, the forgery gets a 409.
- Vitest + happy-dom: mounts
SupportChat.vue, clicks Decline and Approve, and checks what the user sees after a reload.
- Pest: the approval flow with
SupportAgent::fake(). That is the subject of the last article in this series.
Takeaways
- Put irreversible actions behind
Approvable tools, and compute the approval reason from your own data.
- With
useChat, addToolApprovalResponse plus sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses is all the client needs.
- A decline ends the turn without a model reply. Show the outcome yourself.
- Do not resume approvals from browser-supplied history. Keep the conversation on the server with
RemembersConversations, so the server checks decisions against what it actually paused on.