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

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

Навіщо потрібен Human-in-the-Loop

До цього моменту, коли агент починав викликати інструменти, він працював до завершення самостійно. Це прийнятно, коли інструменти лише читають дані. Але це значно ризикованіше для інструмента, який видаляє файл, повертає платіж або надсилає листа клієнту. Як зазначено у блозі Laravel:

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

Як позначити інструмент для підтвердження

Підтвердження активується окремо для кожного інструмента. Реалізуйте контракт 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, який повертає булеве значення або екземпляр 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 працюють як скорочення для схвалення та відхилення. Кожен очікуваний виклик вимагає рішення, інакше ви отримаєте ApprovalMismatchException, що також охоплює невідомі ID та виклики, які вже були вирішені. Якщо ви не хочете перелічувати всі з них, методи approveRemaining() та rejectRemaining() встановлюють значення за замовчуванням для решти:

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

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

Важливі деталі реалізації

• Агент має бути Conversational з збереженою історією; інакше немає з чого відновити призупинений виклик. Трейт RemembersConversations це обробляє.
• Підтвердження підтримується методами prompt, stream, queue, broadcast, broadcastNow та broadcastOnQueue.
• Під час потокової передачі та broadcasting пауза надходить як подія tool_approval_request. З протоколом потоку Vercel AI SDK підтвердження випромінюються, використовуючи власні частини схвалення інструментів цього протоколу.
• Агенти в черзі передають відповідь до callback then і відправляють подію ToolApprovalRequested.
• Паузи відбуваються для кожного виклику, а не для кожного кроку. Інструменти на одному кроці, які не вимагають підтвердження, виконуються негайно, тому тримайте зовнішні побічні ефекти ідемпотентними, використовуючи $request->toolCallId().
• Laravel записує результат схваленого інструмента перед тим, як попросити модель продовжити. Якщо генерація не вдається після цього моменту, підтвердження вже використане, тому відновіть роботу зі звичайним текстовим запитом замість повторного надсилання рішень.

Оновлення та breaking changes

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

Якщо ви додаєте крок підтвердження до агента, який у вас вже є, документація включає повний flow: пару маршрутів, які приймають або нове повідомлення, або набір рішень з екрана чату. Решта анонсів Laracon US доступна в блозі Laravel, а код знаходиться у репозиторії laravel/ai.