罗罗编程学习记录
本页内容 展开查看

10.4.1.3 工具设计与参数校验

所属:全栈开发面试题库 / 10 AI 应用开发:LLM 与 Agent / 10.4 Agent 架构 / 10.4.1 Agent 循环与工具调用

10.4.1.3-001 一个好的工具描述应包含哪些要素?

一句话结论

包含:工具用途、适用与不适用场景、输入参数含义与格式、返回内容、副作用与风险;描述面向模型选择决策,写清边界与示例,避免实现细节堆砌。

概念解释

  • 用途与边界:何时用、何时不用。
  • 参数说明:字段类型、格式、示例。
  • 风险提示:写操作与副作用。

原理流程

  1. 归纳工具解决的问题与排除场景。
  2. 逐参数说明约束。
  3. 标注副作用与权限要求。

代码 / 示例

用途: 查询指定订单的状态与金额
不适用: 搜索用户、修改订单
返回: 订单状态、金额、更新时间
副作用: 只读, 不改动数据

常见误区

  • 误区:描述只写函数名同义反复;正解:模型看不到实现,描述必须承担选择与填参指引。
  • 误区:把内部实现细节写进给模型的描述;正解:实现细节对决策无帮助,应保持接口语义清晰。

追问

  • Q:描述过长有影响吗? A:过长噪声增加,应聚焦用途、边界与参数。
  • Q:返回值要在描述里说吗? A:要,模型据此判断结果是否足够作答。

10.4.1.3-002 参数 JSON Schema 应如何定义类型与约束?

一句话结论

参数声明类型(string/number/integer/boolean/object/array)、必填项、枚举范围、格式与描述;能用枚举限定的取值不要开放自由文本;约束写在 schema 中,应用层再按同一规则校验。

概念解释

  • 类型:字段数据形态。
  • 必填:缺失即非法。
  • 枚举:受控取值集合。
  • 格式:日期、编号等模式。

原理流程

  1. 定义字段类型与必填关系。
  2. 枚举/范围/格式约束。
  3. 应用层校验规则与 schema 一致。

代码 / 示例

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["paid", "pending", "shipped", "cancelled"],
      "description": "订单状态过滤,仅取枚举值"
    },
    "limit": {"type": "integer", "minimum": 1, "maximum": 100}
  },
  "required": ["status"]
}

常见误区

  • 误区:参数都用 string 图省事;正解:类型宽松导致格式错误与注入面扩大。
  • 误区:schema 约束写了但应用不校验;正解:schema 只是提示,执行层必须强制校验。

追问

  • Q:嵌套对象怎么定义? A:逐层声明属性与必填,数组元素用 items 定义结构。
  • Q:范围约束写在哪里? A:schema 与校验层都体现,避免模型取值越界。

10.4.1.3-003 必填参数缺失如何处理?

一句话结论

应用校验发现必填缺失时,返回缺失字段与取值要求,让模型补充或发起澄清;不猜测默认值执行写操作;读操作可按业务约定默认值,但需在描述中写明。

概念解释

  • 缺失判定:必填字段为空或未提供。
  • 反馈补全:错误回传期望字段。
  • 默认策略:仅只读场景可约定。

原理流程

  1. 校验必填集合。
  2. 缺失则回传字段名与说明。
  3. 模型补全后重新校验。

代码 / 示例

{
  "error": "缺少必填参数 order_id",
  "missing": ["order_id"],
  "expected": {"order_id": "string,订单号"}
}

常见误区

  • 误区:应用自动填默认订单号;正解:写操作对象不能猜,错对象后果严重。
  • 误区:缺失字段直接报错终止;正解:先反馈补全,给模型修正机会。

追问

  • Q:业务上确有默认值怎么办? A:在工具描述中写明默认逻辑,避免模型与应用理解不一致。
  • Q:多次缺失同一字段怎么办? A:转澄清动作,向用户索取缺失信息。

10.4.1.3-004 参数枚举与自由文本如何取舍?

一句话结论

状态、类型、渠道等受控分类用枚举;用户姓名、备注、查询词等开放内容保留文本但做长度与字符约束;枚举减少歧义无谓取值,开放文本满足真实输入,二者按取值是否受控选择。

概念解释

  • 枚举:有限可枚举集合。
  • 自由文本:开放语义输入。
  • 约束:长度、字符、敏感校验。

原理流程

  1. 判断取值集合是否有限可控。
  2. 受控字段用枚举。
  3. 开放字段加边界约束。

代码 / 图示

订单状态/渠道/类型 → enum
客户名称/留言/搜索词 → string + 长度/字符约束

常见误区

  • 误区:能枚举的也写自由文本;正解:自由文本产生同义错值,下游解析困难。
  • 误区:开放文本不加任何约束;正解:长度与特殊字符边界仍需控制。

追问

  • Q:枚举值需要扩展怎么办? A:版本化补充取值,回归验证模型选择与下游处理。
  • Q:用户输入不在枚举内怎么办? A:提示合法取值,不擅自映射到相近枚举。

10.4.1.3-005 工具输入输出如何保持结构稳定?

一句话结论

输入参数与返回字段定义保持向后兼容:新增字段可选,不随意改名或改变类型;返回结构面向下游消费设计;结构变更同步版本与回归;稳定接口让多步链条可预期地解析结果。

概念解释

  • 向后兼容:旧调用仍可用。
  • 字段约定:命名、类型、含义固定。
  • 下游消费:返回结构服务后续步骤。

原理流程

  1. 定义稳定字段契约。
  2. 变更以新增可选字段为主。
  3. 破坏性变更走版本升级。

代码 / 图示

返回: { status, amount, updated_at, items? }
新增字段可选; 改名/改类型 → 新版本

常见误区

  • 误区:返回值随手调整不通知;正解:下游步骤解析字段,结构破坏会断链。
  • 误区:把内部对象直接透出;正解:对外返回应裁剪为契约字段。

追问

  • Q:字段废弃怎么处理? A:先标记弃用、下游迁移,再下线,保留过渡期。
  • Q:返回列表分页结构? A:统一字段表达条数、游标/页码,便于后续步骤处理。

10.4.1.3-006 工具副作用与只读属性如何标注?

一句话结论

工具在描述中标注只读、写入、删除、外发等副作用级别;应用层按副作用等级匹配权限与确认策略;模型与审计都能据此判断动作风险,写操作不与只读工具混同处理。

概念解释

  • 只读:不改变外部状态。
  • 写入:新增/修改/删除。
  • 外发:通知、提交、对外发布。

原理流程

  1. 评估动作对外部状态的影响。
  2. 标注副作用级别。
  3. 按级别接入权限与确认。

代码 / 图示

read:  查询, 无副作用
write: 创建/修改, 需权限
delete/external: 高危, 需确认 + 审计

常见误区

  • 误区:工具描述不提副作用;正解:风险等级不可见会导致高危动作被自动执行。
  • 误区:写操作与读操作同一权限口径;正解:写操作授权与确认应更严格。

追问

  • Q:副作用级别谁定义? A:业务与安全角色按动作影响评定,记录在工具配置中。
  • Q:读工具也可能泄露数据怎么办? A:按数据权限控制可见范围,不只看读写标记。

10.4.1.3-007 参数校验应分哪几层?

一句话结论

三层:schema 结构校验(类型、必填、枚举、格式)、业务校验(归属、范围、状态合法)、安全校验(注入、越权、敏感内容);模型输出不可信,应用入口与工具实现都要校验。

概念解释

  • 结构层:格式合法性。
  • 业务层:对象与状态合理性。
  • 安全层:输入风险与权限。

原理流程

  1. schema 校验通过后进入业务校验。
  2. 业务归属与状态检查。
  3. 安全输入检查后执行。

代码 / 图示

结构(类型/必填/枚举) → 业务(归属/状态/范围) → 安全(注入/越权)

常见误区

  • 误区:只做 schema 校验就执行;正解:对象归属与业务状态不合法仍会造成错误操作。
  • 误区:校验只在入口做一次;正解:工具实现内部也要复核,防止入口被绕过。

追问

  • Q:校验失败返回什么? A:分层说明失败原因与可修正方向,供模型/用户处理。
  • Q:业务校验示例? A:只能操作本人或本门店数据,订单状态允许的变更范围。

10.4.1.3-008 如何避免参数被拼接进危险命令?

一句话结论

工具实现使用参数化接口(参数绑定、结构化调用),不把参数拼接成 SQL、Shell 或脚本命令;输入按类型与白名单校验;命令构造由受信代码完成,模型参数只作为值传入。

概念解释

  • 参数化:值与命令结构分离。
  • 白名单:类型与合法范围。
  • 受信构造:命令由固定代码生成。

原理流程

  1. 参数进入受控数据结构。
  2. 调用层参数化绑定。
  3. 禁止字符串拼接命令。

代码 / 图示

安全: WHERE order_id = ? 绑定参数
危险: "SELECT ... WHERE id='" + arg + "'"

常见误区

  • 误区:转义一下字符串就安全;正解:转义可被绕过,参数化绑定才是根本手段。
  • 误区:模型不会传恶意内容;正解:上游材料可能被注入污染参数,执行层必须防护。

追问

  • Q:动态表名/字段名怎么办? A:用白名单映射,不把用户输入直接拼进标识符。
  • Q:外部命令调用? A:参数以数组形式传递,避免 shell 解析拼接。

10.4.1.3-009 工具数量过多会带来什么问题,如何精简?

一句话结论

工具过多增加选择噪声、描述上下文负担与误选概率;按场景分组挂载、合并语义重复工具、下线低频工具;保留工具描述与参数精简,定期按调用统计与错误率整理工具集。

概念解释

  • 选择噪声:相近工具竞争。
  • 上下文负担:描述占用窗口。
  • 精简:分组、合并、下线。

原理流程

  1. 统计各工具调用频率与错误。
  2. 合并重复语义工具。
  3. 按任务场景动态挂载子集。

代码 / 图示

高频工具常驻; 低频/场景工具按需加载
重复工具 → 合并为带参数区分的单一工具

常见误区

  • 误区:工具越多能力越强;正解:误选与参数错配概率随数量上升。
  • 误区:一次挂全部后端能力;正解:按任务白名单加载必要工具。

追问

  • Q:相近工具合并后参数怎么区分? A:用受控参数表达不同对象或动作,schema 注明取值含义。
  • Q:工具下线前做什么? A:查调用依赖与错题集,回归验证后移除。

10.4.1.3-010 工具命名应遵循什么规范?

一句话结论

名称清晰表达动作与对象,动词开头、小写与受控分隔,避免含糊缩写;同一组工具命名风格一致,便于模型区分相近工具;名称与描述一致,不使用内部代号或业务黑话。

概念解释

  • 语义明确:动作 + 对象。
  • 风格一致:命名格式统一。
  • 可区分:相近工具命名有差异。

原理流程

  1. 按动作对象定义名称。
  2. 统一分隔与大小写约定。
  3. 检查相近工具可区分度。

代码 / 图示

get_order / list_orders / cancel_order
避免: do_stuff / handle1 / op_a

常见误区

  • 误区:用内部函数名直接当工具名;正解:内部代号对模型无语义,容易误选。
  • 误区:多个工具名称高度相似;正解:动作或对象部分应能区分。

追问

  • Q:命名与后端函数不一致怎么办? A:工具层定义对外语义名,后端实现做映射。
  • Q:命名变更影响什么? A:调用记录与回归样本需同步更新版本。

10.4.1.3-011 如何设计工具返回结果便于模型消费?

一句话结论

返回结构化字段、关键结论前置、错误与数据分离;列表给出条数与关键字段,大对象外部引用;字段命名稳定,避免把自由文本大段塞进返回;结果能直接支持下一步决策。

概念解释

  • 结构化:字段可解析。
  • 结论前置:先给状态与要点。
  • 错误分离:status/error 明确。

原理流程

  1. 按下游需要裁剪字段。
  2. 组织状态、数据、错误结构。
  3. 大结果压缩并留引用。

代码 / 示例

{
  "status": "ok",
  "order_id": "A20260101001",
  "state": "paid",
  "amount": 199.00,
  "items_count": 2,
  "error": null
}

常见误区

  • 误区:返回一大段未结构化文本;正解:模型解析易错,关键字段应结构化。
  • 误区:成功失败混在文本里;正解:状态字段明确,便于判断下一步。

追问

  • Q:返回内容多怎么办? A:给摘要与计数,明细存外部按引用回取。
  • Q:字段命名跨工具统一吗? A:通用状态字段(status/error)保持一致。

10.4.1.3-012 写操作工具为何需要二次确认?

一句话结论

写操作改变外部状态且难以自动回滚,执行前需向用户或审批流确认对象、动作与关键参数;自动循环不能默认放行删除、支付、外发、批量修改等动作;确认记录进入审计轨迹。

概念解释

  • 不可逆性:状态变更后果。
  • 确认对象:动作、目标、参数。
  • 审计:确认人与依据留痕。

原理流程

  1. 工具标记高危副作用。
  2. 调用前生成确认信息。
  3. 确认通过后执行并记录。

代码 / 图示

高危工具 → 展示: 动作/对象/参数 → 用户/审批确认 → 执行 → 审计

常见误区

  • 误区:模型说可以执行就直接放行;正解:确认权在用户或审批策略,不在模型。
  • 误区:确认一次后续同类写操作免确认;正解:按动作与对象逐次评估风险。

追问

  • Q:哪些动作算高危? A:删除、支付/退款、批量修改、对外发送、权限变更,按业务清单评定。
  • Q:确认界面展示什么? A:对象标识、动作类型、关键参数与影响范围。

10.4.1.3-013 工具的幂等键应如何设计?

一句话结论

写操作生成稳定唯一的幂等键(会话、任务、操作类型与对象组合),服务端按键识别重复提交并返回首次结果;键由应用生成并随调用传入,模型不自行编造重复或冲突标识。

概念解释

  • 幂等键:识别同一操作。
  • 服务端去重:重复提交不重复生效。
  • 应用生成:稳定可控。

原理流程

  1. 应用为操作生成幂等键。
  2. 调用与服务端记录键与结果。
  3. 重复提交按键返回既有结果。

代码 / 图示

idempotency_key = session_id + task_id + action + target
重复请求 → 命中键 → 返回原结果

常见误区

  • 误区:靠前端/模型不重复点;正解:重试与超时场景必须服务端去重。
  • 误区:幂等键每次随机生成;正解:随机键失去去重作用,重复操作会各自生效。

追问

  • Q:键冲突怎么处理? A:生成规则保证唯一性,冲突时拒绝并告警。
  • Q:只读工具需要幂等键吗? A:不需要,重点保护有副作用的写操作。

10.4.1.3-014 参数中的时间、编号、枚举值如何校验?

一句话结论

时间校验格式、范围与相对时间解析;编号校验前缀、长度与字符集;枚举校验取值在受控集合内;校验规则在 schema 与应用层一致,错误反馈指出正确格式与示例。

概念解释

  • 时间:格式、范围、时区。
  • 编号:前缀、长度、字符集。
  • 枚举:白名单集合。

原理流程

  1. 按字段类型应用规则。
  2. 非法返回格式示例。
  3. 修正后再次校验。

代码 / 示例

日期: YYYY-MM-DD, 不超出允许范围
编号: 字母开头 + 数字, 示例 A20260101001
枚举: 仅允许清单内取值

常见误区

  • 误区:相对时间交给模型自由换算;正解:应用层解析「昨天」等表达并校验时区边界。
  • 误区:编号只查非空;正解:格式不合法可能指向错误对象。

追问

  • Q:跨时区时间怎么处理? A:统一存储与比较口径,输入解析后标注时区。
  • Q:枚举大小写不一致? A:按受控标准归一,非法值反馈正确取值。

10.4.1.3-015 工具失败时返回给模型的信息如何把握粒度?

一句话结论

回传错误类型、可修正原因与处理建议,不泄露内部堆栈、密钥与敏感实现;参数类错误给出期望格式,系统错误给出是否可重试;粒度让模型能决策,又不暴露内部细节。

概念解释

  • 错误类型:可修正/可重试/拒绝。
  • 修正指引:格式、范围。
  • 脱敏:内部细节不外泄。

原理流程

  1. 归类错误性质。
  2. 生成面向决策的反馈。
  3. 内部详情留日志,对外脱敏。

代码 / 图示

对模型: 订单不存在 / 参数格式应为… / 临时超时可重试
对日志: 完整堆栈与内部错误码

常见误区

  • 误区:把原始堆栈抛给模型;正解:内部实现细节可能被用于构造攻击。
  • 误区:错误只写「失败」;正解:缺少原因模型无法选择修正或换路径。

追问

  • Q:权限拒绝怎么反馈? A:说明无权限操作该对象,不提示绕过方式。
  • Q:业务失败与系统故障区分? A:业务结果正常返回给用户判断,系统故障进入重试策略。

10.4.1.3-016 如何为工具设计默认值与可选参数?

一句话结论

默认值应在工具描述与实现中一致写明,可选参数标注省略时的行为;默认逻辑服务于常见场景,不掩盖必要的对象确认;新增可选参数不破坏既有调用契约。

概念解释

  • 默认行为:省略参数时的处理。
  • 可选参数:非必填但有约定。
  • 契约一致:描述与实现对齐。

原理流程

  1. 判断参数是否有合理默认。
  2. 描述写明省略行为。
  3. 实现按默认逻辑执行。

代码 / 示例

{
  "properties": {
    "limit": {"type": "integer", "default": 20, "description": "返回条数,省略时 20,最大 100"}
  }
}

常见误区

  • 误区:实现有默认值但描述不写;正解:模型不知道默认行为,可能误填或漏填。
  • 误区:写操作对象字段给默认值;正解:目标对象不能用默认值代替确认。

追问

  • Q:默认值会变化吗? A:变更默认属于契约调整,需版本记录并回归。
  • Q:可选参数枚举? A:省略时走默认,填写必须在合法集合内。

10.4.1.3-017 工具与后端接口之间的映射层做什么?

一句话结论

映射层负责工具调用到后端接口的参数转换、权限校验、结果裁剪与错误归一;模型面对的工具契约稳定,后端实现可调整;映射层隔离模型输出与内部系统,是安全与兼容的缓冲层。

概念解释

  • 参数转换:工具参数 → 后端请求。
  • 安全裁剪:权限字段与返回范围。
  • 错误归一:后端错误转工具反馈。

原理流程

  1. 校验工具参数。
  2. 转换并调用后端。
  3. 裁剪结果、归一错误后回传。

代码 / 图示

tool_call → 映射层(校验/转换/权限) → 后端接口 → 裁剪/归一 → 模型结果

常见误区

  • 误区:工具直接暴露后端原始接口;正解:后端字段与错误结构不应直接决定模型契约。
  • 误区:映射层不做权限检查;正解:权限校验必须在映射/服务层落地。

追问

  • Q:后端接口升级影响工具吗? A:通过映射层适配,保持工具契约稳定。
  • Q:结果裁剪依据什么? A:调用身份的数据权限与下游步骤需要的字段。

10.4.1.3-018 如何发现工具设计上的高频错误?

一句话结论

按工具统计选择错误、参数错误、校验失败与失败原因分布;回看错误轨迹归类到描述不清、schema 过松、缺上下文或实现问题;高频错误优先修订描述、约束或拆分工具。

概念解释

  • 错误分布:按工具与原因统计。
  • 轨迹归类:定位设计环节。
  • 优先级:高频错误先改。

原理流程

  1. 采集调用日志与错误反馈。
  2. 按工具/原因分组统计。
  3. 修订并回归对照。

代码 / 图示

工具 X: 选错 N / 缺参 N / 枚举错 N / 归属错 N
归因: 描述 / schema / 上下文 / 实现

常见误区

  • 误区:错误都归模型能力;正解:先看工具描述与参数约束是否清楚。
  • 误区:只看总量不分组;正解:不按工具归类无法定位具体改进点。

追问

  • Q:参数错误最高频怎么改? A:收紧枚举/格式、补示例与约束描述。
  • Q:改进后如何验证? A:在回归错题集上复跑,对比错误率变化。

10.4.1.3-019 工具配置应如何版本化管理?

一句话结论

工具名、schema、描述、副作用等级与权限策略纳入版本控制;线上会话记录所用配置版本;破坏性变更走新版本,旧版本按兼容期下线;配置变更与模型提示、回归样本一起发布。

概念解释

  • 配置版本:契约与策略快照。
  • 兼容期:旧版本过渡。
  • 联动发布:提示/样本同步。

原理流程

  1. 工具配置随代码版本管理。
  2. 线上记录配置版本。
  3. 变更跑回归后发布。

代码 / 图示

tool_config v1 → v2(变更说明/兼容策略)
记录: 会话使用版本; 回归样本同步更新

常见误区

  • 误区:工具描述在线上随意改;正解:改动影响选择行为,需要评审与回归。
  • 误区:不记录线上配置版本;正解:复盘时无法还原当时 schema 与权限策略。

追问

  • Q:权限策略变更走什么流程? A:与安全策略同步评审,高风险变更有审批记录。
  • Q:配置回滚怎么做? A:版本快照可回退,回滚后回归验证调用链路。

10.4.1.3-020 工具设计与校验落地清单是什么?

一句话结论

清单:用途与边界描述、参数 schema(类型/必填/枚举/格式)、分层校验、副作用标注、只读/写/高危确认、参数化防注入、结果结构稳定、返回可消费结构、幂等键、工具精简与命名规范、配置版本化与错误率回归。

概念解释

  • 契约设计:描述、schema、命名、结构。
  • 执行安全:校验、权限、确认、幂等、注入防护。
  • 演进:版本、精简、回归。

原理流程

  1. 定义工具契约与安全等级。
  2. 实现映射层与分层校验。
  3. 按错误率持续优化并版本化。

代码 / 图示

□ 用途边界  □ 参数schema  □ 分层校验  □ 副作用标注
□ 高危确认  □ 参数化防注入  □ 稳定返回结构  □ 幂等键
□ 精简/命名  □ 配置版本  □ 错误率回归

常见误区

  • 误区:工具设计只面向开发实现;正解:描述与 schema 首先服务模型决策,再服务执行。
  • 误区:上线后不维护工具集;正解:调用统计与错题回流驱动工具迭代。

追问

  • Q:工具如何组合完成复杂任务? A:单工具能力明确后,见 10.4.1.4 多 Agent 编排与任务分解。
  • Q:工具间通信协议? A:跨进程工具与 Agent 协议见 10.4.2.1 MCP 工具协议。