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

读取可浏览目录中的智能体与团队展示条目,用于选择后续操作对象。本接口不返回单个智能体的 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;不强行把所有错误归成同一种包装。读取失败时没有可供继续分页的成功页。

最后更新于