跳到主要内容

算子示例

以下示例聚焦当前工作流与智能体工具目录可使用的契约和选择模式。请把样例 URL 和字段名替换为已授权资源。

示例 1：从 REST API 读取客户​

创建一个包含只读方法的 REST API 算子：

{
  "name": "getCustomer",
  "description": "按准确的平台客户 ID 读取一位客户",
  "inputSchema": {
    "type": "object",
    "required": ["customerId"],
    "properties": {
      "customerId": { "type": "string", "minLength": 1 }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": ["found"],
    "properties": {
      "found": { "type": "boolean" },
      "customer": {
        "type": ["object", "null"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "status": { "type": "string" }
        }
      }
    }
  }
}

把 customerId 映射到 URL Path，并把远端 404 映射为 { "found": false, "customer": null }。认证保存在托管连接中。该方法只读，因此对临时网络错误进行短重试通常是安全的。

示例 2：安全创建外部工单​

写方法应开放幂等值：

{
  "name": "createSupportTicket",
  "description": "用户批准后创建一张支持工单",
  "inputSchema": {
    "type": "object",
    "required": ["title", "description", "idempotencyKey"],
    "properties": {
      "title": { "type": "string", "minLength": 1 },
      "description": { "type": "string", "minLength": 1 },
      "priority": { "type": "string", "enum": ["LOW", "MEDIUM", "HIGH"] },
      "idempotencyKey": { "type": "string", "minLength": 8 }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": ["ticketId", "status"],
    "properties": {
      "ticketId": { "type": "string" },
      "status": { "type": "string" },
      "created": { "type": "boolean" }
    }
  }
}

作为智能体工具开放时要求确认。把 idempotencyKey 传给远端服务；无论新建还是复用工单，都返回稳定 ticket ID。

示例 3：选择正确的数据集操作​

假设候选人数据集包含 id、name、education_level、work_experience 和已配置向量字段。

问题操作原因
“打开候选人 ID 42”使用类型化 ids 的结构化查询已知准确身份
“数据集中有多少条记录？”计数精确总数，不依赖记录分页
“查找陈思远”全文搜索或精确字段查询字面姓名
“谁有可迁移的海上建设经验？”向量搜索概念性且可能跨语言

向量搜索应同时请求身份和证据字段：

{
  "text": "海上建设、安全系统、重型工程和可迁移项目经验",
  "limit": 20,
  "outputFields": [
    "id",
    "name",
    "current_location",
    "work_experience",
    "project_experience"
  ]
}

推荐人员前必须检查返回经历。Top-K 不等于业务资格。如果输出字段不在数据集 Schema 中，执行前应删除或替换。

示例 4：在 WorkflowStudio 连接算子​

客户升级工作流可以这样设计：

  1. 手动或事件触发器接收 customerId 和 issue。
  2. getCustomer 返回客户和 found 标记。
  3. If/Else 节点在 found 为 false 时返回明确结果并停止。
  4. 任务型智能体按严格输出 Schema 分类严重程度。
  5. createSupportTicket 只在已批准分支运行。
  6. 最终 Transform 节点返回 ticketId、status 和分类结果。

测试找到、未找到、低优先级、高优先级、重复事件、远端失败和超时路径。

示例 5：渲染智能体工具结果​

Chat 执行过程应保留结构化结果：

if (event.type === 'tool.execution') {
  const metadata = event.metadata ?? {};
  renderToolActivity({
    name: String(metadata.toolName ?? 'Tool'),
    arguments: metadata.arguments,
    result: metadata.result,
    error: metadata.error,
    pluginId: metadata.pluginId,
  });
}

不要把结果替换成一句“工具已完成”。已注册插件可以渲染专属卡片，同时保留原始结构化值供检查。

相关指南​