# 查询引用知识库的智能体

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

按当前身份可见范围，查看有效绑定中引用该知识库的智能体。

```text
GET https://api.moi.matrixorigin.cn/v5/semantic-models/{model_id}/referencing-agents
```

## 调用前准备

准备当前工作区凭据及相应资源权限。变量、导入文件和操作边界见[公共说明](objects.md)。

## 查询参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X GET "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/referencing-agents" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --get \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=${NEXT_CURSOR:-}"
```

:::::
:::::{tab-item} 参数说明

服务合并当前工作区与系统智能体定义及工作区绑定覆盖，再按当前身份过滤；接口不返回归档智能体。实际 limit 以响应为准；权限投影无可见候选时早返回分支可能为 0。按 next_cursor 推进，不以 items 为空或少于 limit 判断完成：归档过滤在分页之后，可能产生空的中间页。结果不含总数，不能当作全局无人引用或删除安全的证明。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model_id` | integer | 路径必填 | 当前工作区正整数知识库 ID；先检查模型读取权限与存在性。 |
| `limit` | integer | 否 | 默认 50；显式提供须为正整数，超过 200 时取 200。 |
| `cursor` | string | 否 | 上一页 next_cursor；第一页省略或为空，不能跨工作区或资源复用。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [],
    "limit": 50
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应信息。 |
| `data` | object | 当前动作结果；单对象导入时直接为知识库对象。 |
| `data.items` | object[] | 本页可见且未归档的引用智能体。 |
| `data.items[].id` | string | 智能体 ID。 |
| `data.items[].workspace_id` | string | 智能体定义所属工作区，可能与当前查询工作区不同。 |
| `data.items[].name` | string | 名称。 |
| `data.items[].description` | string | 描述。 |
| `data.items[].status` | string | 智能体状态。 |
| `data.items[].updated_at` | string | RFC 3339 时间。 |
| `data.items[].knowledge_base_count` | integer | 该智能体当前有效绑定中的知识库引用数，不是本查询全局引用总数。 |
| `data.limit` | integer | 实际页大小。 |
| `data.next_cursor` | string | 存在且非空时继续同一资源；结束时可省略。 |

:::::
::::::
:::::::

## 错误响应

分别检查 HTTP、业务码与目标资源。按[错误与环境](objects.md#错误与环境)保留请求信息并回查。
