查询组织智能体列表
接口介绍
接口路径:POST /api/V1/open-portal/app/linksoul/agent-faces/agent-list
查询组织(租户)下全部 NORMAL(非模板)智能体的摘要列表,用于在人脸绑定前选择目标智能体。
- 返回每个智能体的基本信息、创建人、同步状态与已绑定设备 SN;未绑定设备的智能体
syncStatus为UNBIND、snList为空。 - 支持按创建人、智能体编码、状态(缺省 NORMAL)、产品型号、同步状态精确筛选,多个条件为 AND。
- 操作者用户 ID 由平台网关注入
X-App-User-Id,调用方不要自行设置;服务端校验操作者为租户管理员。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tenant_id | integer (int64) | 是 | 目标租户 ID,必须与操作者租户匹配 |
| operator_id | string | 否 | 按创建人用户 ID 精确筛选 |
| agent_code | string | 否 | 按智能体编码精确筛选 |
| status | string | 否 | 按状态精确筛选;缺省 NORMAL |
| bot_version | string | 否 | 按产品型号精确筛选,如 X2、A3 |
| sync_status | string | 否 | 按同步状态筛选:UNBIND / BINDING / FAILED / SUCCESS |
| page | integer | 否 | 页码,从 1 开始;缺省 1 |
| page_size | integer | 否 | 每页条数;缺省 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}'
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 状态码,成功为 0 |
| message | string | 错误提示;成功时为 success |
| data | object | 分页结果:total(总数)/ page(当前页)/ pageSize(每页条数)/ list(本页智能体摘要数组) |
| data.id | integer (int64) | 智能体 ID |
| data.gmtCreate | string | 创建时间 |
| data.gmtModified | string | 最后修改时间 |
| data.tenantId | string | 租户 ID |
| data.agentCode | string | 智能体编码 |
| data.agentName | string | 智能体名称 |
| data.version | string | 智能体版本 |
| data.status | string | 状态,本接口只返回 NORMAL |
| data.botVersion | string | 产品型号,如 X2、A3 |
| data.description | string | 智能体介绍 |
| data.operatorId | string | 创建人用户 ID |
| data.operatorName | string | 创建人姓名 |
| data.syncStatus | string | 同步状态;未绑定设备时为 UNBIND |
| data.snList | array 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缺失或与操作者租户不匹配。- 操作者不是租户管理员。