Laravel AI SDK: Human-in-the-Loop Tool Approval | Mohamed Said [Skip to content](#main) [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://www.msaied.com/public) - [Home](https://www.msaied.com/public) - [Projects](https://www.msaied.com/public/projects) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [About](https://www.msaied.com/public#about) [ Contact](https://www.msaied.com/public#contact) Menu Menu ---- Close - [HomeStart here](https://www.msaied.com/public) - [ProjectsCase studies](https://www.msaied.com/public/projects) - [ArticlesEngineering notes](https://www.msaied.com/public/articles) - [CertificatesCredentials](https://www.msaied.com/public/certificates) - [AboutHow I work](https://www.msaied.com/public#about) - [ContactGet in touch](https://www.msaied.com/public#contact) [Start a conversation](https://www.msaied.com/public#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 1. [Home](https://www.msaied.com/public) 2. / 3. [Articles](https://www.msaied.com/public/articles) 4. / 5. [Laravel](https://www.msaied.com/public/articles?category=laravel) 6. / 7. Laravel AI SDK Adds Human-in-the-Loop Tool Approval [Laravel](https://www.msaied.com/public/articles?category=laravel) [AI](https://www.msaied.com/public/articles?category=ai) Laravel AI SDK Adds Human-in-the-Loop Tool Approval ==================================================== Laravel AI SDK v0.10.0 introduces a human-in-the-loop (HITL) API that lets agents pause before executing sensitive tools, requiring a human to approve, reject, or edit arguments before the agent proceeds. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com/public#person) Published 30 Jul 2026 · Updated 31 Jul 2026 · 3 min read ShareCopy linkCopied ![Laravel AI SDK Adds Human-in-the-Loop Tool Approval](https://cdn.msaied.com/490/5b325ae6bad97a0aa3ab3648b55e994e.png) On this page +1. [Laravel AI SDK v0.10.0 Brings Human-in-the-Loop Control to Agents](#laravel-ai-sdk-v0100-brings-human-in-the-loop-control-to-agents) 2. [Marking a Tool as Approvable](#marking-a-tool-as-approvable) 3. [Handling Pending Approvals](#handling-pending-approvals) 4. [Key Details to Know Before Upgrading](#key-details-to-know-before-upgrading) 5. [Breaking Changes in v0.10.0](#breaking-changes-in-v0100) 6. [Takeaways](#takeaways) Laravel AI SDK v0.10.0 Brings Human-in-the-Loop Control to Agents ----------------------------------------------------------------- Announced at Laracon US 2026 in Boston and shipped on July 21, [Laravel AI SDK v0.10.0](https://github.com/laravel/ai/releases/tag/v0.10.0) introduces a **human-in-the-loop (HITL) API** for AI agents. Before this release, an agent that started executing tools ran straight through to completion with no way to intervene. That is acceptable for read-only operations, but it is a serious concern when a tool can delete a file, issue a refund, or send an email to a customer. The new API lets you intercept specific tool calls, pause the agent, and require a human decision — approve, reject, or modify the arguments — before execution resumes. Marking a Tool as Approvable ---------------------------- Approval is opt-in per tool. Implement the `Approvable` contract and add the `InteractsWithApprovals` trait: ```php 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}."; } } ``` When blanket approval is too broad, define a `needsApproval` method that inspects the incoming arguments and returns a boolean or an `Approval` instance with a reason: ```php use Laravel\Ai\Approvals\Approval; protected function needsApproval(Request $request): Approval|bool { return $request['amount'] forUser($user) ->prompt('Refund the damaged headphones on order 4192.'); if ($response->hasPendingApprovals()) { foreach ($response->pendingApprovals as $approval) { // $approval->id, ->tool, ->arguments, ->reason } } ``` To resume, continue the conversation and pass a `Decisions` instance keyed by tool call ID: ```php 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('Outside the return window.'), ])); ``` Every pending call must receive a decision, or an `ApprovalMismatchException` is thrown. Use `approveRemaining()` or `rejectRemaining()` to set a bulk default for any calls not explicitly addressed. Key Details to Know Before Upgrading ------------------------------------ - The agent must implement `Conversational` with persisted history (via `RemembersConversations`) — there is nothing to resume otherwise. - HITL works with `prompt`, `stream`, `queue`, `broadcast`, `broadcastNow`, and `broadcastOnQueue`. - During streaming, a pause arrives as a `tool_approval_request` event; queued agents dispatch a `ToolApprovalRequested` event. - Pauses are **per call, not per step** — tools in the same step that do not require approval run immediately. Keep side effects idempotent using `$request->toolCallId()`. - If generation fails after an approval result has already been stored, resume with a plain text prompt rather than resubmitting decisions. ### Breaking Changes in v0.10.0 - A new nullable `approval_state` column is added to the conversation messages table. - Custom `ConversationStore` implementations must add a `storeApprovalResults()` method. Takeaways --------- - Approval is opt-in per tool via the `Approvable` contract and `InteractsWithApprovals` trait. - `needsApproval()` lets you apply conditional logic based on tool arguments. - Pending approvals are surfaced on the response and resumed via a `Decisions` instance. - Streaming, broadcasting, and queued agents all support the HITL pause/resume flow. - Upgrading requires a migration for the new `approval_state` column and a `storeApprovalResults()` method on custom stores. Full documentation is available in the [Laravel AI SDK docs](https://laravel.com/docs/13.x/ai-sdk#human-tool-approval). Source: [Laravel News](https://laravel-news.com/laravel-ai-sdk-adds-human-in-the-loop-tool-approval) - [Laravel AI SDK](https://www.msaied.com/public/articles?search=Laravel%20AI%20SDK) - [HITL](https://www.msaied.com/public/articles?search=HITL) - [AI Agents](https://www.msaied.com/public/articles?search=AI%20Agents) - [Laracon US 2026](https://www.msaied.com/public/articles?search=Laracon%20US%202026) - [Tool Approval](https://www.msaied.com/public/articles?search=Tool%20Approval) Frequently asked questions --------------------------- Does every tool call require human approval when using the HITL API?No. Approval is opt-in per tool. You can make approval unconditional, apply conditional logic via a `needsApproval()` method that inspects the arguments, or override the requirement at the agent level with `withoutApproval()` and `requireApproval()`. What happens if I do not provide a decision for every pending tool call?An `ApprovalMismatchException` is thrown. You must supply a decision for every pending call, or use `approveRemaining()` / `rejectRemaining()` to set a default for any calls not explicitly addressed. What are the breaking changes when upgrading to Laravel AI SDK v0.10.0?Two breaking changes: a new nullable `approval\_state` column is added to the conversation messages table (requiring a migration), and any custom `ConversationStore` implementation must add a `storeApprovalResults()` method. ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author ---------------- [Mohamed Said](https://www.msaied.com/public#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. [About](https://www.msaied.com/public#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) [Previous articleCPX 2.0: The Composer Package Executor for PHP](https://www.msaied.com/public/articles/cpx-20-the-composer-package-executor-for-php-1) [Next articleLaravel Octane + FrankenPHP: Persistent Services, Boot-Once Singletons, and Safe State](https://www.msaied.com/public/articles/laravel-octane-frankenphp-persistent-services-boot-once-singletons-and-safe-state) On this page ------------- 1. [Laravel AI SDK v0.10.0 Brings Human-in-the-Loop Control to Agents](#laravel-ai-sdk-v0100-brings-human-in-the-loop-control-to-agents) 2. [Marking a Tool as Approvable](#marking-a-tool-as-approvable) 3. [Handling Pending Approvals](#handling-pending-approvals) 4. [Key Details to Know Before Upgrading](#key-details-to-know-before-upgrading) 5. [Breaking Changes in v0.10.0](#breaking-changes-in-v0100) 6. [Takeaways](#takeaways) ### Have a technical challenge? Tell me what you’re building. I reply within two working days. [Start a conversation](https://www.msaied.com/public#contact) Related articles ----------------- [ ![](https://cdn.msaied.com/740/cce86edc21eddcbdd2f2454fadaf9c70.png) · 3 min read### The Pipeline Pattern in Laravel: Custom Pipelines Beyond Middleware 5 Oct 2026 ](https://www.msaied.com/public/articles/the-pipeline-pattern-in-laravel-custom-pipelines-beyond-middleware-1) [ ![](https://cdn.msaied.com/739/2d6897fdcdcf090613f96f72a64b8a78.png) · 4 min read### MySQL Full-Text Search in Laravel: Indexes, Relevance Scoring, and Boolean Mode 4 Oct 2026 ](https://www.msaied.com/public/articles/mysql-full-text-search-in-laravel-indexes-relevance-scoring-and-boolean-mode) [ ![](https://cdn.msaied.com/738/073696a3fefe18bec825beec5ac658f5.png) · 4 min read### Laravel Queue Rate-Limited Middleware: Throttling Jobs Without Losing Work 4 Oct 2026 ](https://www.msaied.com/public/articles/laravel-queue-rate-limited-middleware-throttling-jobs-without-losing-work) Have a technical challenge? ---------------------------- Tell me what you’re building. I reply within two working days. [Discuss your project ↗](https://www.msaied.com/public#contact) © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. - [Home](https://www.msaied.com/public) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [GitHub](https://github.com/EG-Mohamed) - [LinkedIn](https://www.linkedin.com/in/msaiedm/) - [WhatsApp](https://wa.me/201094619204) - [Email Address](mailto:hello@msaied.com) - [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) - [Sitemap](https://www.msaied.com/public/sitemap.xml)