بث وكيل Laravel AI SDK إلى واجهة دردشة Vue باستخدام useChat
Gentil Maliyamungu B. · 2026-11-15
ابنِ وكيل دعم باستخدام Laravel AI SDK مع أداة للبحث عن الطلبات، وبث ردوده إلى دردشة Vue 3 باستخدام useChat من @ai-sdk/vue.
الدردشة التي تنتظر الجواب كاملاً قبل أن تعرض شيئاً تبدو معطّلة. يحدّق المستخدمون في مؤشر دوران لخمس أو عشر ثوانٍ، ثم يظهر جدار من النص دفعة واحدة. البث يصلح ذلك: يظهر الرد كلمة بعد كلمة، وإذا استدعى النموذج أداة يمكنك إظهار ذلك أيضاً.
يعرف Laravel AI SDK (laravel/ai) مسبقاً كيف يبثّ. تعرض وثائقه المساعد Vercel::chat() الذي يتحدث البروتوكول نفسه الذي يستخدمه useChat في Vercel AI SDK. معظم الأمثلة التي ستجدها على الإنترنت تستخدم إصدار React من useChat، أو Livewire، أو عميلاً مكتوباً يدوياً لـ EventSource. هذا الدرس ينفّذ إصدار Vue من البداية إلى النهاية:
- وكيل Laravel يجيب عن أسئلة زبائن متجر صغير،
- أداة يستدعيها الوكيل للبحث عن طلب في قاعدة البيانات،
- مكوّن Vue 3 يبثّ الرد ويعرض استدعاء الأداة لحظة حدوثه.
كل ما يلي بُني وشُغّل على laravel/ai 1.4.0 مع Laravel 13.42 وPHP 8.4، إلى جانب ai 7.0.173 و@ai-sdk/vue 4.0.173 وVue 3.5. الجانب المكتوب بجافاسكربت من هذه المكتبات يتغيّر بسرعة، لذا راجع الإصدارات المثبّتة لديك إذا لم يطابق شيء ما الشرح.
ما الذي نبنيه
العرض التوضيحي هو دردشة دعم لمتجر تخيّلي. تُدرج ثلاث طلبات: 1001 (تم الشحن)، و1002 (متأخر)، و1003 (مُسترد). عندما يسأل المستخدم «Where is order 1001?»، يستدعي الوكيل أداة LookupOrder، يقرأ النتيجة، ويبثّ جواباً قصيراً.
هناك ثلاثة أجزاء:
SupportAgent، صنف PHP يحتوي على التعليمات وأداة واحدة.
POST /chat، مسار يحوّل طلب useChat إلى استدعاء للوكيل ويبثّ الرد.
SupportChat.vue، مكوّن يستخدم useChat لإرسال الرسائل وعرض الأجزاء المبثوثة.
خارج نطاق هذا المقال: الأدوات التي تحتاج موافقة إنسان (ذلك هو المقال التالي)، وحفظ المحادثات في قاعدة البيانات، وRAG.
تثبيت Laravel AI SDK
ابدأ من تطبيق Laravel جديد واتبع قسم التثبيت في الوثائق:
composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate
خطوة النشر تنشئ config/ai.php وملفات الترحيل لجداول محادثات حزمة SDK. نحن لا نستخدم تلك الجداول في هذا المقال، لكن تشغيل الترحيل الآن يجنّبك مفاجأة لاحقاً.
أضف مفتاح مزوّد إلى .env، مثلاً OPENAI_API_KEY=... أو OPENROUTER_API_KEY=.... المزوّد الافتراضي يُضبط في config/ai.php.
تشغيله من دون مفتاح API
أثناء كتابة هذا أردت أن يعمل العرض على جهاز بلا أي مفتاح، فجعلت المزوّد الافتراضي قابلاً للضبط ووجّهته إلى خادم صغير مكتوب مسبقاً يتحدث تنسيق OpenAI Chat Completions (موجود في المستودع باسم mock-llm/server.mjs). مشغّل openai-compatible في SDK يحتاج إلى url، وللنصوص، إلى نموذج افتراضي:
// config/ai.php
'default' => env('AI_DEFAULT_PROVIDER', 'openai'),
'providers' => [
// ...
'openai-compatible' => [
'driver' => 'openai-compatible',
'url' => env('OPENAI_COMPATIBLE_URL'),
'key' => env('OPENAI_COMPATIBLE_API_KEY'),
'models' => [
'text' => [
'default' => env('OPENAI_COMPATIBLE_MODEL'),
],
],
],
],
AI_DEFAULT_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_URL=http://127.0.0.1:4010/v1
OPENAI_COMPATIBLE_MODEL=mock-model
المحاكي ليس نموذجاً. يتبع بضع قواعد ثابتة (إذا احتوت الرسالة على رقم من أربعة أرقام، استدعِ LookupOrder). وجوده فقط كي يمكن اختبار HTTP والبث والواجهة فعلاً. استبدله بمزوّد حقيقي عندما تريد أجوبة حقيقية.
البيانات
جدول الطلبات صغير عن قصد:
Schema::create('orders', function (Blueprint $table) {
$table->id();
$table->string('number')->unique();
$table->string('customer_name');
$table->string('status'); // shipped, delayed, delivered, refunded
$table->date('eta')->nullable();
$table->unsignedInteger('total_cents');
$table->timestamp('refunded_at')->nullable();
$table->timestamps();
});
ينشئ OrderSeeder الطلبات الثلاثة. نموذج Order يحوّل eta إلى تاريخ. لا شيء عن AI SDK حتى الآن.
إنشاء الوكيل
php artisan make:agent SupportAgent
الصنف المُولَّد ينفّذ Agent وConversational وHasTools، مع دالة messages() فارغة. سنمرّر سجل الدردشة من المتصفح عبر withMessages()، وSDK لا يسمح بالجمع بينهما: استدعاء withMessages() على وكيل Conversational يرمي LogicException («Ad-hoc message history may not be combined with a conversational agent.»). لذا أزل Conversational ودالة messages():
<?php
namespace App\Ai\Agents;
use App\Ai\Tools\LookupOrder;
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Stringable;
#[MaxSteps(5)]
class SupportAgent implements Agent, HasTools
{
use Promptable;
public function instructions(): Stringable|string
{
return <<<'TEXT'
You are the support assistant for a small online shop.
Use the LookupOrder tool whenever the customer mentions an order number.
Never guess an order status or delivery date: if the tool finds nothing, say so.
Keep answers short and friendly.
TEXT;
}
public function tools(): iterable
{
return [
new LookupOrder,
];
}
}
#[MaxSteps(5)] يحدّ عدد الذهاب والإياب إلى النموذج في الجولة الواحدة. استدعاء أداة يكلف خطوتين على الأقل (الاستدعاء ثم الجواب)، لذا خمسة تترك هامشاً دون أن تترك نموذجاً مرتبكاً يدخل حلقة لا تنتهي.
إنشاء الأداة
php artisan make:tool LookupOrder
للأداة ثلاث دوال: وصف يقرأه النموذج، ومخطط JSON لوسائطها، وhandle():
<?php
namespace App\Ai\Tools;
use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;
class LookupOrder implements Tool
{
public function description(): Stringable|string
{
return 'Look up a customer order by its order number and return its status and estimated delivery date.';
}
public function handle(Request $request): Stringable|string
{
$validated = $request->validate([
'order_number' => 'required|string|digits:4',
]);
$order = Order::firstWhere('number', $validated['order_number']);
if (! $order) {
return "No order found with number {$validated['order_number']}.";
}
return json_encode([
'number' => $order->number,
'status' => $order->status,
'eta' => $order->eta?->toDateString(),
]);
}
public function schema(JsonSchema $schema): array
{
return [
'order_number' => $schema->string()
->description('The four-digit order number, without the # sign.')
->required(),
];
}
}
هناك تفصيلان مهمان هنا.
أولاً، المخطط يقيّد ما يرسله النموذج، لكنه ليس تحققاً. $request->validate() هو التحقق. عندما يفشل التحقق، يعيد SDK رسائل التحقق إلى النموذج كنتيجة للأداة حتى يتمكن من تصحيح نفسه (Validating Tool Arguments).
ثانياً، اسم الأداة. ما لم تعرّف دالة name()، يستخدم SDK الاسم الأساسي للصنف، فيرى النموذج دالة اسمها LookupOrder. يصل هذا الاسم أيضاً إلى المتصفح كنوع الجزء tool-LookupOrder، وسنستخدمه في قالب Vue.
مسار الدردشة
هذا هو الجزء الذي تغطيه الوثائق تحت Frontend Integration:
<?php
namespace App\Http\Controllers;
use App\Ai\Agents\SupportAgent;
use Illuminate\Http\Request;
use Laravel\Ai\Vercel\Vercel;
class ChatController extends Controller
{
public function store(Request $request)
{
$request->validate([
'messages' => ['required', 'array', 'max:50'],
]);
$chat = Vercel::chat($request);
return (new SupportAgent)
->withMessages($chat->history())
->stream($chat)
->usingProtocol($chat->protocol());
}
}
// routes/web.php
Route::post('/chat', [ChatController::class, 'store'])
->middleware('throttle:ai');
// app/Providers/AppServiceProvider.php, in boot()
RateLimiter::for('ai', function (Request $request) {
return Limit::perMinute(30)->by($request->user()?->id ?: $request->ip());
});
إليك ما تفعله كل سطر، بناءً على قراءة Laravel\Ai\Vercel\Chat في الحزمة:
Vercel::chat($request) يقرأ مصفوفة messages التي يرسلها useChat.
$chat->history() يحوّل كل رسالة قبل أحدث رسالة للمستخدم إلى كائنات Message الخاصة بـ SDK، بما في ذلك استدعاءات الأدوات السابقة ونتائجها.
- تمرير
$chat نفسه إلى stream() يجعل الوكيل يستخدم أحدث رسالة للمستخدم كمطالبة. (لاحقاً، عندما تحتاج الأدوات إلى موافقة، يحمل الكائن نفسه قرارات المستخدم.)
$chat->protocol() يعيد بروتوكول بيانات Vercel، بحيث تكون الاستجابة تياراً يستطيع useChat تحليله.
throttle:ai هو مُحدِّد معدّل بالاسم عرّفته في AppServiceProvider، حتى تتشارك كل المسارات التي تستدعي نموذجاً ميزانية واحدة لكل مستخدم أو عنوان IP. مع throttle:20,1 العادي على عدة مسارات، يربط Laravel الحد بالمستخدم المسجّل أو بعنوان IP، لا بالمسار، فتنتهي المسارات إلى عدّاد واحد مشترك. فاجأني ذلك أثناء الاختبار.
إذا نفّذت curl على هذا المسار، يمكنك رؤية ما يستقبله المتصفح. نسخة مختصرة:
data: {"type":"start","messageId":"01a1deba-..."}
data: {"type":"start-step"}
data: {"type":"tool-input-available","toolCallId":"call_1","toolName":"LookupOrder","input":{"order_number":"1001"}}
data: {"type":"tool-output-available","toolCallId":"call_1","output":"{\"number\":\"1001\",\"status\":\"shipped\",\"eta\":\"2026-11-17\"}"}
data: {"type":"finish-step"}
data: {"type":"start-step"}
data: {"type":"text-delta","id":"01a1deba-...","delta":"Order "}
data: {"type":"text-delta","id":"01a1deba-...","delta":"#1001 "}
...
data: {"type":"finish","finishReason":"stop","messageMetadata":{"usage":{...}}}
data: [DONE]
تحمل الاستجابة أيضاً الرأسين x-vercel-ai-ui-message-stream: v1 وX-Accel-Buffering: no. الثاني يطلب من Nginx ألا يخزّن التيار في المخزن المؤقت.
مكوّن Vue
ثبّت حزم العميل:
npm install vue ai @ai-sdk/vue
npm install -D @vitejs/plugin-vue
في الإصدار 4 من @ai-sdk/vue، useChat هو composable يعيد مراجع (messages وstatus وerror) إضافة إلى دوال مثل sendMessage وstop. صنف Chat الأقدم ما زال مُصدَّراً لكنه مُعلَم بأنه مهجور. يُضبط نقطة النهاية عبر ناقل:
<script setup>
import { ref, computed } from 'vue';
import { useChat } from '@ai-sdk/vue';
import { DefaultChatTransport } from 'ai';
const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content ?? '';
const { messages, status, error, sendMessage, stop } = useChat({
transport: new DefaultChatTransport({
api: '/chat',
headers: { 'X-CSRF-TOKEN': csrfToken },
}),
});
const input = ref('');
const busy = computed(() => status.value === 'submitted' || status.value === 'streaming');
function submit() {
const text = input.value.trim();
if (!text || busy.value) return;
sendMessage({ text });
input.value = '';
}
</script>
لأن /chat مسار web، ينطبق وسيط CSRF الخاص بلارافيل. قالب Blade يطبع <meta name="csrf-token" content="{{ csrf_token() }}"> والناقل يرسله كـ X-CSRF-TOKEN في كل طلب.
status يمرّ عبر submitted (أُرسل الطلب ولم يُستلم شيء بعد)، ثم streaming، ثم ready، أو error. هذا يكفي لإظهار تلميح «Thinking…» واستبدال زر Send بزر Stop:
<template>
<main class="mx-auto max-w-xl p-6">
<ul class="space-y-3">
<li v-for="message in messages" :key="message.id"
:class="message.role === 'user' ? 'text-right' : 'text-left'">
<template v-for="(part, index) in message.parts" :key="index">
<p v-if="part.type === 'text'" class="inline-block whitespace-pre-wrap rounded-lg bg-white px-3 py-2 shadow-sm">
{{ part.text }}
</p>
<div v-else-if="part.type === 'tool-LookupOrder'" class="my-1 rounded border border-dashed px-3 py-2 text-sm text-gray-600">
<span v-if="part.state === 'output-available'">Checked order #{{ part.input.order_number }}</span>
<span v-else-if="part.state === 'output-error'">Lookup failed: {{ part.errorText }}</span>
<span v-else>Looking up order…</span>
</div>
</template>
</li>
</ul>
<p v-if="status === 'submitted'" class="mt-3 text-sm text-gray-500">Thinking…</p>
<p v-if="error" class="mt-3 text-sm text-red-600">Something went wrong. Please try again.</p>
<form class="mt-4 flex gap-2" @submit.prevent="submit">
<input v-model="input" class="flex-1 rounded border px-3 py-2" placeholder="Where is order 1001?" :disabled="busy" />
<button v-if="busy" type="button" class="rounded border px-3" @click="stop">Stop</button>
<button v-else type="submit" class="rounded bg-black px-3 text-white">Send</button>
</form>
</main>
</template>
لكل رسالة مصفوفة parts، وليس سلسلة content واحدة. تبدو الجولة التي تتضمن استدعاء أداة هكذا بعد انتهائها (سجّلتها من التطبيق قيد التشغيل): step-start، ثم tool-LookupOrder بالحالة output-available، ثم step-start آخر، ثم جزء text. عرض الأجزاء بدلاً من سلسلة مسطّحة هو ما يسمح بإظهار «Checked order #1001» بين سؤال المستخدم والجواب.
تجاهل أجزاء step-start ما لم ترد فواصل بصرية بين الخطوات.
محادثات متعددة الجولات
useChat يرسل النص الكامل في كل طلب. في السؤال الثاني («And order 9999?»)، يحتوي الطلب على أربع رسائل، وVercel::chat()->history() يحوّل الثلاث الأولى إلى سياق، بما في ذلك استدعاء الأداة السابق ونتيجته. في تشغيلي، كان الجواب الثاني «No order found with number 9999.»، وقد جاء مباشرة من فرع «غير موجود» في الأداة.
هذا بسيط وبلا حالة، وهو مناسب لأداة للقراءة فقط. لكن تذكّر أن السجل يأتي من المتصفح، لذا يمكن للمستخدم تعديله. لا تدع هذا السجل يقرر أبداً ما إذا كان مسموحاً بحدوث شيء حسّاس. في المقال التالي، تحتاج أداة RefundOrder إلى موافقة إنسان، وأبيّن لماذا يتطلّب ذلك تخزين المحادثة على الخادم.
كيف تحققت من أنه يعمل
لم أرغب في نشر شيفرة كنت قد قرأتها فقط، لذا يتضمّن العرض ثلاث طبقات من الفحص:
- اختبار Pest يزيّف الوكيل ويتحقق من جسم الاستجابة المبثوث.
SupportAgent::fake() يقبل قائمة من الردود. في شيفرة المصدر للإصدار 1.4.0، تقبل البوابة المزيّفة أيضاً كائنات Laravel\Ai\Responses\Data\ToolCall، ما يجعل الحلقة تشغّل أداة LookupOrder الحقيقية مقابل قاعدة بيانات الاختبار. هذا غير مذكور في الوثائق، فاعتبره تفصيل تنفيذ:
SupportAgent::fake([
new ToolCall('call_1', 'LookupOrder', ['order_number' => '1001']),
'Order #1001 has shipped.',
])->preventStrayPrompts();
$body = $this->postJson('/chat', ['messages' => [
['id' => 'u1', 'role' => 'user', 'parts' => [['type' => 'text', 'text' => 'Where is order 1001?']]],
]])->assertOk()->streamedContent();
expect($body)
->toContain('"toolName":"LookupOrder"')
->toContain('\"status\":\"shipped\"')
->toContain('"type":"text-delta"');
- سكريبت Node يشغّل composable
useChat الحقيقي (يعمل خارج مكوّن) مقابل php artisan serve والمزوّد المحاكي.
- اختبار Vitest يركب
SupportChat.vue في happy-dom، يكتب سؤالاً، يرسل النموذج، يرى زر Stop أثناء بث النص، ثم يتحقق من الجواب النهائي ومن سطر «Checked order #1001».
يذهب المقال الخامس في هذه السلسلة أبعد في اختبار الوكلاء باستخدام Pest.
ملاحظات للإنتاج
أمور يسهل إغفالها:
- التخزين المؤقت. يضبط SDK القيمة
X-Accel-Buffering: no، لكن شبكة CDN أو موازن أحمال قد يحبس الاستجابة حتى انتهائها. إذا وصلت الرموز دفعة واحدة في الإنتاج بينما تُبث محلياً، ابدأ بالبحث هناك.
- الأخطاء تصل إلى المتصفح. عندما يعيد المزوّد خطأ في منتصف التيار، احتوى جزء بروتوكول Vercel الذي رأيته رسالة المزوّد في
errorText. يعرض مكوّني رسالة عامة بدلاً من طباعتها.
- المصادقة. مسار العرض عندي عام ومحدود المعدّل فقط، لإبقاء الدرس قصيراً. ينبغي لتطبيق حقيقي أن يضعه خلف
auth (جلسة أو Sanctum).
- لا استجابة خام. الاستجابات المبثوثة لا تكشف استجابة HTTP الخام من المزوّد، لذا لا تتوفر رؤوس مثل عدّادات حد المعدّل على هذا المسار (Raw HTTP Responses).
- المفاتيح تبقى على الخادم. المتصفح لا يحدّث إلا مسار Laravel الخاص بك.
الخاتمة
كمية الشيفرة صغيرة: صنف وكيل واحد، وأداة واحدة، ودالة متحكّم من ثلاثة أسطر، ومكوّن Vue. معظم العمل هو فهم ما يتحرك عبر السلك. Vercel::chat() يقرأ ما يرسله useChat، وusingProtocol() يكتب ما يتوقعه في المقابل، وقالبك يعرض parts.
يشمل العرض المرفق المزوّد المحاكي واختبار Pest واختبار Vitest. التالي: إضافة أداة RefundOrder تتوقف حتى ينقر إنسان على Approve، وخطأ الأمان الذي كدت أرتكبه أثناء بنائها.