Laravel AI SDK додав функцію Human-in-the-Loop для ручного підтвердження дій інструментів

На конференції Laracon US 2026 у Бостоні команда Laravel анонсувала API human-in-the-loop (HITL) для Laravel AI SDK. Тепер агенти можуть ставити виконання інструментів на паузу та чекати, поки людина схвалить дію, відхилить її або відредагує аргументи. Функціонал з'явився у laravel/ai#773 і став доступним у версії v0.10.0 від 21 липня.

Раніше AI-агент працював у режимі «автопілота»: після запуску він виконував усі завдання до кінця. Це прийнятно для читання даних, але ризиковано, коли йдеться про видалення файлів, повернення коштів чи надсилання імейлів клієнтам. З блогу Laravel:

Досі AI-агенти, побудовані на Laravel AI SDK, працювали автономно. Новий HITL API дозволяє перехоплювати конкретні дії та вимагати рішення користувача, перш ніж агент продовжить роботу. Ви можете схвалити, заблокувати або змінити подальші дії замість того, щоб дізнаватися про результат постфактум.

# Маркування інструмента для підтвердження

Підтвердження активується для кожного інструмента окремо. Для цього імплементуйте контракт Approvable та використайте трейт InteractsWithApprovals — після цього інструмент потребуватиме схвалення за замовчуванням:

use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;
 
class IssueRefund implements Approvable, Tool
{
    use InteractsWithApprovals;
 
    public function handle(Request $request): Stringable|string
    {
        $order = Order::findOrFail($request['order_id']);
 
        $order->refund($request['amount']);
 
        return "Refunded {$request['amount']} on order {$order->id}.";
    }
 
    // ...
}

Щоб не запитувати підтвердження щоразу, можна додати логіку в метод needsApproval. Він має повертати boolean або екземпляр Approval із зазначенням причини:

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

Вимогу підтвердження можна також перевизначити під час реєстрації інструментів агентом за допомогою методів withoutApproval() та requireApproval():

public function tools(): iterable
{
    return [
        (new LookUpOrder)->withoutApproval(),
        (new IssueRefund)->requireApproval('Every refund gets reviewed.'),
    ];
}

# Схвалення, відхилення або редагування виклику

Коли модель звертається до інструмента, що потребує підтвердження, агент зупиняється і повертає очікувані виклики у відповіді. Кожен запит містить ID виклику, назву інструмента, аргументи та причину:

$response = (new SupportAgent)
    ->forUser($user)
    ->prompt('Refund the damaged headphones on order 4192.');
 
if ($response->hasPendingApprovals()) {
    foreach ($response->pendingApprovals as $approval) {
        // $approval->id
        // $approval->tool
        // $approval->arguments
        // $approval->reason
    }
}

Щоб продовжити виконання, передайте об'єкт Decisions, де ключами є ID викликів:

use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\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.'),
    ]));

Для простоти можна використовувати true та false. Якщо ви не хочете обробляти кожен виклик вручну, методи approveRemaining() або rejectRemaining() дозволяють встановити рішення для всіх залишків:

$decisions = Decisions::from([
    'call_abc' => true,
])->rejectRemaining('Not approved.');

Якщо відхилення містить текст результату, він передається назад моделі для формування відповіді. Відхилення без результату просто фіксує відмову та зупиняє цикл генерації.

# Важливі деталі

• Агент має бути Conversational із увімкненим збереженням історії (трейт RemembersConversations), інакше він не зможе продовжити роботу після паузи.
• Підтвердження підтримується методами prompt, stream, queue, broadcast, broadcastNow та broadcastOnQueue.
• Під час стрімінгу пауза приходить як подія tool_approval_request.
• У чергах (queued agents) відповідь передається в then-колбек, а також ініціюється подія ToolApprovalRequested.
• Пауза спрацьовує на рівні виклику, а не кроку. Інструменти, що не потребують схвалення, виконуються миттєво в тому ж кроці.
• Laravel фіксує результат схваленого інструмента перед продовженням. Якщо після цього генерація перерветься, підтвердження вважається використаним — відновлюйте роботу звичайним текстовим промптом.

Оновлення до версії 0.10 вносить зміни в базу даних: додано nullable-колонку approval_state у таблицю повідомлень та метод storeApprovalResults() для кастомних реалізацій ConversationStore.

Детальні приклади налаштування маршрутів для обробки рішень доступні в документації. Інші анонси з Laracon US можна знайти у блозі Laravel, а вихідний код — у репозиторії laravel/ai.