前端 Agent 编排中的工具调用拦截器：实现人机协同的确认机制

前端 Agent 编排中的工具调用拦截器：实现人机协同的确认机制

在把大模型 Agent 接入真实业务系统时，最让安全团队和业务方担心的就是“Agent 失控”——比如 Agent 自作主张地调用了转账接口、删除了线上数据表，或者向客户群发了未经审核的营销短信。

如果完全不给 Agent 工具调用权限，Agent 就退化成了只能聊天的普通问答机器人；如果把所有权限无条件开放给 Agent 全自动执行，又面临巨大的不可控风险。

解决这一矛盾的核心工程架构是：前端工具调用拦截器（Tool Invocation Interceptor）与人机在环协同（Human-in-the-Loop, HITL）。通过在前端与 Agent 运行时之间构建拦截插槽，对于高危或涉及金钱/敏感数据的动作，挂起（Suspend）模型执行流程，弹出交互卡片由人类用户二次确认或修改参数后，再继续后续的执行链路。

工具风险分级与拦截状态机

我们将 Agent 可调用的工具按照破坏性划分为三个等级：

1. L1 只读无害工具（Auto-Pass）：查询天气、搜索文档、读取只读配置等，由 Agent 全自动静默调用；
2. L2 读写轻量工具（User Notification）：创建草稿、添加收藏、发送测试日志等，自动执行但需在前端界面明确提示；
3. L3 高危敏感工具（User Confirmation Required）：发起支付扣款、删除生产资源、修改权限配置等，必须强制拦截并挂起执行。

[Agent 规划出 Tool Call: "transferMoney"] │ ▼ [前端 Interceptor 识别为 L3 风险工具] ──> (挂起 Agent 执行管道) │ ▼ [前端 UI 渲染受控授权确认卡片: "是否向账户 X 转账 ¥5000?"] │ ├─ 用户点击【拒绝】──> 向 Agent 回传: { status: "rejected", reason: "User cancelled" } └─ 用户点击【确认】──> 真实发起请求，并将成功结果喂回 Agent 继续推理

核心实现：可挂起的前端工具调用拦截器

借助 TypeScript 和 Promise 的挂起机制，我们实现一个完全受控的拦截器引擎：

export type ToolRiskLevel = 'L1' | 'L2' | 'L3'; export interface ToolActionPayload { callId: string; toolName: string; riskLevel: ToolRiskLevel; parameters: Record<string, any>; } export interface InterceptorDecision { action: 'proceed' | 'reject' | 'modify'; modifiedParams?: Record<string, any>; rejectReason?: string; } export class AgentToolInterceptor { private pendingResolvers = new Map<string, (decision: InterceptorDecision) => void>(); private onPromptUserCallback?: (payload: ToolActionPayload) => void; public registerUserPromptHandler(callback: (payload: ToolActionPayload) => void) { this.onPromptUserCallback = callback; } // 当 Agent 引擎尝试调用工具时触发此拦截钩子 public async intercept(toolName: string, riskLevel: ToolRiskLevel, params: Record<string, any>): Promise<any> { const callId = crypto.randomUUID(); // 如果是 L1 级低风险工具，直接放行 if (riskLevel === 'L1') { return { status: 'proceed', finalParams: params }; } // L3 级高风险工具：挂起当前执行流，向前端 UI 发出确认事件 return new Promise<any>((resolve) => { this.pendingResolvers.set(callId, (decision) => { if (decision.action === 'reject') { resolve({ status: 'cancelled', error: decision.rejectReason || 'Operation was rejected by user.', }); } else if (decision.action === 'modify') { resolve({ status: 'proceed', finalParams: decision.modifiedParams || params, }); } else { resolve({ status: 'proceed', finalParams: params, }); } }); // 通知前端 UI 弹出确认弹窗 if (this.onPromptUserCallback) { this.onPromptUserCallback({ callId, toolName, riskLevel, parameters: params, }); } }); } // 前端用户点击按钮后触发的反馈方法 public resolveUserAction(callId: string, decision: InterceptorDecision) { const resolver = this.pendingResolvers.get(callId); if (resolver) { resolver(decision); this.pendingResolvers.delete(callId); } } }

在 React UI 中的受控确认卡片渲染

结合 React Hook，将拦截器事件转化为清晰的用户确认浮层：

import React, { useState, useEffect } from 'react'; import type { AgentToolInterceptor, ToolActionPayload } from './interceptor'; export const AgentHumanConfirmationSlot: React.FC<{ interceptor: AgentToolInterceptor }> = ({ interceptor, }) => { const [currentRequest, setCurrentRequest] = useState<ToolActionPayload | null>(null); useEffect(() => { interceptor.registerUserPromptHandler((payload) => { setCurrentRequest(payload); }); }, [interceptor]); if (!currentRequest) return null; const handleConfirm = () => { interceptor.resolveUserAction(currentRequest.callId, { action: 'proceed' }); setCurrentRequest(null); }; const handleReject = () => { interceptor.resolveUserAction(currentRequest.callId, { action: 'reject', rejectReason: '用户在界面主动终止了操作', }); setCurrentRequest(null); }; return ( <div className="my-3 p-4 bg-amber-50 border border-amber-300 rounded-xl shadow-sm"> <div className="flex items-center gap-2 text-amber-900 font-semibold text-sm"> <span>⚠ 高危操作确认请求</span> <span className="px-2 py-0.5 text-xs bg-amber-200 text-amber-800 rounded"> {currentRequest.toolName} </span> </div> <p className="text-xs text-amber-700 mt-1"> Agent 申请执行敏感操作，请核实以下调用参数： </p> <pre className="mt-2 p-2 bg-white rounded border border-amber-200 text-xs font-mono overflow-x-auto text-gray-800"> {JSON.stringify(currentRequest.parameters, null, 2)} </pre> <div className="mt-3 flex gap-2 justify-end"> <button onClick={handleReject} className="px-3 py-1.5 text-xs font-medium bg-white text-gray-700 border border-gray-300 rounded hover:bg-gray-50" > 拒绝授权 </button> <button onClick={handleConfirm} className="px-3 py-1.5 text-xs font-medium bg-amber-600 text-white rounded hover:bg-amber-700" > 确认执行 </button> </div> </div> ); };

工程落地收益

1. 构筑安全信任底线：业务方与风控团队无需再担心大模型由于幻觉乱调接口，所有高危动作均有清晰的人工审批留痕。
2. 支持参数在线修正：当 Agent 生成的 SQL 查询条件或转账金额有轻微瑕疵时，用户可以在前端直接修改参数后放行，避免推倒重来，大幅提升协同效率。
3. 完美融入大模型多轮会话：通过拦截器返回的标准状态，模型能够准确理解“用户拒绝了此项操作”并根据反馈调整下一步规划（例如：“检测到您取消了该操作，请问是否需要换一种方式处理？”）。