Laravel AI SDK Adds Human-in-the-Loop Tool Approval

At Laracon US 2026 in Boston, the Laravel team announced a human-in-the-loop (HITL) API for the Laravel AI SDK. Agents can now pause before executing a tool and wait for a person to approve it, reject it, or edit its arguments. The feature landed in laravel/ai#773 and shipped in v0.10.0 on July 21.

Before this, once an agent started calling tools, it ran to completion on its own. That's fine when the tools only read data. It's a harder sell for a tool that deletes a file, refunds a payment, or emails a customer. From the Laravel blog:

Until now, an AI agent built with the Laravel AI SDK ran on autopilot: once it started executing tools, there was no way to step in. The new human-in-the-loop (HITL) API lets you intercept specific agent actions and require a decision before the agent proceeds, so you can approve, deny, or modify what happens next instead of finding out after the fact.

#Marking a Tool as Approvable

Approval is opt-in per tool. Implement the Approvable contract, use the InteractsWithApprovals trait, and the tool requires approval by default:

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}.";
    }
 
    // ...
}

Asking every time is often too blunt. To decide based on the arguments, define a needsApproval method that returns a boolean or an Approval instance carrying a reason:

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.');
}

You can also override the requirement where the agent registers its tools, using withoutApproval() and requireApproval():

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

#Approving, Rejecting, or Editing a Call

When the model calls an approvable tool, the agent stops short of running it and hands the pending calls back on the response. Each one carries the tool call ID, the tool name, the arguments, and the reason:

$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
    }
}

To resume, continue the conversation and pass a Decisions instance keyed by tool call 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.'),
    ]));

The booleans true and false work as shorthand for approve and reject. Every pending call requires a decision, or you get an ApprovalMismatchException, which also covers unknown IDs and calls that have already been resolved. If you don't want to enumerate all of them, approveRemaining() and rejectRemaining() set a default for the rest:

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

A rejection that includes a result string goes back to the model so it can keep responding. A rejection with no result records the rejection and stops the generation loop there.

#Details Worth Knowing

• The agent has to be Conversational with its history persisted; otherwise, there is nothing to resume the paused call from. The RemembersConversations trait handles that.
• Approval is supported by prompt, stream, queue, broadcast, broadcastNow, and broadcastOnQueue.
• During streaming and broadcasting, a pause arrives as a tool_approval_request event. With the Vercel AI SDK stream protocol, approvals are emitted using that protocol's native tool approval parts.
• Queued agents pass the response to the then callback and dispatch a ToolApprovalRequested event.
• Pauses are per call, not per step. Tools in the same step that don't require approval run immediately, so keep external side effects idempotent using $request->toolCallId().
• Laravel records an approved tool's result before it asks the model to continue. If generation fails after that point, the approval is already spent, so resume with an ordinary text prompt instead of resubmitting the decisions.

Upgrading to 0.10 brings a couple of breaking changes: a new nullable approval_state column on the conversation messages table and a storeApprovalResults() method that custom ConversationStore implementations must provide.

If you're adding an approval step to an agent you already have, the documentation includes a full flow: a pair of routes that accept either a new message or a set of decisions from a chat screen. The rest of the Laracon US announcements are on the Laravel blog, and the code lives in the laravel/ai repository.