把业务 API 变成 Agent 真正敢用的工具
工具接入不只是给接口加一层描述。参数、权限、幂等和可观测性,决定它能否进入真实业务流程。
当 Agent 开始调用业务系统,工具定义就成了人与模型之间的新接口。一个“能调用”的 MCP Server,和一个“可以放心交给生产流程”的 MCP Server,中间还隔着不少工程工作。
先收窄动作,再描述动作
如果把原有后台 API 原样暴露,模型很容易面对过多参数和含糊的操作语义。我的做法是按业务动作组织工具:查询账户状态、读取可用余额、发起充值等。每个动作都应有明确的输入、返回结果和失败边界。描述要说清楚什么时候该调用,尤其要指出什么时候不该调用。
权限必须回到服务端
模型生成的参数不能成为授权依据。调用方身份、账户归属、设备或会话绑定都要在服务端校验。对于影响资金的动作,还需要把“申请执行”和“确认执行”分开考虑,并留下可追溯的操作者与请求编号。
把重试当作默认情况
Agent 可能因为超时重试,网络层也可能重复投递。读操作通常容易处理;写操作要设计幂等键,并在数据库中建立唯一约束,让同一业务意图只生效一次。返回值需要区分“已完成”“仍在处理”和“明确失败”,避免模型把未知状态误判为成功。
给人留下检查路径
日志里至少应能串起一次对话请求、工具调用、下游 API 和最终业务结果。对模型隐藏的内部异常可以有统一的用户提示,但工程人员仍需看到原始错误和耗时。这样工具失败时,才能定位究竟是参数理解、授权、下游服务还是超时策略出了问题。
我在广告账户、充值与查询等业务能力的工具化工作中,越来越觉得工具接口的价值在于把业务规则表达得足够清楚。模型能力会变化,清晰的边界与可靠的服务端约束会长期有效。