怎样为 Agent 设计易调用、可校验且安全的工具接口？

面试时怎么答

用一组好坏接口对比最容易说清：execute_request 这类万能工具让模型承担过多权限与参数判断，而窄业务接口能用 enum、范围和 required 字段约束输入。还要交代返回 Schema、错误类型、幂等键、dry-run 和副作用。工具拆分粒度被追问时，回答要在可理解性与调用步数之间取平衡。

可以这样答：

Agent 工具应暴露命名清楚、参数受限的最小业务能力，而不是“执行任意 HTTP 请求”这样的万能接口。输入用 Schema 标出必填项、枚举和范围，返回值也要结构化；写操作带幂等键，并明确是否支持 dry-run、会产生什么副作用。真正的权限由服务端根据调用者身份注入，不能让模型通过参数自行声明。

核心回答

工具设计首先决定模型是否能选对和填对。名称应表达单一动作，描述写清“何时使用、何时不要使用、参数单位与前置条件”。输入使用 JSON Schema 限制类型、必填项、枚举、范围与额外字段；不要把 JSON 字符串再塞进一个自由文本参数。输出也应结构化，区分成功结果、可重试错误、参数错误、权限错误和永久业务错误。

安全边界必须在工具服务端，而不是交给模型自律。租户、用户与权限从可信会话注入；工具只持有最小凭据。写操作采用幂等键，并尽可能支持 preview/dry-run → 人工确认 → commit。接口元数据可以标记只读、破坏性或幂等，但这些标记是提示，客户端仍要实际执行权限与确认策略。

展开说明

接口粒度应围绕可独立验证的业务动作。过粗的 run_sql、call_api 增大注入和误用面；过细则迫使模型编排几十步。可以把确定性复杂流程封装成一个领域服务，只让 Agent 选择参数和时机。

Schema 变更要版本化。新增可选字段通常较兼容，改名、改类型和语义变化应发布新版本；旧轨迹回放可发现提示或模型升级后的工具选择退化。

工程实践

为每个工具建立正常、缺参、越界、权限不足、超时、重复提交和依赖失败测试。记录模型看到的工具版本、经脱敏的参数摘要、校验错误、幂等命中和执行结果。关键指标包括工具选择准确率、首轮参数通过率、平均修复次数、端到端成功率、重复副作用数和人工确认覆盖率。

常见追问

为什么 additionalProperties: false 常有帮助？ 它能拒绝未声明字段，避免模型凭空添加参数；但 Schema 演进时要做好版本兼容。
工具越少越好吗？ 不是；工具太多会增加选择混淆，太少又会形成高权限万能工具，应按独立业务能力与风险边界划分。
只读工具还需要权限校验吗？ 需要；读取也可能泄露跨租户或敏感数据，必须由服务端执行对象级授权和审计。

一句话复习

好工具接口是窄能力、强 Schema、结构化错误、幂等副作用与服务端最小权限的组合。