跳到主要内容

算子最佳实践

可靠算子应具有单一职责、明确契约、安全重试、最小权限和可观察结果。

一个方法只做一项操作​

优先使用 getCustomer、listInvoices 和 createTicket，不要使用笼统的 runOperation。职责聚焦的方法更容易在工作流中映射，也更容易被智能体正确选择。

Runtime 工具目录中的名称必须唯一。即使内部注册键不同，重复工具名也会让模型选择和结果渲染产生歧义。

设计类型化契约​

  • 使用稳定业务 ID。
  • 真正必需的字段才设为必填。
  • 定义数组 Item 和嵌套对象。
  • 封闭取值集合使用 Enum。
  • 说明单位、时区、格式和值含义。
  • 严格操作应拒绝未知字段。
  • 返回稳定 ID 和类型化事实。

不要只返回展示文案。界面可以格式化结构化数据，但下游节点无法可靠解析一句话。

明确表达空结果​

只读操作没有匹配不是执行错误，应返回明确状态：

{
  "success": true,
  "results": [],
  "total": 0
}

请求失败应返回或抛出独立错误，并包含安全 Code 与消息。明确区分可避免智能体在工具没有数据时声称已经找到结果。

让写操作具有幂等性​

重试可能重复发送邮件、支付、工单或新增记录。对有重要后果的写操作：

  • 接收或派生幂等键；
  • 记录生成的资源 ID；
  • 重放时复用，不执行第二次写入；
  • 交互调用时要求确认；
  • 参数或授权失败不重试。

有意设置超时与重试​

  • 算子超时必须位于任务或轮次预算内。
  • 只重试临时错误。
  • 使用有边界的退避，不要立即循环。
  • 对重复警告进行频率限制。
  • 在错误中保留 execution/request ID。
  • Runtime 和供应商支持时，取消远端工作。

保护 Secret 与数据​

  • 凭据保存在托管连接或 Secret 中。
  • 对空间和远端系统实施最小权限。
  • 日志中屏蔽敏感输入输出。
  • 不记录完整简历、文档、API Header 或包含数据的 curl 命令。
  • 只返回调用方需要且有权查看的字段。
  • 渲染工具结果时按不可信内容处理。

支持智能体选择工具​

面向智能体的描述应回答：

  1. 工具执行哪项准确操作？
  2. 什么情况下应该选择？
  3. 什么情况下应选择其他工具？
  4. 必须提供哪些 ID 或证据？
  5. 空结果意味着什么？

数据集工具必须保持以下边界：

  • 结构化查询用于精确类型条件和 ID；
  • 计数用于精确总数；
  • 全文搜索用于字面文本；
  • 向量搜索用于概念、相似性和跨语言匹配。

不要把某个行业的词汇写成全局 Runtime 规则。行业专属选择指导应放在对应智能体或解决方案模板中。

保持结果可观察​

在执行过程中展示状态、时长、安全参数、结构化结果和错误详情。应用插件可以提供更丰富卡片，但不能丢弃底层算子结果。

异步操作应展示进度和最终资源/执行 ID。如果没有真正创建后台 Job，不要把“处理中”作为最终成功结果。

测试契约边界​

测试范围不能只有成功路径：

  • 必填与可选输入；
  • 错误类型和额外字段；
  • 空结果与多条结果；
  • Unicode 和区域文本；
  • 大型嵌套值；
  • 无权访问资源；
  • 连接失败、限流、超时和取消；
  • 安全重试与重复写；
  • 工作流映射和智能体工具渲染。

修改契约后，必须运行引用它的工作流和智能体。Helper 单元测试不能替代端到端契约测试。

版本变更​

优先增加可选字段。破坏性变更应创建新 Identifier 或方法，迁移并验证调用方后，再停用原契约。不要悄悄改变已有字段含义。

评审清单​

  • 名称唯一且动作明确
  • 适用范围说明清楚
  • 输入输出 Schema 类型明确
  • 空结果表达明确
  • 连接与空间权限最小化
  • 超时、重试与幂等行为安全
  • 日志不包含敏感值
  • 工作流与 Chat 能看到结构化结果
  • 覆盖成功、错误、空结果、重复和取消测试
  • 启用前已完成调用方回归

相关指南​