跳到主要内容

自定义算子

当前没有内置算子或数据源操作能够完成所需外部动作时，可以创建自定义算子。当前用户可用的自定义 Runtime 是 REST API；OpenAPI 导入会从已有契约生成 REST API 算子方法。

创建前检查​

先检查已启用的算子目录。已有内置算子能够完成需求时应优先复用，因为平台会维护其实现、修复和 Runtime 集成。

以下情况适合创建自定义 REST API 算子：

  • 业务系统提供 HTTPS API；
  • 操作具有稳定输入输出契约；
  • 凭据可以存入托管连接或 Secret；
  • 已经明确超时、重试和幂等行为。

不要把算子当作存放任意脚本或凭据的位置。

手动创建​

  1. 打开控制台 → 算子并选择创建。
  2. 填写唯一 Identifier、名称、描述、分类和标签。
  3. 选择 REST API 执行类型。
  4. 配置 Server URL 和认证连接。
  5. 每个外部操作创建一个方法。
  6. 为各方法定义输入和输出 Schema。
  7. 将类型化输入映射到 HTTP Path、Query、Header 和 Body。
  8. 配置超时与安全重试。
  9. 测试方法后再启用。

测试与生产端点应放在环境配置中，使不同环境使用同一份算子契约。

导入 OpenAPI​

远端服务已有持续维护的 OpenAPI 文档时，可以使用 OpenAPI 导入。

  1. 选择 URL 导入或受支持的文件上传。
  2. 选择需要导入的 Operation。
  3. 检查生成的算子 Identifier 和方法名。
  4. 验证 Server URL、Content Type、参数、请求体、响应 Schema 和认证。
  5. 删除用户不应调用的方法和字段。
  6. 使用代表性响应测试后再启用。

导入只是起点，并不能证明外部 API 安全或兼容。生成的描述通常需要补充业务语义，让工作流作者和智能体能够选择正确方法。

详见 OpenAPI 支持。

认证与 Secret​

  • 优先使用托管连接、ConfigMap Secret 或环境引用。
  • 不要在 Header、默认值、示例或导出定义中硬编码 Token。
  • 远端凭据只授予必需范围。
  • 日志中屏蔽敏感输入和输出。
  • 应能在不修改算子 Schema 的情况下轮换凭据。

测试矩阵​

启用前至少覆盖：

场景预期行为
有效请求返回结构化成功结果
有效请求但无数据明确空结果，不作为错误
输入缺失或无效远端调用前返回校验错误
凭据无效明确授权错误，不泄漏 Secret
远端 4xx最终业务或请求错误
远端 5xx/网络中断仅在已配置且安全时重试
超时有边界地失败并提供诊断元数据
重复写请求返回幂等结果或明确防重

随后把算子加入测试工作流，验证映射、日志、重试和下游输出。

启用与开放​

启用算子后，它才有资格进入已授权产品目录，但不会自动向所有智能体开放。作为智能体工具使用时，还要确保工具定义、智能体配置、Chat 模式、本地 Provider 和空间权限均允许。

有重要后果的写操作应要求确认，并返回受影响资源 ID 与状态。读操作应返回结构化记录，并在适用时明确总数或空结果。

变更管理​

算子 Schema 应按 API 契约管理。增加可选字段通常比重命名字段或改变已有字段类型安全。必须进行破坏性变更时：

  1. 创建新的方法或算子 Identifier；
  2. 更新并测试所有工作流和智能体调用方；
  3. 启用新契约；
  4. 确认旧契约使用量为零后再停用。

相关指南​