为高风险智能体工具加入人工批准:用 Laravel AI SDK 和 Vue 做退款
Gentil Maliyamungu B. · 2026-11-15
让 Laravel AI SDK 的工具先等待人工决定,在 Vue 的 useChat 界面中渲染“批准”和“拒绝”,并把暂停的这一轮保存在服务器上。
让语言模型 读取 你的数据是一回事。让它 改动 你的数据是另一回事。一个只会查询订单的客服智能体,就算搞混了,通常也没什么危害。一个能够退款的客服智能体,无论听起来多么自信,都不该只凭自己的判断行事。
Laravel AI SDK 内置了答案:可批准的工具。当模型调用这类工具时,运行会暂停,你的界面询问一个人,然后根据其决定继续。本文在上一篇文章的客服聊天中加入 RefundOrder 工具,并用 Vue 的 useChat 走完整条回路。
文中也写到我中途犯过的一个错误。我的第一版只把聊天历史放在浏览器里,一份手写的请求就足以在没人点击任何按钮的情况下把退款批准掉。修复只有几行,但你得知道它在那里。
测试环境为 laravel/ai 1.4.0、Laravel 13.42、PHP 8.4、ai 7.0.173、@ai-sdk/vue 4.0.173 和 Vue 3.5。
起点
从上一篇文章起,我们已经有:
- 一个
SupportAgent,带有 LookupOrder 工具,
- 一条
POST /chat 路由,使用 Vercel::chat() 并以 Vercel 协议做流式输出,
- 一个
SupportChat.vue 组件,建立在 useChat 上。
预先写入了订单 1001(45.00 美元,已发货)、1002(129.00 美元,延误)和 1003(已经退款)。
一个可批准的工具
要让工具变为可批准,实现 Approvable 并使用 InteractsWithApprovals trait。默认情况下,之后每次调用都需要批准。你可以重写 needsApproval(),按每次调用决定,并返回带有界面可展示原因的 Approval:
<?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(),
];
}
}
批准原因是从数据库算出来的,不是从模型那里拿来的。“Refund $129.00 on order #1002.” 是审查的人可以核对的内容。如果订单不存在或已经退过款,就没有什么需要批准,于是工具直接运行,并返回一条模型可以转述的消息。
handle() 仍会再次检查所有条件。批准解决的是 谁来决定,并不能代替校验。
真正的商店还会在展示或退款前检查该订单是否属于已登录客户。为了让例子聚焦,我把它省略了,但在你的应用里不要跳过。如果 handle() 会调用支付提供方,$request->toolCallId() 会返回提供方的工具调用 ID;SDK 的文档注释把它描述成可用作外部幂等键,这对接受这类键的退款 API 很有用。
把工具加到智能体上,并调整指令:
public function tools(): iterable
{
return [
new LookupOrder,
new RefundOrder,
];
}
工具暂停时,流看起来是什么样的
在上一篇文章的控制器保持不变的情况下,询问 “Please refund order 1002” 会产生这样的流:
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]
工具没有运行。这一轮以 finishReason: tool-calls 和一个批准请求结束。在客户端,useChat 会把它变成一个 tool-RefundOrder 分段,带有 state: 'approval-requested' 和一个 approval 对象。在 ai 7 里,服务器上的 reason 会显示为 approval.requestReason。
在 Vue 里做“批准”和“拒绝”按钮
useChat 提供 addToolApprovalResponse({ id, approved })。单独使用时,它只更新本地消息。要把决定发到服务器,请传入 sendAutomaticallyWhen,并使用 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 });
}
然后按状态渲染工具分段:
<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>
在流仍然打开时,按钮是禁用的。批准请求会在 finish 分段稍早一点到达,如果在这个窗口里点击,什么也不会发送。
在这个演示里,客户和批准者是同一个人,这足以展示机制。在真正的商店里,“批准”按钮通常会出现在员工视图中。流程和 API 保持不变。
每种选择之后会发生什么
我在每条路径之后都记录了消息分段,用的是对接正在运行的应用的真正 useChat。
批准。 客户端会重新提交整段对话。Vercel::chat() 在最后一条助手消息里找到批准,并把它转成 Decisions 对象,于是智能体继续运行,而不是开始新的提示。工具会执行,模型接着往下说:
tool-RefundOrder[output-available] | step-start | text: "Done. Order #1002 was refunded."
拒绝。 该分段变成 output-denied,并且 后面没有任何文本。起初这让我吃了一惊。阅读 Vercel::approvalResponsesFrom() 就能明白:从客户端只读取 approved 这个布尔值,因此拒绝会变成一次没有结果的驳回。文档写到,没有结果的驳回 “stops the generation loop after recording the rejection”。模型再也没有机会说 “OK, I won't refund it”,所以你的界面必须自己说出来,这也是上面的模板里有一行 “Refund declined” 的原因。这还意味着一个 reason,如果传给 addToolApprovalResponse,也不会通过这条路径到达模型。
只把历史放在浏览器里的安全问题
我的第一版用的是上一篇文章里那个无状态控制器:
return (new SupportAgent)
->withMessages($chat->history())
->stream($chat)
->usingProtocol($chat->protocol());
文档允许这样做。恢复一次批准需要被暂停那一轮的历史,文档说你可以要么使用 Conversational 智能体,要么 “provide the history from your application's frontend using the withMessages method”。
但要想想这意味着什么。使用 withMessages() 时,被暂停的那一轮只存在于浏览器中,服务器自己没有任何东西可以用来对照这个决定。我用一份手写请求测过:一条用户消息,再加上一条助手消息,其中包含一个 tool-RefundOrder 分段,状态为 approval-responded 且 approved: true,针对的是一笔根本没人问起的订单。服务器运行了 RefundOrder,订单被标成已退款,智能体回复 “Done. Order #1001 was refunded.”
批准按钮从未出现过。任何能调用你聊天端点的人,都可以用 curl 做同样的事。
修复:把暂停的这一轮留在服务器上
让智能体记住自己的对话,这样被暂停的工具调用就会存进 SDK 的 agent_conversation_messages 表:
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
}
把 HasConversations 加到 User 模型上,把路由放在 auth 后面,并不再从浏览器传入历史:
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() 会选取该用户与这个智能体最近的一次对话;如果没有,就新开一轮。智能体从数据库加载自己的历史。withMessages() 没有了(再说,把它和 Conversational 智能体合用本来就会抛错)。useChat 仍然会提交完整记录,但服务器现在只用最新的那条消息,或其中的决定。
同样那份伪造请求现在会以 HTTP 409 失败:
{"message":"Approval decisions do not match the pending tool calls.","approvals":[]}
这就是 SDK 的 ApprovalMismatchException。决定必须匹配服务器自己暂停过的工具调用,因此虚构的 toolCallId 会被拒绝。当用户还没有任何已存储的对话时,运行会在流内部失败,客户端收到一个错误分段。两种情况下工具都不会运行,订单保持原样。
因为 continueLastConversation() 使用的是已认证用户,没有人能通过这条路由恢复别人的对话。如果你改为从客户端接受一个对话 ID,文档警告 continue() 不会检查所有权;先用会话存储的 conversationBelongsTo() 或一条策略来检查。
额外收获:聊天能在页面刷新后留下来
既然对话已经存储,页面就可以把它恢复回来。一个 GET /chat 端点会按 useChat 期望的格式返回它:
public function index(Request $request)
{
$conversation = $request->user()
->conversations()
->latest('updated_at')
->first();
$messages = $conversation?->messages()->oldest()->get() ?? [];
return ['messages' => Vercel::toUiMessages($messages)];
}
在组件里,在挂载时加载它,并赋给可写的 ref messages:
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');
loaded 标志修复过我测试里一个真实的缺陷。没有它,用户可能在历史请求返回之前就发出一条消息,晚到的响应会把新消息覆盖掉。
toUiMessages() 也会重建待处理的批准(状态为 approval-requested),因此刷新前还在等待的退款,刷新后仍然会显示按钮。
还有一个成本方面的说明:当 RemembersConversations 开始一段新对话时,1.4.0 的中间件会再调用一次模型来生成短标题。你可以把 ai.conversations.generate_title 设为 false,写在 config/ai.php 里,即可关掉它。我是在包的源码里找到这个键的,文档里没有。
这是如何测试的
- Node 脚本: 用真正的
useChat 组合式函数对接 php artisan serve 和一个脚本化的 OpenAI 兼容模拟器。它拒绝 1002 的退款,批准 1001 的退款,重新加载历史,并发送那份伪造请求。结果:1002 仍是 delayed,1001 是 refunded,伪造请求得到 409。
- Vitest + happy-dom: 挂载
SupportChat.vue,点击 Decline 和 Approve,并检查刷新后用户看到的内容。
- Pest: 使用
SupportAgent::fake() 的批准流程。这是本系列最后一篇文章的主题。
要点
- 把不可逆的操作放在
Approvable 工具后面,并根据你自己的数据计算批准原因。
- 使用
useChat 时,客户端只需要 addToolApprovalResponse 加上 sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses。
- 拒绝会在没有模型回复的情况下结束这一轮。结果要由你自己展示。
- 不要根据浏览器提供的历史来恢复批准。用
RemembersConversations 把对话留在服务器上,这样服务器会拿决定去对照它真正暂停过的内容。