‏تأیید انسانی در Laravel AI SDK

تو لاراکان US 2026 تیم لاراول از یه API «انسان در حلقه» (HITL) برای Laravel AI SDK خبر داد. تو بلاگ لاراول اومده که تا قبل از این، ایجنت روی حالت خودکار کار می‌کرد و همین که شروع به اجرای ابزارها می‌کرد، دیگه راهی برای دخالت نبود. این قابلیت تو PR شمارهٔ ۷۷۳ مخزن laravel/ai لند شده و ۲۱ جولای با نسخهٔ v0.10.0 بیرون اومده.

فرقش اونجا معلوم می‌شه که ابزار فقط داده نمی‌خونه؛ ابزاری که فایل پاک می‌کنه، پول برمی‌گردونه یا به مشتری ایمیل می‌زنه. حالا کافیه ابزار قرارداد Approvable رو پیاده کنه و از تِرِیت InteractsWithApprovals استفاده کنه تا پیش‌فرض نیاز به تأیید داشته باشه. اگه پرسیدن همیشگی زیادی خشک باشه، متد needsApproval می‌تونه بر اساس آرگومان‌ها تصمیم بگیره:

protected function needsApproval(Request $request): Approval|bool
{
    return $request['amount'] <= 2000
        ? false
        : Approval::required('Refunds over $20 need a manager.');
}

وقتی مدل یه ابزار تأییدی رو صدا می‌زنه، ایجنت اجراش نمی‌کنه و درخواست‌های معلق رو با شناسهٔ فراخوانی، نام ابزار، آرگومان‌ها و دلیلش برمی‌گردونه. برای ادامه، مکالمه رو continue می‌کنی و یه نمونهٔ Decisions که با شناسهٔ هر فراخوانی کلید خورده بهش می‌دی:

$response = (new SupportAgent)
    ->continue($conversationId, as: $user)
    ->prompt(Decisions::from([
        'call_abc' => Decision::approve(),
        'call_ghi' => Decision::reject('This order is outside the return window.'),
    ]));

هر فراخوانی معلق حتماً باید یه تصمیم بگیره، وگرنه ApprovalMismatchException می‌گیری؛ approveRemaining() و rejectRemaining() هم برای بقیه یه پیش‌فرض می‌ذارن. ردکردنی که یه متن نتیجه همراهش باشه به مدل برمی‌گرده تا جواب بده، ولی ردکردن خالی همون‌جا حلقهٔ تولید رو تموم می‌کنه.

نویسنده چندتا نکتهٔ ریز رو هم یادآوری می‌کنه: ایجنت باید Conversational باشه و تاریخچه‌ش ذخیره شه، وگرنه چیزی برای ادامه‌دادن نیست. مکث هم به‌ازای هر فراخوانیه نه هر گام، پس بهتره اثرهای جانبی رو با $request->toolCallId() تکرارپذیر (idempotent) نگه داری. آپگرید به 0.10 دوتا تغییر شکننده داره: ستون nullable جدید approval_state و متد storeApprovalResults() که پیاده‌سازی‌های سفارشی ConversationStore باید داشته باشنش.

نکات کلیدی:

• API انسان در حلقه تو نسخهٔ v0.10.0 لاراول AI SDK منتشر شده
• تأیید per-tool فعال می‌شه: قرارداد Approvable + تِرِیت InteractsWithApprovals
• needsApproval بر اساس آرگومان‌ها تصمیم می‌گیره؛ withoutApproval() و requireApproval() هم موقع ثبت ابزار قابل override هستن
• تصمیم‌ها با Decisions و شناسهٔ فراخوانی برمی‌گردن؛ نبود تصمیم یعنی ApprovalMismatchException
• پشتیبانی از prompt، stream، queue و برادکست؛ تو استریم رویداد tool_approval_request می‌گیری