查询组织智能体列表

接口介绍

接口路径:POST /api/V1/open-portal/app/linksoul/agent-faces/agent-list

查询组织(租户)下全部 NORMAL(非模板)智能体的摘要列表,用于在人脸绑定前选择目标智能体。

  • 返回每个智能体的基本信息、创建人、同步状态与已绑定设备 SN;未绑定设备的智能体 syncStatus 为 UNBIND、snList 为空。
  • 支持按创建人、智能体编码、状态(缺省 NORMAL)、产品型号、同步状态精确筛选,多个条件为 AND。
  • 操作者用户 ID 由平台网关注入 X-App-User-Id,调用方不要自行设置;服务端校验操作者为租户管理员。

请求参数

字段类型必填说明
tenant_idinteger (int64)是目标租户 ID,必须与操作者租户匹配
operator_idstring否按创建人用户 ID 精确筛选
agent_codestring否按智能体编码精确筛选
statusstring否按状态精确筛选;缺省 NORMAL
bot_versionstring否按产品型号精确筛选,如 X2、A3
sync_statusstring否按同步状态筛选:UNBIND / BINDING / FAILED / SUCCESS
pageinteger否页码,从 1 开始;缺省 1
page_sizeinteger否每页条数;缺省 10,最大 100

调用示例

签名方式同获取上传地址:请求头携带 X-App-Id、X-App-Key、X-Timestamp、X-Nonce、X-Signature。

下方命令可直接复制运行:替换凭证后先跑一次即可验证连通性(在线调试),再按「请求参数」修改 -d 内容调试其它入参。

bash
APP_ID="app_xxxxxxxx"; APP_KEY="ak_xxxxxxxx"; APP_SECRET="sk_xxxxxxxx"
BASE_URL="https://open.agibot.com"
API_PATH="/api/V1/open-portal/app/linksoul/agent-faces/agent-list"

TS_MS=$(( $(date +%s) * 1000 ))
NONCE="$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')"
SIGNATURE=$(printf 'POST\n%s\n%s\n%s' "$API_PATH" "$TS_MS" "$NONCE" \
  | openssl dgst -sha256 -hmac "$APP_SECRET" | sed 's/^.* //')

curl -sS -X POST "$BASE_URL$API_PATH" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: $APP_ID" \
  -H "X-App-Key: $APP_KEY" \
  -H "X-Timestamp: $TS_MS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE" \
  -d '{"tenant_id": 12345}'

返回参数

字段类型说明
codeinteger状态码,成功为 0
messagestring错误提示;成功时为 success
dataobject分页结果:total(总数)/ page(当前页)/ pageSize(每页条数)/ list(本页智能体摘要数组)
data.idinteger (int64)智能体 ID
data.gmtCreatestring创建时间
data.gmtModifiedstring最后修改时间
data.tenantIdstring租户 ID
data.agentCodestring智能体编码
data.agentNamestring智能体名称
data.versionstring智能体版本
data.statusstring状态,本接口只返回 NORMAL
data.botVersionstring产品型号,如 X2、A3
data.descriptionstring智能体介绍
data.operatorIdstring创建人用户 ID
data.operatorNamestring创建人姓名
data.syncStatusstring同步状态;未绑定设备时为 UNBIND
data.snListarray of string已绑定设备的 SN;未绑定设备时为空

返回示例

json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "pageSize": 10,
    "list": [
      {
      "id": 6061,
      "gmtCreate": "2026-10-30T17:48:15.000+08:00",
      "gmtModified": "2026-10-30T17:49:01.000+08:00",
      "tenantId": "111664713323618",
      "agentCode": "AI_AGENT_0b78c048",
      "agentName": "x2智能体测试",
      "version": "1.0.0",
      "status": "NORMAL",
      "botVersion": "X2",
      "description": "test",
      "operatorId": "111664713207929",
      "operatorName": "13051562119",
      "syncStatus": "UNBIND",
      "snList": []
      }
    ]
  }
}

常见错误

  • tenant_id 缺失或与操作者租户不匹配。
  • 操作者不是租户管理员。