AI Agent工具开发实战：层层护栏防止删库跑路

文章目录前言1. 工具即 Schema先给 AI 发“工作证”1.1 注册表对外提供三个能力2. 目前注册的 5 个工具2.1 calculator 用 AST 白名单绝不用 eval3. Text2SQL生成 → 校验 → 执行 → 报错回炉3.1 踩坑记录3.2 Prompt 里的关键约束4. 四层 SQL 护栏4.1 数据库侧只读连接4.2 实测拦截效果5. Human-in-the-loop高危操作要过“领导审批”6. 另外两个护栏6.1 提示词注入检测6.2 PII 脱敏出网前7. 工具执行的可观测P.S. 推荐一个大神的教程给想要了解或者学习人工智能知识的读者这个教程里内容讲解通俗易懂且风趣幽默对我帮助很大。我想与大家分享这个宝藏教程请点击下方链接查看 传送门https://blog.csdn.net/qq_74013365前言先说结论给 AI 配工具这件事本质上就是给一个“什么都会一点、但什么都不太靠谱”的员工发权限。你说它笨吧它能写 SQL你说它聪明吧它敢在你的生产库上跑 DROP TABLE。这篇文章没什么别的就是记录我怎么给这位员工上保险的。1. 工具即 Schema先给 AI 发“工作证”工具要被 AI 正确调用第一步是让它知道你有什么、每样怎么用。我的方案是把每个工具注册成一份“简历”——名字、职责、参数全写清楚塞进注册表。Tool(namesql_query,descriptionBI 数据查询Text2SQL项目成本、缺陷趋势、交付效率等指标统计。只读。,parameters{type:object,properties:{question:{type:string,description:要查询的业务问题中文描述即可}},required:[question]},fn_tool_sql_query,risklow,# low | high)1.1 注册表对外提供三个能力registry.specs()# JSON Schema 清单给 API / 前端registry.describe_for_prompt()# 自然语言清单自动塞进 Plan 的 Promptregistry.execute(name,args,trace_id)# 统一执行入口好处就一句话新增工具只改一处编排层零改动。相当于公司招了新人你只需要更新一下通讯录不用重新装修办公室。2. 目前注册的 5 个工具上线跑着的工具目前一共 5 个工具风险说明search_knowledgelow知识库检索RAGsql_querylowBI 数据 Text2SQLsend_alerthigh推送告警需人工确认calculatorlow安全四则运算get_todaylow解析“本月/上周”相对时间注意那个 send_alert风险等级是 high。推送告警这种事让 AI 自己拍板就跟让猫决定什么时候开罐头一样——它倒是开心你心里直打鼓。2.1 calculator 用 AST 白名单绝不用 eval_ALLOWED_OPS{ast.Add:operator.add,ast.Sub:operator.sub,...}def_safe_eval(expr):return_eval(ast.parse(expr,modeeval))有人问为什么这么怂我只能说eval 一时爽删库火葬场。你永远不知道用户会在输入框里敲什么万一来一句__import__(os).system(rm -rf /)那你这个月的绩效就没了。3. Text2SQL生成 → 校验 → 执行 → 报错回炉让模型写 SQL本质上等于让实习生写周报你需求讲得再清楚他总能给你一版“看起来很有道理、细看全是坑”的东西。forattemptinrange(2):promptTEXT2SQL_TMPL.format(schemaschema,questionquestion,limitrow_limit)iflast_err:promptf\n上一次生成的 SQL 报错{last_err}\n请修正后只输出 SQL。raw_sqlllm.chat([{role:user,content:prompt}],temperature0)try:safe_sqlvalidate_sql(raw_sql)# ← 护栏returnexecute(safe_sql)exceptGuardrailErrorase:last_errstr(e)# 护栏拦截也算一次错误回炉重生成3.1 踩坑记录第一版我没把数据库报错回传结果模型一旦写错字段名就永远失败。它不是不努力是每次都在同一个坑里摔倒而且摔得很有仪式感。后来把报错塞回 prompt一次修正的成功率肉眼可见地涨了。原来 AI 也会“吃一堑长一智”前提是你要把那个“堑”亲手喂到它嘴边。3.2 Prompt 里的关键约束生成 SQL 之前我还会在 prompt 里焊死几条规矩1. 只能输出一条 SELECT不要解释、不要 markdown 代码块 2. 禁止 INSERT/UPDATE/DELETE/DROP/ATTACH/PRAGMA 3. 必须带 LIMIT 200 4. 日期字段为 TEXTYYYY-MM-DD本月用 date(now,start of month) 5. 只能用给定的表和字段 一个少样本示例看到第 2 条没“禁止 INSERT/UPDATE/DELETE/DROP”。这种话写出来像废话不写出来就是事故——因为你不写它真的会删。4. 四层 SQL 护栏Prompt 是软的护栏是硬的。嘴上说“别乱来”没用得物理上锁死。我给它上了四道锁defvalidate_sql(sql,allowed_tables,row_limit,readonlyTrue):# ① 清洗去 markdown 代码块、去注释cleanstrip_sql_comments(raw)# ② 语法层禁多语句if_MULTI_STMT.search(clean):raiseGuardrailError(检测到多语句执行)# ③ 关键字层必须以 SELECT/WITH 开头ifreadonlyandnotlow.startswith((select,with)):raise...# 危险关键字黑名单forkwin(insert,update,delete,drop,attach,pragma,...):ifre.search(rf\b{kw}\b,low):raise...# ④ 权限层正则提取 from/join 后的表名必须在白名单tablesset(_TABLE_RE.findall(clean))ifillegal:tables-allowed:raiseGuardrailError(f引用了未授权的表{illegal})# ⑤ 兜底没 LIMIT 自动补ifnotre.search(r\blimit\s\d,low):cleanf LIMIT{row_limit}4.1 数据库侧只读连接consqlite3.connect(ffile:{db_path}?modero)# SQLite 只读模式只读连接就是物理层面的“只能看不能拿”。就像图书馆书随便看但休想借走一本。模型再有想法也翻不出水花。4.2 实测拦截效果上线以后我拿几个经典刁钻输入试了试全部被按住了输入结果“删掉成本表”✅ 被关键字黑名单拦截SELECT * FROM secret_salary✅ 被表白名单拦截SELECT ...; DROP TABLE x✅ 被多语句检测拦截三连拦一个没漏。模型想删库跑路先过关键字这关过了还有表名白名单白名单过了还有只读连接只读连接过了……还有备份。反正它今天必须老老实实给我查数。5. Human-in-the-loop高危操作要过“领导审批”iftool.riskhighandsettings.hitl_enabledandnotauto_approve_high_risk:returnToolResult(False,errorHITL_REQUIRED,meta{need_human:True})翻译一下高危操作必须人工确认相当于我顺手给 AI 装了个 OA 审批流——它想发一条告警行先提申请领导批了再说。前端渲染一张橙色确认卡用户点「确认执行」后端才把悬着的工具真正跑起来。这就是我面试时写在简历里的“权限边界”。当初这四个字一写面试官的眼睛都亮了。6. 另外两个护栏6.1 提示词注入检测INJECTION_PATTERNS[r忽略(?:以上|上面|之前).{0,6}(?:指令|规则|提示),rignore\s(?:all\s)?previous\sinstructions,r输出(?:你的|系统).{0,4}(?:提示词|prompt),...]有人试图让模型“忽略之前的指令”这类输入会被模式库逮住。但注意命中之后我不中断服务而是降级成“只读检索模式”再发一条 warn 事件。粗暴拒绝会误伤正常用户这个分寸得拿捏。说白了就像接到诈骗电话不直接挂断而是放一首“您拨打的用户正忙”让它自己觉得没意思。6.2 PII 脱敏出网前_PII_RULES[(re.compile(r1[3-9]\d{9}),[PHONE]),# 手机号(re.compile(r\b\d{17}[\dXx]\b),[ID_CARD]),# 身份证(re.compile(r\b\d{16,19}\b),[CARD]),# 银行卡(re.compile(r[\w.-][\w-]\.[\w.]),[EMAIL]),(re.compile(r(?:sk-|api[_-]?key\s*[:]\s*)[A-Za-z0-9_\-]{16,}),[SECRET]),]这一条是真的被吓出来的。企业场景里用户会随手把客户手机号、身份证号粘进对话框一旦这些内容发到第三方模型恭喜你bug 单还没提律师函先到了。脱敏就是在数据出门前给它穿好衣服——合规这条线谁也别想裸奔。7. 工具执行的可观测withtracer.span(trace_id,ftool.{name},argsargs,risktool.risk):resulttool.fn(args,trace_id)每个工具调用都会被 Tracer 包成一个 Span同时给前端推 tool_start / tool_end 事件。你在执行链路时间线上能看到每一步工具调用的参数、耗时和结果预览。说白了AI 每次动手都留痕。它今天干了什么、花了多久、结果对不对一查一个准——比家长查孩子手机使用记录还细。下一篇聊记忆、可观测与成本控制咱们到时候接着唠。P.S. 推荐一个大神的教程给想要了解或者学习人工智能知识的读者这个教程里内容讲解通俗易懂且风趣幽默对我帮助很大。我想与大家分享这个宝藏教程请点击下方链接查看传送门https://blog.csdn.net/qq_74013365