模块 2Tool 与 Agent Runtime

Tool 契约设计

Tool 是能力契约，不是随手暴露的函数

  • 面向模型的语义描述
  • 面向 Runtime 的执行和权限元数据
  • 面向调用方的稳定输入输出
  • 面向治理的 Owner、版本和审计信息

名称与描述决定模型如何区分能力

  • 名称稳定、动词清晰、避免近义 Tool
  • 描述说明适用条件和不适用条件
  • 列出关键副作用与前置状态
  • 不要在描述中隐藏业务规则或凭据

参数 Schema 应减少歧义而非复刻内部 API

  • 用 enum、范围和可判别联合类型收窄动作空间
  • 时间、金额、ID、单位和默认值必须明确
  • 优先传业务标识，不让模型生成内部令牌或权限字段
  • Schema 合法后仍要做权限、存在性和状态校验

结果既要供模型理解，也要防止 Context 爆炸

  • 成功数据与可读摘要分层
  • 分页、截断和 Artifact 引用
  • 来源、时效和置信信息
  • 敏感字段过滤与最小披露

错误必须支持下一步决策

  • 参数错误、权限拒绝、业务冲突、暂时故障、未知故障
  • 稳定错误码、可重试性、用户安全消息、诊断关联 ID
  • 只回注模型可行动的信息，不泄露堆栈和内部拓扑

副作用是契约的一部分

  • 只读、可逆写入和不可逆操作分级
  • 是否幂等、需要何种幂等键
  • 是否需要审批、预览或二次确认
  • 执行后可用什么查询验证结果

Tool 演进要保护模型和消费者

  • 兼容新增与破坏性变更
  • Schema、语义和错误契约测试
  • 模型选择与参数生成回归
  • 双版本窗口、废弃告警和 Owner 责任