查询智能体和团队目录卡片¶
读取可浏览目录中的智能体与团队展示条目,用于选择后续操作对象。本接口不返回单个智能体的 A2A Agent Card。
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 需替换为该环境的实际返回值。
请求¶
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"
查询参数 |
类型 |
必填 |
说明 |
|---|---|---|---|
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,不能一律替换成当前工作区。
成功响应¶
{"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}}
字段 |
类型 |
说明 |
|---|---|---|
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 时读取下一页:
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;不强行把所有错误归成同一种包装。读取失败时没有可供继续分页的成功页。