AI 动手之前先让人拍板：Laravel AI 工具审批机制完整指南

在 Laravel AI 中，Agent 可以像调用函数一样调用各种工具（Tools）——读文件、发请求、删数据。但如果某个操作有风险呢？Laravel AI 内置了工具审批（Approval）机制：Agent 在真正执行工具之前先"暂停"，等待人类拍板，你可以选择批准、拒绝，甚至直接修改参数再放行。这套机制让你既享受 AI Agent 的自动化效率，又牢牢掌握安全底线，是生产环境上线 AI Agent 时不可或缺的"刹车系统"。

为什么需要工具审批？🛡️

想象一个能调用DeleteFile工具的客服 Agent。用户随口一句"把配置清了"，AI 如果直接执行删除，事故就发生了。工具审批把这种高风险操作拆成两步：

1. 暂停（Pause）：Agent 提出工具调用请求，但不执行，把请求内容（工具名、参数、原因）交给你的应用
2. 决策（Decide）：人类（或你的业务规则）给出决定：approve/reject/edit
3. 恢复（Resume）：Agent 从暂停点继续，被批准的工具才会真正运行

被拒绝的调用不会让对话"卡死"——SDK 会自动向历史里补一条"该调用未被批准、未执行"的结果记录，保证会话可正常回放。相关逻辑位于 src/Gateway/Concerns/HandlesToolApprovals.php#L78-L131。

一键开启：声明哪些工具需要审批

第一步：实现 Approvable 接口

工具类只需实现 Approvable 接口，核心就三个方法：

第二步：使用 InteractsWithApprovals 特性

配套的 InteractsWithApprovals trait 已经写好全部实现，你甚至可以用needsApproval(Request $request)按参数动态判断，比如"删除路径在/tmp下就免审，否则需要审批"。一个完整示例见测试夹具 ApprovableNumberGenerator：

class ApprovableNumberGenerator implements Approvable, Tool { use InteractsWithApprovals; protected function needsApproval(Request $request): Approval|bool { return true; // 每次都要求人工确认 } }

💡 小技巧：requireApproval('会删除生产数据')传入的原因（reason）会随暂停请求一起返回给前端，方便审批人看懂风险。

审批流程全景图：暂停 → 决策 → 恢复

阶段一：Agent 暂停，等待拍板

当 Agent 调用到需要审批的工具时，prompt()返回的AgentResponse不会继续往下跑，而是携带待审批清单暂停下来。你可以通过三个信号识别它：

• $response->hasPendingApprovals()返回true
• $response->pendingApprovals是一个 PendingApproval 集合，每项包含id、工具名tool、参数arguments和reason
• 系统同时触发 ToolApprovalRequested 事件，事件里带有conversationId，可直接推给审批人

暂停时，工具调用（tool_use）已被写入会话历史（数据库表agent_conversation_messages的steps字段），这是后续能"断点续跑"的关键。

阶段二：人类给出决策 Decision

SDK 提供了 Decision 类来表达三种动作：

Decision::approve() // 批准，原样执行 Decision::reject('理由') // 拒绝，并把理由作为结果告诉 AI Decision::edit(['path' => '/tmp/file']) // 修改参数后再批准

决策以"工具调用 ID => 决策"的映射形式打包成 Decisions 对象，并且支持布尔简写和通配符：

Decisions::from([ 'toolu_1' => true, // 简写：批准 'toolu_2' => Decision::reject('太危险了'), // 拒绝 '*' => false, // 其余调用默认拒绝 ]);

⚠️ 注意两条规则：决策映射不能为空；通配符'*'只能用于批准/拒绝，不能用于edit（无法替每个未知调用编参数）。

阶段三：带着决策恢复 Agent

prompt()、stream()等入口的第一个参数除了字符串提示词，也接受一个Decisions对象（见 Agent 接口）。恢复的方式就是"继续同一会话 + 提交决策"：

$paused = (new MyAgent)->forUser($user)->prompt('删除 config/app.php'); if ($paused->hasPendingApprovals()) { // ... 人工审批通过后 ... $result = (new MyAgent) ->continue($paused->conversationId, $user) ->prompt(Decisions::from(['toolu_1' => true])); }

恢复后 Agent 会：执行被批准的工具 → 把"批准/拒绝"结果回填进对话 → 继续调用模型完成剩余步骤。被拒绝的调用会以denied: true的结果告知模型，模型可以据此换一种方式回答。

进阶玩法：流式审批与多通道恢复

流式输出中的审批事件 🌊

使用stream()时，审批请求会以ToolApprovalRequest流事件的形式推送，类型为tool_approval_request，负载包含完整的approvals清单（见 src/Streaming/Events/ToolApprovalRequest.php#L24-L34）。前端监听到该事件即可弹出审批按钮，审批完再调stream(Decisions::...)恢复——用户全程无感、不断连。

队列与广播同样支持恢复

审批恢复不仅适用于同步调用。queue(Decisions)、broadcast(Decisions, $channel)等入口都能携带决策参数，适用于"审批邮件审批 → 后台队列恢复执行"这类异步场景，行为验证见 tests/Feature/ToolApprovalTest.php#L172-L200。

会话归属与并发保护 🔒

• 恢复时若提交的工具调用 ID 与当前待审批清单对不上（比如并发下重复提交、或会话已被推进），SDK 会抛出ApprovalMismatchException，并以 HTTP 409 返回当前最新待审批清单，方便前端刷新（tests/Feature/ToolApprovalTest.php#L24-L41）
• 实现了ResolvesPendingApprovals的会话存储可以按conversationId主动查询"还差哪些审批"（src/Contracts/ResolvesPendingApprovals.php），适合做审批中心页面
• 恢复执行由continue($conversationId, $user)绑定会话归属，配合forUser()可做权限校验

快速上手清单 ✅

1. 给风险工具实现Approvable接口，用requireApproval('原因')声明审批要求
2. 调用 Agent 后检查$response->hasPendingApprovals()，把pendingApprovals展示给审批人
3. 审批人操作后构建Decisions::from(['工具ID' => true/false/Decision::edit(...)])
4. 用->continue($conversationId, $user)->prompt($decisions)恢复 Agent
5. 监听ToolApprovalRequested/ToolApprovalResolved事件，完善审计日志

掌握以上五步，你就在 Laravel AI 里搭好了一个"人机协作"的 Agent 审批闭环：AI 负责想，人负责拍板。相关核心代码都集中在 src/Approvals/ 目录，配套的完整行为测试在 tests/Feature/ToolApprovalTest.php 和 tests/Feature/ToolApprovalResumeTest.php，阅读它们是理解这套机制最快的路径。