# 查询智能体和团队目录卡片

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

读取可浏览目录中的智能体与团队展示条目，用于选择后续操作对象。本接口不返回单个智能体的 A2A Agent Card。

```text
GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-cards
```

## 调用前准备

`PRODUCT_API_BASE_URL` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

PRODUCT_API_BASE_URL 包含目标环境的产品前缀。准备本人的凭据与有权限的 WORKSPACE_ID，路径 ID 和 X-Workspace-ID 必须一致。示例 ID 需替换为该环境的实际返回值。

## 请求

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

```bash
curl --get "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-cards" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "catalog=workspace" \
  --data-urlencode "query=$SEARCH_TEXT" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"
```

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

| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| catalog | string | 否 | workspace 读取当前工作区智能体与团队，system 读取系统智能体；省略时合并可浏览来源。 |
| query | string | 否 | 名称等展示信息的检索条件。不要改成 keyword。 |
| include_development | boolean | 否 | true 或 1 时允许系统智能体开发态定义参加目录筛选；省略为 false，不是跳过授权。 |
| limit | integer | 否 | 默认 50；小于等于 0 使用默认，大于 200 限为 200。 |
| offset | integer | 否 | 默认 0，负值归为 0。 |

kind 决定后续是智能体还是团队操作；workspace_id 是该条目的来源工作区，可能为 system，不能一律替换成当前工作区。

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

## 成功响应

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

```json
{"code":0,"data":{"items":[{"kind":"agent","id":"agent-example","workspace_id":"system","name":"示例智能体","status":"active","version":1,"updated_at":"2026-11-12T01:02:03Z","actions":["chat","connect_im","api_invoke","create_scheduled_task"],"requires_agent_model":true}],"total":1,"limit":20,"offset":0}}
```

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.items | array | 本页目录卡片。 |
| data.items[].kind | string | agent 或 team。 |
| data.items[].id | string | 对应类型的对象 ID。 |
| data.items[].workspace_id | string | 对象来源工作区；与 kind、id 一起保留。 |
| data.items[].name | string | 本次语言下的展示名称。 |
| data.items[].description | string | 可选描述。 |
| data.items[].avatar_ref | string | 可选头像引用。 |
| data.items[].status | string | 条目状态。当前目录按 active 选取。 |
| data.items[].version | integer | 可选的智能体版本；团队条目不保证有此字段。 |
| data.items[].updated_at | string | 最近更新时间。 |
| data.items[].actions | string[] | 目录展示的动作标识，不替代具体动作的授权或成功结果。 |
| data.items[].requires_agent_model | boolean | 可选；true 表示还需准备智能体模型。省略或 false 不保证全部运行条件已经满足。 |
| data.total | integer | 本次来源和筛选范围的条目总数，不是本页条数。 |
| data.limit | integer | 实际页上限。 |
| data.offset | integer | 当前偏移量。 |

展示语言以本次 Content-Language 和实际返回为准。按 updated_at 降序，时间相同时按 kind、workspace_id、id 排序；分页期间目录变化可能导致跨页变化。

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

## 翻页与继续

保持筛选条件，用返回的 limit 增加 offset；offset + limit >= total 时结束。下面仅在上一页实际 limit 为 20 且 total 大于 20 时读取下一页：

```bash
curl --get "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-cards" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "catalog=workspace" \
  --data-urlencode "query=$SEARCH_TEXT" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=20"
```

agent 条目继续获取该智能体的 A2A 调用信息；team 条目使用团队接口，不能直接把团队 ID 传给智能体 A2A。actions 是展示参考，具体调用仍重新校验身份、角色和资源条件。

## 错误

来源分类无效等输入可返回 HTTP 400；身份、授权、依赖或读取失败按实际响应处理。此动作的普通领域错误使用数值 code/message/details，授权层也可能使用字符串 code；不强行把所有错误归成同一种包装。读取失败时没有可供继续分页的成功页。
