【AI Agent通识九课】03 · AI 的菜单 vs 暗号 — 工具怎么设计

AI Agent 通识课 · 第 3 篇 / 共 9 篇一句话记住把工具做成菜单不靠暗号。去年我用某个 Agent 产品时遇到一件糟心事我让它给张总发个邮件改下周会时间。它给张总的同事发了邮件。怎么出的错Agent 内部把张总识别成了错误的联系人又因为工具协议太松散这个错误没有在任何一环被拦住——直接发了出去。这就是今天要讲的主题AI 怎么用工具决定了它会不会闯祸。业界有个专有名词叫工具幻觉Tool Hallucination——AI 调错工具、传错参数、甚至伪造不存在的工具。搞不清这件事你做的 Agent 永远不靠谱。01 · 一个生活化的对比路边摊靠吼点餐像松散的工具协议你喊“来个鸡腿饭多放辣”老板听成“鸡翅饭微辣。”自然语言歧义、信息丢失、错了也没人拦。肯德基点餐机像结构化工具协议屏幕上清清楚楚原味鸡 / 辣翅 / 薯条每个按钮点下去弹出参数份数1/2/3、辣度不辣/中辣/变态辣封闭菜单、参数固定想点孜然羊肉根本没这个按钮。航空公司值机系统像强类型协议你选座位 “88A”——系统报错“座位号不存在”你选商务舱但票是经济舱——系统报错“票型不符”连错都不让你提。AI 调用工具也一样。越结构化越可靠。02 · 如果让你来做你会怎么设计假设你在做一个个人助理 Agent有 4 个工具查日程看日历上有什么会发消息发邮件 / 短信下单买东西搜信息查资料你怎么让 AI 知道这 4 个工具的存在朴素方案 A在 Prompt 里用自然语言描述你有以下工具 1. 查日程查看日历 2. 发消息发邮件或短信 3. 下单网购 4. 搜信息搜索然后指望 AI 输出[调用查日程(下周)]你再解析。问题一堆AI 可能输出[调用查询日程]名字变了可能输出[调用查日程 下周]括号没了甚至输出[调用删除日程(下周)]根本不存在的工具这就是路边摊靠吼。朴素方案 B让 AI 直接写代码让 AI 输出 Python 代码 code send_email(zhangcompany.com, 改时间) 然后 exec(code)更糟AI 可能写open(日程.txt).read()绕过你的工具直接访问系统可能写os.system(rm -rf /)灾难可能写发消息()忘了传参正确方向像点餐机那样关键思路别让 AI 自由发挥给它封闭菜单。屏幕只有 4 个按钮查日程 / 发消息 / 下单 / 搜信息每个按钮的参数都是下拉选不能乱填想点孜然羊肉按钮都没有03 · 四种主流工具协议方案 A字符串式最松散做法工具就是一个字符串名字 自然语言描述。tools[{name:查日程,description:查日历},{name:发消息,description:发邮件或短信},{name:下单,description:购物下单},{name:搜信息,description:搜索},]AI 看描述决定调哪个输出字符串查日程(下周)你再解析。生活类比路边摊靠吼——听得懂算运气好谁在用LangChain 早期版本、大量 Demo、研究项目优点灵活、快速搭建缺点AI 可能拼错工具名、参数靠 AI 猜、工具幻觉率高适合原型、Demo、学习方案 BJSON Schema最主流做法用 JSON Schema 严格定义工具的名字、参数、类型。{name:send_message,description:给指定联系人发消息,parameters:{type:object,properties:{to:{type:string,description:收件人邮箱或手机号},channel:{type:string,enum:[email,sms]},content:{type:string,description:消息内容}},required:[to,channel,content]}}生活类比肯德基点餐机——菜单固定、参数下拉选、不合法的组合不让你提谁在用ChatGPT 插件 / GPTsFunction Calling 是原生路径绝大多数商用 Agent跨模型兼容MCP 协议Anthropic 推的开放协议底层也是 JSON Schema优点✅ 参数有 JSON Schema 强校验发消息必须有收件人✅ OpenAI / Anthropic 原生优化幻觉率低✅ 业界标准跨模型通用缺点❌ JSON 字符串易写错❌ 没有编译期检查运行时才发现问题适合绝大多数商用 Agent2026 年事实标准方案 C装饰器式开发体验最好做法用语言特性Python 装饰器自动生成 Schema。tooldefsend_message(to:str,channel:Literal[email,sms],content:str)-None:给指定联系人发消息 Args: to: 收件人邮箱或手机号 channel: 渠道email 或 sms content: 消息内容 # 具体发送逻辑生活类比自助点餐 Pad——菜单自动同步后厨改菜品不用手动更新两边谁在用LangChaintoolPython 生态最主流Hermes Agent开源框架首选LlamaIndex / Pydantic AI同类做法优点✅ 代码即文档工具和 Schema 永远同步✅ 开发体验极好✅ 类型注解复用 Python 原生能力缺点❌ Python 的类型注解是软约束运行时才检查❌ 装饰器魔法对新手不友好❌ 不跨语言适合Python 生态的 Agent 项目方案 D强类型枚举式最硬核做法用静态类型语言Rust / Kotlin / Swift的枚举 强类型结构体。enumAgentAction{CheckCalendar(CheckCalendarParams),SendMessage(SendMessageParams),PlaceOrder(PlaceOrderParams),Search(SearchParams),}structSendMessageParams{to:String,channel:Channel,// enum Channel { Email, Sms }content:String,}生活类比航空公司值机系统——座位选错、票型不符连错都不让你提谁在用WarpRust 枚举部分企业级 AgentGo / Kotlin / Swift 强类型实现高可靠性场景金融、医疗、生产级 DevOps优点✅编译期就能堵死所有错误✅ 枚举是封闭集合AI 只能从有限变体里选✅ 穷举性检查加新工具所有漏处理的地方编译期报错✅ 极高可靠性缺点❌ 语言学习曲线陡❌ 加工具要改枚举不如装饰器灵活适合生产级、对可靠性要求极高的 Agent速查表方案生活类比代表类型检查可靠性开发效率字符串式路边摊靠吼LangChain 早期无 中 高JSON Schema肯德基点餐机OpenAI / Claude / MCP运行时 高 高装饰器式自助点餐 PadLangChaintool/ Hermes运行时 高 极高强类型枚举航空值机系统Warp编译期 极高 中04 · 加个新工具试试假设要加一个新工具删除邮件四种方案各要改哪里字符串式tools.append({name:删除邮件,description:删除指定邮件})完事。但 AI 下次可能调 “删邮件” / “delete_email” / “移除邮件”——运行时才崩。JSON Schema{name:delete_email,parameters:{properties:{email_id:{type:string}},required:[email_id]}}运行时验证参数。但如果 schema 本身写错了少个逗号部署前发现不了。装饰器式tooldefdelete_email(email_id:str)-None:删除指定邮件...自动生成 Schema类型检查运行时——AI 传了个int进来真跑才报错。强类型枚举enumAgentAction{// ... 原有变体DeleteEmail(DeleteEmailParams),// 新增}编译期全部检查。加了新变体所有处理AgentAction的地方执行器、日志、确认弹窗都会报没处理 DeleteEmail 分支——编译器替你做 code review。一张表看差异检查点字符串式JSON Schema装饰器式强类型枚举工具名拼错运行时运行时运行时编译期参数类型错不查运行时运行时编译期少处理新工具不查不查不查编译期Schema 本身错无 schema部署时编译期编译期工具幻觉高低低极低05 · 手把手一次工具调用的全链路场景你对助理说把下周三和张总的会改到周四下午 3 点。阶段 1用户输入 ┌──────────────────────────────────┐ │ 把下周三和张总的会改到周四下午3点 │ └─────────────┬────────────────────┘ │ ▼ 阶段 2LLM 理解意图生成工具调用 ┌──────────────────────────────────┐ │ LLM 输出: │ │ { │ │ tool: update_calendar, │ │ arguments: { │ │ event_id: meeting_20260508,│ │ new_time: 2026-05-09 15:00│ │ } │ │ } │ └─────────────┬────────────────────┘ │ ▼ 阶段 3Agent 框架反序列化 类型校验 ┌──────────────────────────────────┐ │ ✅ 工具存在 update_calendar ✓ │ │ ✅ 参数合法 event_id ✓ │ │ ✅ 时间格式 ISO 8601 ✓ │ │ ❌ 任何一项失败就拒绝 │ └─────────────┬────────────────────┘ │ ▼ 阶段 4风险检查下篇主题 ┌──────────────────────────────────┐ │ 查日程 → 安全直接跑 │ │ 改日程 → 要不要先问主人 │ │ 删日程 → 必须问主人 │ └─────────────┬────────────────────┘ │ ▼ 阶段 5Executor 执行 ┌──────────────────────────────────┐ │ 调日历 APImove event to 周四 │ │ → 返回成功 │ └─────────────┬────────────────────┘ │ ▼ 阶段 6结果回给 LLMObservation ┌──────────────────────────────────┐ │ LLM 看到结果 → 准备回复改好了 │ └──────────────────────────────────┘不同协议的区别主要在阶段 3字符串式几乎没校验“可能成功可能崩”JSON Schema校验合法性“参数不对拒绝”装饰器式类型注解校验“类型不对拒绝”强类型枚举编译期已经保证了“根本不会走到这一步出错”06 · 怎么选一个决策树你要做 Agent 吗 ├─ 快速 Demo / 学习 │ └─ 字符串式LangChain 起步 ├─ 正式商用最常见路径 │ ├─ 要跨多个 LLM │ │ └─ JSON SchemaFunction Calling / MCP │ │ │ └─ 只用 OpenAI / Python 栈 │ ├─ 想要最好开发体验 │ │ └─ 装饰器式LangChain tool / Pydantic AI │ │ │ └─ 要 OpenAI 原生优化 │ └─ Function CallingJSON Schema └─ 生产级 / 对可靠性要求极高 ├─ 团队有静态类型语言能力 │ └─ 强类型枚举Rust / Kotlin │ └─ 只有 Python 栈 └─ 装饰器式 严格 Pydantic 校验90% 的团队选 JSON Schema 或装饰器式。只有Agent 要干重要的事、出错损失惨重的场景如替企业管家、金融交易、生产级 DevOps才值得上强类型枚举。07 · 我踩过的坑做过几个 Agent 项目工具协议这块栽过的跟头总结 3 条坑 1自然语言描述写太模糊早期我给工具写 description 时图省事“发消息给指定的人发消息。”AI 经常调错——分不清邮件还是短信、不知道哪个字段是收件人。改进description 要写精确的参数含义 使用场景举例。“向指定联系人发送消息。channel 参数控制渠道email 或 sms紧急事务用 sms正式通知用 email。”效果立刻好一倍。坑 2工具太多AI 记不住我曾经给一个 Agent 塞了 40 多个工具想着给全了才能干所有事。结果 AI 开始乱调——相似功能的工具选错、参数混淆。后来缩减到 20 个核心工具AI 幻觉率降到 1/5。教训工具数量和 AI 可靠性是反比关系。宁少勿多。坑 3没给失败工具的处理路径工具调用失败时很多 Agent 框架直接把 stack trace 扔给 LLM。LLM 看到 Python 异常信息经常会懵。改进失败结果要封装成人话再喂回 LLM。# 差returnfError:{traceback.format_exc()}# 好return发送失败收件人邮箱不存在。请确认邮箱地址或使用手机号重试。AI 就知道怎么自我纠正了。08 · 你能带走什么读完这篇你应该能回答的 3 个问题✅工具协议的本质把工具做成封闭菜单点餐机而不是路边摊靠吼✅四种主流方案及适用场景字符串式Demo路边摊JSON Schema商用主流肯德基点餐机装饰器式Python 生态首选自助 Pad强类型枚举生产级高可靠航空值机✅工具幻觉的根源协议越松散AI 越容易发明不存在的工具下次评估 Agent 产品时问 4 个问题它的工具是封闭集合还是开放字符串参数校验发生在编译期、运行时还是没有工具会不会被 AI幻觉调用加新工具的成本有多高产品经理设计 AI 功能时不要只用自然语言描述工具给 AI 结构化的 Schema工具数量宁少勿多20-30 个够用多了 AI 也记不住工具要一把钥匙一把锁不要搞万能工具让 AI 随便填参数重要工具必须有参数校验发消息至少要校验收件人存在开发者自己搭 Agent 时起步用LangChaintool装饰器5 分钟能跑进阶切OpenAI Function Calling原生优化最好生产级考虑MCP 协议跨 LLM 兼容极高可靠性场景才上 Rust 枚举09 · 下一篇预告04 · AI 的双车道 — 安全怎么保AI 能调工具了下一个问题来了——让 AI 查日程很安全但让 AI “发消息给老板”、“转账”、删邮件呢机场安检模型普通行李直接过危险品单独开箱。对比 AutoGPT 全自动 / Cursor 每次 Accept / Claude Code allowlist / Warp 两级风险标签——告诉你不同场景该把点头门槛放多高。一句话记忆锚点把工具做成菜单不靠暗号。像肯德基点餐机不像路边摊靠吼——菜单越封闭AI 越可靠。路易乔布斯 © 2026 | AI Agent 通识课 · 第 3 篇 / 共 9 篇