<span id="查询智能体和团队目录卡片"></span>

# List agent and team catalog cards

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

Read browsable agent and team entries to choose targets for subsequent operations. This API does not return an individual agent's A2A Agent Card.

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

<span id="调用前准备"></span>

## Before you call this API

Set `PRODUCT_API_BASE_URL` to the product API prefix `https://api.moi.matrixorigin.cn/v5`; use the corresponding product API URL for a dedicated deployment.

PRODUCT_API_BASE_URL includes the product prefix for the target environment. Prepare your credentials and an authorized WORKSPACE_ID. The path ID must match X-Workspace-ID. Replace example IDs with actual values returned in that environment.

<span id="请求"></span>

## Request

:::::::{div} mo-api-tabs mo-api-request-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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} Parameters

| Query parameter | Type | Required | Description |
| --- | --- | --- | --- |
| catalog | string | No | workspace reads agents and teams in the current workspace; system reads system agents. Omission combines browsable sources. |
| query | string | No | Search condition for display information such as names. Do not rename it to keyword. |
| include_development | boolean | No | true or 1 includes development definitions of system agents in catalog filtering. Defaults to false when omitted; this does not bypass authorization. |
| limit | integer | No | Defaults to 50. Values at or below 0 use the default; values above 200 are capped at 200. |
| offset | integer | No | Defaults to 0; negative values become 0. |

kind determines whether subsequent operations target an agent or a team. workspace_id is the entry's source workspace and may be system; do not always replace it with the current workspace.

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

| Field | Type | Description |
| --- | --- | --- |
| data.items | array | Catalog cards on this page. |
| data.items[].kind | string | agent or team. |
| data.items[].id | string | Object ID for the corresponding kind. |
| data.items[].workspace_id | string | Object source workspace; retain it together with kind and id. |
| data.items[].name | string | Display name in the current language. |
| data.items[].description | string | Optional description. |
| data.items[].avatar_ref | string | Optional avatar reference. |
| data.items[].status | string | Entry status. The current catalog selects active entries. |
| data.items[].version | integer | Optional agent version; team entries do not guarantee this field. |
| data.items[].updated_at | string | Most recent update time. |
| data.items[].actions | string[] | Action identifiers shown in the catalog. They do not replace authorization or establish success for specific actions. |
| data.items[].requires_agent_model | boolean | Optional. true means an agent model must still be prepared. Omission or false does not guarantee that all runtime prerequisites are satisfied. |
| data.total | integer | Total entries for the selected sources and filters, not the number on this page. |
| data.limit | integer | Effective page limit. |
| data.offset | integer | Current offset. |

Display language follows the current Content-Language and actual response. Results sort by updated_at descending, then by kind, workspace_id, and id for ties. Catalog changes during pagination may affect subsequent pages.

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

<span id="翻页与继续"></span>

## Paginate and continue

Keep the same filters and increase offset by the returned limit. Stop when offset + limit >= total. The following reads the next page only if the preceding page actually returned limit 20 and total greater than 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"
```

For an agent entry, retrieve that agent's A2A invocation information. For a team entry, use team APIs; do not pass a team ID directly to agent A2A. actions is a display reference. Each invocation revalidates identity, roles, and resource conditions.

<span id="错误"></span>

## Errors

Invalid input such as an unsupported source category can return HTTP 400. Handle identity, authorization, dependency, and read failures according to the actual response. Ordinary domain errors for this action use numeric code/message/details; the authorization layer may use a string code. Do not assume one uniform envelope for all errors. A failed read provides no successful page from which to continue pagination.
