做 AI 应用这一年多我最大的感受是模型本身的能力早就不是瓶颈真正拉开差距的是它“够得着”什么。WorkMate 这个内部助手项目刚起步时我们只给它接了两三个 API结果它就像一个刚入职但双手被绑住的新人脑子转得再快也办不成事。直到我们把“内置工具包”这件事系统化地做起来它才真正从一个聊天框变成能干活的工作流引擎。这篇文章想把我们从设计工具包到落地、再到踩坑修复的全过程复盘一遍重点是工具怎么选、怎么接、怎么防止 AI 把工具用歪适合正在做 AI 智能体或想把大模型接进真实工作流的开发者和产品经理参考。1. 为什么 AI 需要一套“工具箱”1.1 模型能力边界与工具调用的本质大模型本质上是一个“思考者”不是一个“行动者”。它很擅长理解意图、生成文本、归纳信息但它在训练完成后就与世界失去了实时接触。你问它今天库存多少它不知道你让它读一下某个内部系统里的报表它连那个系统在哪都无从得知你让它帮你把一份数据整理成 Excel 发出去它只能生成一段 Python 代码却没法真正执行。工具调用Function Calling / Tool Use就是弥补这个缺口的关键机制模型负责拆解任务、决定调用哪个工具、传什么参数而真正读写数据、发送请求、执行计算的动作由工具完成。可以打一个比方模型是大脑工具是手和眼睛。没有工具的大脑只能纸上谈兵有了工具之后它才能检索资料、动手操作、验证结果。WorkMate 内置工具包要解决的核心问题不是“多接几个 API 那么简单”而是要让模型在一个可控、可观测、可回退的框架里安全地使用这些能力。我们见过很多项目在初期什么工具都接结果模型乱调工具、参数传错、权限失控最后整个系统比没接工具时更不稳定。所以工具包设计的本质是对模型能力边界的一种主动管理——决定它什么时候可以动手、什么时候必须停下来向人确认。1.2 WorkMate 的定位与工具包设计原则WorkMate 在我们团队里的定位是一个内部知识问答与工作流自动化助手。它需要处理的任务包括检索内部文档、汇总多方数据、生成周报、发起审批、定时提醒、把散落在不同系统里的信息拉通。这个定位决定了它的工具包不可能只有一个“搜索文档”的工具而是需要覆盖信息获取、内容生成、代码执行、系统操作等多个层面的“组合工具箱”。我们的工具包设计从一开始就定了三条原则。第一可观测性优先每一次工具调用都要有完整的请求、响应、耗时和 token 消耗记录模型为什么选这个工具、传了什么参数、结果是否被采纳全部可回溯。第二最小权限原则每个工具只暴露完成特定任务所需的最小接口能力绝不放开任意命令执行或整库读写。第三渐进式接入一个工具要先在小范围任务里验证稳定再放开到全员使用而不是一次性把所有接口全堆上去。这三条原则后来被证明非常关键尤其是当模型调用链越变越长的时候没有清晰的调用记录出了问题根本无从查起。2. 工具包的核心组成与选型解析2.1 六大类工具的功能拆解WorkMate 内置工具包目前包含六大类工具每一类都对应一类高频需求。我把它们整理成一张表方便对照理解工具类别典型能力解决的核心问题常见使用场景知识检索内部文档、问答库、历史记录的语义搜索让模型获得“组织记忆”员工问制度、查项目背景公开信息获取网页正文抓取、RSS 订阅解析弥补模型知识的时效性缺口查行业动态、竞品信息文档解析与生成PDF/Word/Excel 读写、格式转换打通非结构化数据的进出通道提取合同关键字段、生成报表代码执行在隔离沙箱中运行 Python 脚本让模型能做计算、能处理数据数据分析、文件批处理、格式转换数据查询内部数据库的只读查询接口让模型访问实时业务数据查库存、查订单、统计指标系统操作与通知发送消息、创建日程、发起审批流让模型能“办成事”而不只是“说建议”自动发周报、建会议、提醒跟进以知识检索为例它和普通关键词搜索最大的区别是向量化召回文档被切分成片段后转成向量用户提问时再把问题向量化做相似度匹配最后把最相关的几段文本拼进模型的上下文。这个过程让模型可以“基于证据回答”而不是凭记忆瞎编。而系统操作与通知类工具则承担了从“建议”到“执行”的跨越比如 WorkMate 可以在数据查询工具拿到周数据后调用文档生成工具产出报告再调用消息工具发到指定群整条链路跑完只需要一次对话指令。2.2 关键工具的选型对比与取舍选型是工具包建设里最容易纠结的环节我挑两个典型的例子说说我们是怎么取舍的。第一个是代码执行工具。我们试过两种方案一种是在服务端直接起一个 Python 子进程跑模型生成的代码另一种是丢进容器化的隔离沙箱里执行。第一种胜在简单几行代码就能跑通延迟也低但我们很快发现风险不可控——模型生成的代码偶尔会出现死循环、意外删除文件、访问内网端口等行为一旦在宿主机上出问题代价是难以承受的。最终我们选择了隔离沙箱方案虽然每次执行多花几百毫秒还要额外维护镜像和资源限额但换来的是可以放心让模型自由生成代码。对实际业务来说这个安全性溢价非常值得。第二个是数据查询工具。团队里一开始有两种声音一种是直接给模型数据库连接串让它写 SQL另一种是封装好只读查询接口模型只能按参数查。第一种看起来很灵活但真实场景里模型写 SQL 容易把大表全扫一遍或者误用敏感字段。我们最终选择的是“受限 SQL”模型生成 SQL 后先经过一个规则层做只读校验、超时限制、行数限制再发给数据库执行。用户请求“查上个月华东区销售额”模型生成的是一条带过滤条件的聚合 SQL规则层自动加上 LIMIT 和超时熔断既保留灵活性又控制住了风险。3. 实操过程与核心环节实现3.1 给 WorkMate 注册第一个工具从定义到生效我们以“查询部门成员日程”这个工具为例完整走一遍注册流程它一共涉及三步定义工具描述与参数 Schema、实现具体的回调函数、把工具挂载到 WorkMate 的运行配置里。第一步是定义工具描述。这一步比大多数人想象的重要得多。模型的工具选择能力很大程度上取决于描述写得清不清楚。我们当时的 JSON Schema 大致长这样{ name: query_member_schedule, description: 查询某位成员在指定时间范围内的日程安排返回日程标题、时间、地点和参与人。适合用于会议预约、周报汇总、日程协调等场景。, parameters: { type: object, properties: { member_name: { type: string, description: 要查询的成员姓名必须是组织架构内的中文姓名 }, start_date: { type: string, description: 开始日期格式 YYYY-MM-DD }, end_date: { type: string, description: 结束日期格式 YYYY-MM-DD不能早于开始日期 } }, required: [member_name, start_date, end_date] } }第二步是实现回调函数。这个函数接收模型按 Schema 解析出的参数然后去内部的日程服务取数返回给模型一个结构化的结果。我们当时用 Python 实现关键逻辑并不复杂。def query_member_schedule_handler(params: dict) - dict: member params[member_name] start params[start_date] end params[end_date] events schedule_client.fetch(member, start, end) if not events: return {status: empty, message: f{member} 在 {start} 至 {end} 内没有日程安排} return { status: success, events: [ { title: ev.title, start_time: ev.start_time, end_time: ev.end_time, location: ev.location, participants: ev.participants, } for ev in events ], }第三步是把函数注册进工具包配置。我们并没有把工具硬编码在模型请求里而是维护一个工具注册中心每次对话开始时根据用户意图和会话状态动态加载工具列表。这样不会让模型一次面对几十个工具降低选择难度也减少 token 消耗。3.2 编排工具调用链让多个工具协同完成一个任务单个工具能解决的需求很有限真正的价值场景是多工具协同。拿 WorkMate 最常用的“本周项目周报生成并发送”来说它需要串联四个工具数据查询工具读本周任务完成情况文档生成工具把结果写成 Markdown 周报代码执行工具把 Markdown 转成带格式的文档文件最后系统操作工具把文件发到群里。模型在收到指令后会自动规划调用顺序前一步的输出会成为后一步的输入。这里有一个容易踩的坑多步调用场景里模型可能把中间结果“记错”。比如数据查询工具返回了 12 条任务记录模型在下一步调用文档生成工具时把其中两条的状态摘要写错。我们后来采用的办法是不让模型凭记忆传递数据而是在上下文里保留工具返回的原始结果并明确提示模型“直接引用上文查询结果中的数据不要自行修改”。实现上我们用了一个简单的状态容器每一步工具调用的结构化输出都会暂存起来后续工具需要引用时直接按变量名读取。这相当于给模型提供了一张“草稿纸”既减少了模型在长上下文中翻找信息的负担也降低了信息在传递过程中被篡改的概率。实测下来串联任务的准确率比让模型纯靠上下文记忆提升了约四成。3.3 权限与安全边界设计工具包带来的风险往往不是模型“变坏”而是权限边界没划好。WorkMate 的权限设计分为三层。第一层是用户身份层。每个对话都绑定发起人的身份标识工具调用时把这个标识透传给下游系统而不是用统一的机器人账号去操作。这样每一笔数据查询、每一次消息发送都保留了操作者痕迹出了问题能找到责任人。第二层是工具能力层。我们为每个工具定义白名单参数和可执行范围。比如代码执行工具默认禁止网络访问禁止读取敏感目录消息发送工具只允许向预设范围内的群组发消息不允许私聊陌生人数据查询工具只暴露只读接口所有写操作必须走审批工具二次确认。第三层是操作确认层。对于不可逆或影响面大的动作比如发起审批、删除数据、对外发送消息我们要求模型先输出“准备执行的操作说明”由用户在对话里确认后再真正执行。很多 AI 落地项目忽略了这个环节觉得多一步确认很麻烦但实际经验告诉我们这一层恰恰是让业务方敢放开权限的关键。发生过不止一次模型理解用户意图偏差的情况多一道确认就能把这类错误挡在生产事故之外。4. 常见问题与排查技巧实录4.1 工具调用失败的 5 类典型场景工具包运行时间长了各种故障模式都会遇到。我把最常见的五类问题整理成速查表症状根本原因排查思路解决方向模型反复调用同一个工具但不成功工具返回的错误信息太模糊查看工具返回的原始报错是否被截断让工具返回结构化错误码并把错误码含义写入系统提示工具参数总是传错格式Schema 描述缺少格式示例检查模型请求日志中实际传入的参数在参数描述里补充示例值比如日期格式、枚举值范围模型选错工具工具描述之间区分度不够对比两个工具的描述文本是否容易混淆重写描述明确各自的适用场景和不适用场景工具返回内容过大导致上下文溢出响应内容没有做裁剪和汇总检查是否把整表数据都塞给了模型服务端先做字段精简、分页截取或预聚合调用链中途中断某个中间工具超时或异常查看调用链追踪中的耗时分布为每个工具设置独立超时时间增加重试退避策略这里我想重点说说第一个问题。模型在工具调用失败后的行为往往不尽人意它可能会反复用相同参数重试即使错误信息已经说明“参数不合法”。我们的解决办法是工具返回的报错要人性化、可行动化不能只抛{error: 500}而要返回类似“member_name 对应的成员不存在请检查姓名拼写或使用组织成员搜索工具确认后再查询”这样的提示。当模型看到具体原因时它的自我纠错能力会显著提升。4.2 从日志到追踪定位“AI 自作主张”的排查方法有一次我们收到反馈说 WorkMate 在生成周报时连续调用了十几次数据查询工具把某个数据库接口直接打到超时。排查时我们发现模型在拿到第一次查询结果后觉得数据不够“丰富”于是不断微调日期范围反复查询造成接口压力。这类问题光看最终结果很难发现必须依靠完整的调用链日志。我们的追踪方案是给每一次用户请求分配一个 trace_id从用户输入开始到模型每次工具调用的请求、响应、token 消耗再到最终回复全部串联起来。通过可视化界面可以看到原本预期 4 步的调用链膨胀到了 15 步。定位到模型反复查询的意图后我们的解决方案有两个一是在数据查询工具的描述里增加“该工具会返回完整统计结果除非业务要求分段获取否则不建议重复调用”的提示二是在框架层面增加重复调用检测如果同一工具在短时间内以相似参数被调用超过三次系统会强制中断并询问用户“是否需要继续查询”。这类“AI 自作主张”的问题靠模型自律不如靠框架约束来得可靠。4.3 WorkMate 工具包避坑清单最后分享几条我们沉淀下来的避坑经验。第一工具描述里不要用“万能”类词汇。早期我们把一个文档解析工具描述成“可以处理所有格式的文档”结果模型什么文件都往它那里送连图片识别失败后反复重试。后来我们在描述里明确写出“支持 PDF、Word、Excel图片格式请使用图片解析工具”工具选择的准确率立刻提升。第二工具的返回结果最好统一包装成{status: ..., data: ...}的结构别让不同的工具各自返回不同字段名。模型在引用结果时统一的结构可以明显减少字段理解错误。我们刚上线时有些工具返回data有些返回result有几次模型把result里的 JSON 字符串当成嵌套对象处理折腾了很久。第三工具包不是越丰富越好。工具太多模型的选择压力会变大而且工具之间的边界更容易模糊。我们的经验是每次新增工具前先问三个问题——这个功能是否已有工具覆盖模型是否能准确区分它与现有工具的边界接入后是否能解决一个真实的高频需求三个问题有一个不达标就先不上。5. 从工具包到工具箱的迭代心得5.1 工具包管理的日常不是一劳永逸工具包上线只是开始真正的挑战在维护。我们维护的方式分三个层次代码层做版本管理和灰度开关新工具先在“测试空间”里跑一段时间只允许小部分用户调用配置层做定期的工具描述审查因为随着模型版本升级它对描述的理解方式也会变化原本有效的描述可能变得含糊数据层做调用频率和失败率的周度复盘连续两周调用量为零的工具会标记为“待优化”要么重写描述要么直接下线。印象很深的一次优化是在模型升级后开始的。原本表现良好的工具选择在升级后突然频繁出错。排查了好几天才发现新模型对工具描述的语义理解更加“灵活”它会因为两个工具都提到了“数据”就把它们当成可替代项。后来我们的工具描述措辞统一加入了“本工具不适用于……”的反向界定效果立竿见影。这件事之后我们每升级一次模型版本都会跑一轮工具选择的回归测试确认所有既有工具仍然被准确触发。5.2 衡量工具包价值的三个侧面工具包的价值不能只凭“感觉好用”来判断我们日常用三个指标来衡量任务完成率、人为干预率、平均调用链长度。任务完成率指用户发起请求后WorkMate 在不依赖人工介入的情况下完成目标的比例人为干预率指用户发消息打断、纠正或二次确认的频率平均调用链长度则反映了任务复杂度这个数字如果异常增长往往意味着工具分工不合理或模型在低效尝试。这套指标帮助我们做过一个很务实的减法某个财务相关工具原来的调用成功率只有 45%频繁需要人工介入后来我们发现它和查询工具的场景重叠度过高模型经常拿它去查一个数据查询工具更擅长的内容。重新划分边界后该工具的成功率提升到 87%整体人为干预率明显下降。所以工具包建设其实是一个持续做加法和减法的过程加的是能力减的是冗余和混乱。5.3 我个人最想提醒的一点如果只让我说一条经验那就是工具包设计要以“人机协作的流畅度”为中心而不是以“模型能力炫技”为中心。我们最开始的几次迭代总是想给 WorkMate 加更多“看起来厉害”的工具结果反而让用户觉得它变得难以预测。后来我们把重心转回到用户真实的工作流上每次新增工具前都先做需求和路径的梳理用户需要几步操作、希望什么信息出现在什么位置、哪些环节必须有人的确认这些想清楚之后工具包自然就越配越顺手。最后再分享一个小技巧在工具包的每个关键决策点我都会问自己一句——如果模型这次调错工具了最坏的结果是什么这个结果我们能否承受如果不能承受就再加一道防护或确认机制。想明白这个问题的项目工具包大多都能稳健地跑下去。 
长河君 · 2026/10/12 19:48:52 · 阅读 1.2k 大模型工具调用实战：WorkMate内置工具包从设计到落地复盘
做 AI 应用这一年多我最大的感受是模型本身的能力早就不是瓶颈真正拉开差距的是它“够得着”什么。WorkMate 这个内部助手项目刚起步时我们只给它接了两三个 API结果它就像一个刚入职但双手被绑住的新人脑子转得再快也办不成事。直到我们把“内置工具包”这件事系统化地做起来它才真正从一个聊天框变成能干活的工作流引擎。这篇文章想把我们从设计工具包到落地、再到踩坑修复的全过程复盘一遍重点是工具怎么选、怎么接、怎么防止 AI 把工具用歪适合正在做 AI 智能体或想把大模型接进真实工作流的开发者和产品经理参考。1. 为什么 AI 需要一套“工具箱”1.1 模型能力边界与工具调用的本质大模型本质上是一个“思考者”不是一个“行动者”。它很擅长理解意图、生成文本、归纳信息但它在训练完成后就与世界失去了实时接触。你问它今天库存多少它不知道你让它读一下某个内部系统里的报表它连那个系统在哪都无从得知你让它帮你把一份数据整理成 Excel 发出去它只能生成一段 Python 代码却没法真正执行。工具调用Function Calling / Tool Use就是弥补这个缺口的关键机制模型负责拆解任务、决定调用哪个工具、传什么参数而真正读写数据、发送请求、执行计算的动作由工具完成。可以打一个比方模型是大脑工具是手和眼睛。没有工具的大脑只能纸上谈兵有了工具之后它才能检索资料、动手操作、验证结果。WorkMate 内置工具包要解决的核心问题不是“多接几个 API 那么简单”而是要让模型在一个可控、可观测、可回退的框架里安全地使用这些能力。我们见过很多项目在初期什么工具都接结果模型乱调工具、参数传错、权限失控最后整个系统比没接工具时更不稳定。所以工具包设计的本质是对模型能力边界的一种主动管理——决定它什么时候可以动手、什么时候必须停下来向人确认。1.2 WorkMate 的定位与工具包设计原则WorkMate 在我们团队里的定位是一个内部知识问答与工作流自动化助手。它需要处理的任务包括检索内部文档、汇总多方数据、生成周报、发起审批、定时提醒、把散落在不同系统里的信息拉通。这个定位决定了它的工具包不可能只有一个“搜索文档”的工具而是需要覆盖信息获取、内容生成、代码执行、系统操作等多个层面的“组合工具箱”。我们的工具包设计从一开始就定了三条原则。第一可观测性优先每一次工具调用都要有完整的请求、响应、耗时和 token 消耗记录模型为什么选这个工具、传了什么参数、结果是否被采纳全部可回溯。第二最小权限原则每个工具只暴露完成特定任务所需的最小接口能力绝不放开任意命令执行或整库读写。第三渐进式接入一个工具要先在小范围任务里验证稳定再放开到全员使用而不是一次性把所有接口全堆上去。这三条原则后来被证明非常关键尤其是当模型调用链越变越长的时候没有清晰的调用记录出了问题根本无从查起。2. 工具包的核心组成与选型解析2.1 六大类工具的功能拆解WorkMate 内置工具包目前包含六大类工具每一类都对应一类高频需求。我把它们整理成一张表方便对照理解工具类别典型能力解决的核心问题常见使用场景知识检索内部文档、问答库、历史记录的语义搜索让模型获得“组织记忆”员工问制度、查项目背景公开信息获取网页正文抓取、RSS 订阅解析弥补模型知识的时效性缺口查行业动态、竞品信息文档解析与生成PDF/Word/Excel 读写、格式转换打通非结构化数据的进出通道提取合同关键字段、生成报表代码执行在隔离沙箱中运行 Python 脚本让模型能做计算、能处理数据数据分析、文件批处理、格式转换数据查询内部数据库的只读查询接口让模型访问实时业务数据查库存、查订单、统计指标系统操作与通知发送消息、创建日程、发起审批流让模型能“办成事”而不只是“说建议”自动发周报、建会议、提醒跟进以知识检索为例它和普通关键词搜索最大的区别是向量化召回文档被切分成片段后转成向量用户提问时再把问题向量化做相似度匹配最后把最相关的几段文本拼进模型的上下文。这个过程让模型可以“基于证据回答”而不是凭记忆瞎编。而系统操作与通知类工具则承担了从“建议”到“执行”的跨越比如 WorkMate 可以在数据查询工具拿到周数据后调用文档生成工具产出报告再调用消息工具发到指定群整条链路跑完只需要一次对话指令。2.2 关键工具的选型对比与取舍选型是工具包建设里最容易纠结的环节我挑两个典型的例子说说我们是怎么取舍的。第一个是代码执行工具。我们试过两种方案一种是在服务端直接起一个 Python 子进程跑模型生成的代码另一种是丢进容器化的隔离沙箱里执行。第一种胜在简单几行代码就能跑通延迟也低但我们很快发现风险不可控——模型生成的代码偶尔会出现死循环、意外删除文件、访问内网端口等行为一旦在宿主机上出问题代价是难以承受的。最终我们选择了隔离沙箱方案虽然每次执行多花几百毫秒还要额外维护镜像和资源限额但换来的是可以放心让模型自由生成代码。对实际业务来说这个安全性溢价非常值得。第二个是数据查询工具。团队里一开始有两种声音一种是直接给模型数据库连接串让它写 SQL另一种是封装好只读查询接口模型只能按参数查。第一种看起来很灵活但真实场景里模型写 SQL 容易把大表全扫一遍或者误用敏感字段。我们最终选择的是“受限 SQL”模型生成 SQL 后先经过一个规则层做只读校验、超时限制、行数限制再发给数据库执行。用户请求“查上个月华东区销售额”模型生成的是一条带过滤条件的聚合 SQL规则层自动加上 LIMIT 和超时熔断既保留灵活性又控制住了风险。3. 实操过程与核心环节实现3.1 给 WorkMate 注册第一个工具从定义到生效我们以“查询部门成员日程”这个工具为例完整走一遍注册流程它一共涉及三步定义工具描述与参数 Schema、实现具体的回调函数、把工具挂载到 WorkMate 的运行配置里。第一步是定义工具描述。这一步比大多数人想象的重要得多。模型的工具选择能力很大程度上取决于描述写得清不清楚。我们当时的 JSON Schema 大致长这样{ name: query_member_schedule, description: 查询某位成员在指定时间范围内的日程安排返回日程标题、时间、地点和参与人。适合用于会议预约、周报汇总、日程协调等场景。, parameters: { type: object, properties: { member_name: { type: string, description: 要查询的成员姓名必须是组织架构内的中文姓名 }, start_date: { type: string, description: 开始日期格式 YYYY-MM-DD }, end_date: { type: string, description: 结束日期格式 YYYY-MM-DD不能早于开始日期 } }, required: [member_name, start_date, end_date] } }第二步是实现回调函数。这个函数接收模型按 Schema 解析出的参数然后去内部的日程服务取数返回给模型一个结构化的结果。我们当时用 Python 实现关键逻辑并不复杂。def query_member_schedule_handler(params: dict) - dict: member params[member_name] start params[start_date] end params[end_date] events schedule_client.fetch(member, start, end) if not events: return {status: empty, message: f{member} 在 {start} 至 {end} 内没有日程安排} return { status: success, events: [ { title: ev.title, start_time: ev.start_time, end_time: ev.end_time, location: ev.location, participants: ev.participants, } for ev in events ], }第三步是把函数注册进工具包配置。我们并没有把工具硬编码在模型请求里而是维护一个工具注册中心每次对话开始时根据用户意图和会话状态动态加载工具列表。这样不会让模型一次面对几十个工具降低选择难度也减少 token 消耗。3.2 编排工具调用链让多个工具协同完成一个任务单个工具能解决的需求很有限真正的价值场景是多工具协同。拿 WorkMate 最常用的“本周项目周报生成并发送”来说它需要串联四个工具数据查询工具读本周任务完成情况文档生成工具把结果写成 Markdown 周报代码执行工具把 Markdown 转成带格式的文档文件最后系统操作工具把文件发到群里。模型在收到指令后会自动规划调用顺序前一步的输出会成为后一步的输入。这里有一个容易踩的坑多步调用场景里模型可能把中间结果“记错”。比如数据查询工具返回了 12 条任务记录模型在下一步调用文档生成工具时把其中两条的状态摘要写错。我们后来采用的办法是不让模型凭记忆传递数据而是在上下文里保留工具返回的原始结果并明确提示模型“直接引用上文查询结果中的数据不要自行修改”。实现上我们用了一个简单的状态容器每一步工具调用的结构化输出都会暂存起来后续工具需要引用时直接按变量名读取。这相当于给模型提供了一张“草稿纸”既减少了模型在长上下文中翻找信息的负担也降低了信息在传递过程中被篡改的概率。实测下来串联任务的准确率比让模型纯靠上下文记忆提升了约四成。3.3 权限与安全边界设计工具包带来的风险往往不是模型“变坏”而是权限边界没划好。WorkMate 的权限设计分为三层。第一层是用户身份层。每个对话都绑定发起人的身份标识工具调用时把这个标识透传给下游系统而不是用统一的机器人账号去操作。这样每一笔数据查询、每一次消息发送都保留了操作者痕迹出了问题能找到责任人。第二层是工具能力层。我们为每个工具定义白名单参数和可执行范围。比如代码执行工具默认禁止网络访问禁止读取敏感目录消息发送工具只允许向预设范围内的群组发消息不允许私聊陌生人数据查询工具只暴露只读接口所有写操作必须走审批工具二次确认。第三层是操作确认层。对于不可逆或影响面大的动作比如发起审批、删除数据、对外发送消息我们要求模型先输出“准备执行的操作说明”由用户在对话里确认后再真正执行。很多 AI 落地项目忽略了这个环节觉得多一步确认很麻烦但实际经验告诉我们这一层恰恰是让业务方敢放开权限的关键。发生过不止一次模型理解用户意图偏差的情况多一道确认就能把这类错误挡在生产事故之外。4. 常见问题与排查技巧实录4.1 工具调用失败的 5 类典型场景工具包运行时间长了各种故障模式都会遇到。我把最常见的五类问题整理成速查表症状根本原因排查思路解决方向模型反复调用同一个工具但不成功工具返回的错误信息太模糊查看工具返回的原始报错是否被截断让工具返回结构化错误码并把错误码含义写入系统提示工具参数总是传错格式Schema 描述缺少格式示例检查模型请求日志中实际传入的参数在参数描述里补充示例值比如日期格式、枚举值范围模型选错工具工具描述之间区分度不够对比两个工具的描述文本是否容易混淆重写描述明确各自的适用场景和不适用场景工具返回内容过大导致上下文溢出响应内容没有做裁剪和汇总检查是否把整表数据都塞给了模型服务端先做字段精简、分页截取或预聚合调用链中途中断某个中间工具超时或异常查看调用链追踪中的耗时分布为每个工具设置独立超时时间增加重试退避策略这里我想重点说说第一个问题。模型在工具调用失败后的行为往往不尽人意它可能会反复用相同参数重试即使错误信息已经说明“参数不合法”。我们的解决办法是工具返回的报错要人性化、可行动化不能只抛{error: 500}而要返回类似“member_name 对应的成员不存在请检查姓名拼写或使用组织成员搜索工具确认后再查询”这样的提示。当模型看到具体原因时它的自我纠错能力会显著提升。4.2 从日志到追踪定位“AI 自作主张”的排查方法有一次我们收到反馈说 WorkMate 在生成周报时连续调用了十几次数据查询工具把某个数据库接口直接打到超时。排查时我们发现模型在拿到第一次查询结果后觉得数据不够“丰富”于是不断微调日期范围反复查询造成接口压力。这类问题光看最终结果很难发现必须依靠完整的调用链日志。我们的追踪方案是给每一次用户请求分配一个 trace_id从用户输入开始到模型每次工具调用的请求、响应、token 消耗再到最终回复全部串联起来。通过可视化界面可以看到原本预期 4 步的调用链膨胀到了 15 步。定位到模型反复查询的意图后我们的解决方案有两个一是在数据查询工具的描述里增加“该工具会返回完整统计结果除非业务要求分段获取否则不建议重复调用”的提示二是在框架层面增加重复调用检测如果同一工具在短时间内以相似参数被调用超过三次系统会强制中断并询问用户“是否需要继续查询”。这类“AI 自作主张”的问题靠模型自律不如靠框架约束来得可靠。4.3 WorkMate 工具包避坑清单最后分享几条我们沉淀下来的避坑经验。第一工具描述里不要用“万能”类词汇。早期我们把一个文档解析工具描述成“可以处理所有格式的文档”结果模型什么文件都往它那里送连图片识别失败后反复重试。后来我们在描述里明确写出“支持 PDF、Word、Excel图片格式请使用图片解析工具”工具选择的准确率立刻提升。第二工具的返回结果最好统一包装成{status: ..., data: ...}的结构别让不同的工具各自返回不同字段名。模型在引用结果时统一的结构可以明显减少字段理解错误。我们刚上线时有些工具返回data有些返回result有几次模型把result里的 JSON 字符串当成嵌套对象处理折腾了很久。第三工具包不是越丰富越好。工具太多模型的选择压力会变大而且工具之间的边界更容易模糊。我们的经验是每次新增工具前先问三个问题——这个功能是否已有工具覆盖模型是否能准确区分它与现有工具的边界接入后是否能解决一个真实的高频需求三个问题有一个不达标就先不上。5. 从工具包到工具箱的迭代心得5.1 工具包管理的日常不是一劳永逸工具包上线只是开始真正的挑战在维护。我们维护的方式分三个层次代码层做版本管理和灰度开关新工具先在“测试空间”里跑一段时间只允许小部分用户调用配置层做定期的工具描述审查因为随着模型版本升级它对描述的理解方式也会变化原本有效的描述可能变得含糊数据层做调用频率和失败率的周度复盘连续两周调用量为零的工具会标记为“待优化”要么重写描述要么直接下线。印象很深的一次优化是在模型升级后开始的。原本表现良好的工具选择在升级后突然频繁出错。排查了好几天才发现新模型对工具描述的语义理解更加“灵活”它会因为两个工具都提到了“数据”就把它们当成可替代项。后来我们的工具描述措辞统一加入了“本工具不适用于……”的反向界定效果立竿见影。这件事之后我们每升级一次模型版本都会跑一轮工具选择的回归测试确认所有既有工具仍然被准确触发。5.2 衡量工具包价值的三个侧面工具包的价值不能只凭“感觉好用”来判断我们日常用三个指标来衡量任务完成率、人为干预率、平均调用链长度。任务完成率指用户发起请求后WorkMate 在不依赖人工介入的情况下完成目标的比例人为干预率指用户发消息打断、纠正或二次确认的频率平均调用链长度则反映了任务复杂度这个数字如果异常增长往往意味着工具分工不合理或模型在低效尝试。这套指标帮助我们做过一个很务实的减法某个财务相关工具原来的调用成功率只有 45%频繁需要人工介入后来我们发现它和查询工具的场景重叠度过高模型经常拿它去查一个数据查询工具更擅长的内容。重新划分边界后该工具的成功率提升到 87%整体人为干预率明显下降。所以工具包建设其实是一个持续做加法和减法的过程加的是能力减的是冗余和混乱。5.3 我个人最想提醒的一点如果只让我说一条经验那就是工具包设计要以“人机协作的流畅度”为中心而不是以“模型能力炫技”为中心。我们最开始的几次迭代总是想给 WorkMate 加更多“看起来厉害”的工具结果反而让用户觉得它变得难以预测。后来我们把重心转回到用户真实的工作流上每次新增工具前都先做需求和路径的梳理用户需要几步操作、希望什么信息出现在什么位置、哪些环节必须有人的确认这些想清楚之后工具包自然就越配越顺手。最后再分享一个小技巧在工具包的每个关键决策点我都会问自己一句——如果模型这次调错工具了最坏的结果是什么这个结果我们能否承受如果不能承受就再加一道防护或确认机制。想明白这个问题的项目工具包大多都能稳健地跑下去。