الموافقة البشرية على أدوات الوكيل الخطرة: الاسترداد باستخدام Laravel AI SDK وVue
Gentil Maliyamungu B. · 2026-11-15
اجعل أداة Laravel AI SDK تنتظر إنساناً، واعرض «موافقة» و«رفض» في واجهة useChat بـ Vue، واحتفظ بالجولة المتوقفة على الخادم.
السماح لنموذج لغوي بأن يقرأ بياناتك شيء. السماح له بأن يغيّرها شيء آخر. وكيل دعم يستطيع البحث عن طلب غير مؤذٍ إذا ارتبك. أما وكيل دعم يستطيع استرداد طلب فلا ينبغي أن يتصرف وفق حكمه وحده، مهما بدا واثقاً.
لدى 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. عندئذ يحتاج كل استدعاء افتراضياً إلى موافقة. يمكنك تجاوز 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() يعيد معرّف استدعاء الأداة لدى المزوّد؛ يصف docblock الخاص بـ SDK أنه صالح كمفتاح عدم تكرار خارجي، وهذا مفيد لواجهات الاسترداد التي تقبل واحداً.
أضف الأداة إلى الوكيل وعدّل التعليمات:
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، والنقر في تلك النافذة لن يرسل شيئاً.
في هذا العرض الزبون والموافق هما الشخص نفسه، وهذا يكفي لبيان الآلية. في متجر حقيقي عادة ما يعيش زر الموافقة في واجهة للموظفين. التدفّق وواجهة البرمجة يبقيان كما هما.
ماذا يحدث بعد كل اختيار
سجّلت أجزاء الرسالة بعد كل مسار، باستخدام 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.
الإصلاح: الإبقاء على الجولة المتوقفة على الخادم
اجعل الوكيل يتذكّر محادثاته، حتى تُخزَّن استدعاءات الأدوات المتوقفة في جدول agent_conversation_messages الخاص بـ 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
}
أضف 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":[]}
هذه هي ApprovalMismatchException الخاصة بـ SDK. يجب أن تطابق القرارات استدعاءات أدوات أوقفها الخادم نفسه، لذا يُرفض toolCallId مختلق. عندما لا يكون للمستخدم أي محادثة مخزّنة، يفشل التشغيل داخل التيار ويتلقى العميل جزء خطأ. في الحالتين لا تعمل الأداة ويبقى الطلب كما هو.
لأن continueLastConversation() يستخدم المستخدم المصادق عليه، لا يستطيع أحد استئناف محادثة شخص آخر عبر هذا المسار. إذا قبلت معرّف محادثة من العميل بدلاً من ذلك، تحذّر الوثائق من أن 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)];
}
في المكوّن، حمّلها عند التركيب وعيّنها إلى 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: composable
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، حتى يقابل الخادم القرارات بما أوقفه فعلاً.