Agent 工具调用工程规范：边界、拦截、容错、防失控

Agent 能不能真正干活，一半取决于它调用的工具设计得好不好。我自己在项目里被工具调用坑过几次之后，总结了一套必须守住的规范，写下来供参考。

工具设计：单一职责是第一原则

先说工具设计。工具必须遵守"单一职责"——一个工具只负责一件事，别想着塞多个功能进去。你想想，模型是靠自然语言去理解工具描述、生成参数的，工具职责越混杂，它理解错的概率就越高。

工具定义在技术上通常用 Function Calling 机制实现：你给模型提供一份工具清单，每份清单包含工具名、描述、参数 JSON Schema。模型根据这些描述决定调用哪个工具、传什么参数。所以工具元信息写得好不好，直接决定调用准不准——入参格式、参数类型、适用场景、限制条件、返回结构，描述得越明确，模型调用就越不容易翻车。

这里有几个容易被忽视的细节：参数要定义默认值和边界（比如分页的 pageSize 上限）；返回结构要稳定，不然模型解析会乱；工具描述要用模型"看得懂"的话写，别写一堆只有工程师懂的缩写。工具描述写得含糊，是调用失败最常见的原因。写工具描述有个技巧：多用"正面例子"——在描述里附上一个调用示例，模型看到例子，生成参数的准确率会高很多。

运行管控：三条红线

然后是运行管控，这是防失控的关键。我设置了三条红线：

第一，最大调用轮次限制。给全局配一个轮次阈值，超过就直接终止流程。不然模型一旦陷入循环，Token 会无限消耗，逻辑也会卡死。这个限制不能省——很多 Agent 事故，就是没设轮次上限导致的。设多少合适？一般业务 10-15 轮足够，太少了正常的任务都跑不完，太多了容易失控。

第二，高危操作强制人工拦截。删除、修改、数据提交、外网请求这类风险操作，绝对不允许 AI 自主触发，必须走人工确认。别觉得麻烦，这是防事故的底线——AI 误删数据这种事，出一次就够你喝一壶的。实现上可以给工具打上"高危"标记，触发时挂起，等人工审批通过再放行。这里的原则是"宁严勿松"：凡是拿不准的，都默认要人工确认。

第三，调用优先级管控。多个工具可能产生冲突的场景，提前定好优先级，避免逻辑混乱。比如"先查缓存再查数据库"这种顺序，要用规则约束，不能全靠模型自由发挥。

异常容错和日志

异常容错是生产环境必备的能力。网络超时、参数不合法、接口报错、返回空数据、服务熔断……每一种异常都要预设降级话术和兜底逻辑，保证单个工具出问题不会拖垮整条流程。同时全局日志埋点，记录每一次调用的入参、出参、推理逻辑和异常信息，方便线上问题复盘。

这里有个工程细节：日志要有唯一标识（traceId），把一次 Agent 任务的完整链路串起来，这样才能在日志系统里按任务检索每一步。没有链路追踪，Agent 出问题你连从哪查都不知道。每一轮工具调用的入参、出参、耗时、错误，都要跟 traceId 绑定记录——这决定了你复盘的时候能不能一分钟定位问题。

测试：不能只看单次成功

这里我还想说一个容易忽略的点：判断 Agent 稳不稳定，不能只看单次成功。要专门测试工具返回异常、参数边界、用户中途取消、并发调用、权限不足、上下文溢出这些场景，每个失败场景都要有明确的结果。没有这些测试，你的 Agent 只能算演示，不能算可上线。测试的方式可以自动化：准备一组"输入-期望输出"的用例集，批量跑，看通过率；再配合人工抽查，就能比较客观地评估稳定性。

一句话总结我的经验：模型的自主智能，必须建立在工程约束之上。强边界、高可控、稳兜底——能力可以放开，但边界必须焊死。工具调用这块做好了，Agent 才从"玩具"变成"工具"。