API开放平台

TIP

#AI Agent 相关接口

# AI Agent 工作流运行接口

请求方式： POST（HTTPS）
请求地址： https://openapi.qince.com/api/ai_agent/v1/workflowRun/{ openid }/{ timestamp }/{ digest }/{ msg_id } 在线调试
请求示例：

{
  "agentId": "123456789",
  "traceId": "1",
  "source": "web",
  "payload": {
    "text": [
      {
        "key": "code",
        "value": "320105"
      }
    ]
  }
}
说明： 本示例仅供参考，具体以参数说明为准。

参数说明：

参数 类型 必填 说明
agentId String 是 Agent ID，用于标识要执行的工作流 Agent
traceId String 否 追踪 ID，用于请求链路追踪，默认为空
source String 否 请求来源，如 web、api 等，默认为空
payload Object 否 工作流执行所需的业务数据，格式为 JSON 对象，具体结构根据工作流定义而定

响应示例：

{
  "return_code": "0",
  "return_msg": "成功",
  "msg_id": "{ msg_id }",
  "response_data": "<<DATA>>"
}

数据 DATA 示例（成功时）:

{
  "analysisDuration": 5.856,
  "analysisNo": "7245648139254996170",
  "requestlime": "2025-12-16 17:10:42",
  "result": "根据当前天气情况（建邺区，中国江苏省南京市），以下是穿衣建议：\n\n### **天气核心信息**\n- **天气现象**：晴  \n- **温度**：当前17℃，体感温度16℃  \n- **风向/风力**：西北风1级  \n- **湿度**：27%（干燥）  \n- **紫外线指数**：0（无紫外线辐射）  \n- **云量**：0%（晴朗无云）  \n\n\n### **穿衣建议**\n#### **1. 温度与体感**  \n当前温度17℃，体感接近16℃，属于**凉爽舒适**区间，适合穿**薄外套+单衣**组合。\n\n#### **2. 具体搭配**  \n- **上衣**：  \n  - 内搭：长袖T恤、薄针织衫或卫衣（材质可选纯棉、羊毛混纺）。  \n  - 外搭：轻便风衣、牛仔外套、薄款西装或短款夹克（防风保暖，早晚温差小但风感明显）。  \n- **下装**：  \n  - 长裤：牛仔裤、休闲裤或薄款西装裤（避免短裤，早晚微凉）。  \n  - 裙装：若偏好裙装，可搭配薄款长袜+过膝裙，或选择加绒裤袜。  \n- **鞋子**：  \n  - 运动鞋、短靴或乐福鞋（舒适为主，无需厚重棉鞋）。  \n- **配件**：  \n  - 围巾/帽子：可选防风薄围巾（西北风1级，微风感），帽子非必需，晴天可备遮阳帽。  \n  - 防晒：紫外线指数0，无需防晒用品，但晴天可备墨镜防强光。  \n\n\n### **注意事项**  \n- **干燥环境**：湿度仅27%，皮肤易干燥，建议随身携带保湿护肤品。  \n- **昼夜温差**：南京冬季早晚温差较小（当前体感16℃，夜间可能降至10℃左右），若夜间外出，可加一件厚外套。  \n- **空气质量**：AQI 60（良好），PM2.5 34，户外活动无需佩戴口罩。  \n\n\n**总结**：以"**薄外套+长袖内搭+长裤**"为核心，兼顾保暖与透气，适合日常通勤、散步或轻度户外活动。"
}

数据 DATA 说明：

当 agent 接口返回 HTTP 200 状态码时，response_data 字段包含 agent 接口返回的内层 data 对象，其结构如下：

参数 类型 说明
analysisDuration Number 分析耗时（秒）
analysisNo String 分析编号，唯一标识本次分析
requestlime String 请求时间，格式：yyyy-MM-dd HH:mm:ss
result String 工作流执行结果内容，具体格式根据工作流定义而定

响应参数说明：

参数 类型 说明
return_code String 返回码，0 表示成功，1 表示失败
return_msg String 返回消息，描述请求处理结果
msg_id String 消息 ID，与请求中的 msg_id 一致
response_data String 响应数据，JSON 字符串格式。当 HTTP 状态码为 200 时，包含 agent 接口返回的内层 data 对象；失败时包含完整的错误响应信息

错误码说明：

错误码 说明
0 请求成功
1 请求失败，具体错误信息见 return_msg

常见错误：

错误信息 说明 解决方案
传参格式错误，请求体必须是有效的 JSON 格式！ 请求体不是有效的 JSON 格式 检查请求体格式，确保是有效的 JSON 字符串
参数错误：agentId 不能为空！ agentId 参数缺失或为空 在请求体中添加 agentId 参数
系统配置错误：APPSVR_URL 未配置！ 系统配置缺失 联系系统管理员检查配置
调用 agent 接口失败，状态码: XXX 调用下游 agent 接口失败 检查 agent 接口服务状态，查看详细错误信息
调用 agent 接口异常：XXX 调用过程中发生异常 查看日志获取详细异常信息

接口说明：

  1. 本接口用于调用 AI Agent 工作流执行服务，根据提供的 agentId 执行对应的工作流。
  2. 请求体中的 payload 字段结构根据具体的工作流定义而定，请参考对应工作流的文档。
  3. 接口会转发请求到 agent 服务，当 HTTP 状态码为 200 时，会自动提取 agent 服务返回的内层 data 对象并返回在 response_data 字段中，避免双层嵌套结构。
  4. 建议在生产环境中为 traceId 设置唯一值，便于问题追踪和日志查询。

← 企业群发相关接口 →