获取智能体调用说明¶

读取 Agent Card，确认目标智能体支持的 A2A 协议版本、输入输出类型和能力。

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents/{agent_id}/.well-known/agent-card.json

调用前准备¶

先查询智能体列表，选择活动智能体并记录其所属工作区。

准备具有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求示例¶

$AGENT_ID 与 $AGENT_WORKSPACE_ID 分别来自智能体列表中同一项的 id 和 workspace_id。$WORKSPACE_ID 是本次调用所在工作区，$AI_STUDIO_API_KEY 是调用凭据。

curl --get "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/.well-known/agent-card.json" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json" \
  --data-urlencode "agent_workspace_id=$AGENT_WORKSPACE_ID"

路径参数¶

参数	类型	是否必填	说明
`workspace_id`	string	是	本次调用所在工作区 ID，须与工作区请求头一致。
`agent_id`	string	是	智能体列表返回的目标智能体 ID。

查询参数¶

参数	类型	是否必填	说明
`agent_workspace_id`	string	否	智能体所属工作区；只能指定当前工作区或 `system`，省略时使用当前工作区。

选择系统助手时，将 system 填入查询参数，路径仍使用实际目标工作区。

通用入口 GET /v5/agents/card?agent_id=...&agent_workspace_id=... 也可用于读取 Card。本文示例使用工作区级入口；通用入口返回错误时，可按本页路径核对同一智能体的能力。

成功响应¶

成功时返回 Agent Card，不使用通用响应包络。以下节选工作流助手的能力声明，实际响应还包含调用地址和扩展元数据。

{
  "name": "Matrixflow 工作流助手",
  "description": "根据自然语言和已注册工作项创建 Matrixflow 工作流。",
  "version": "v1",
  "protocolVersion": "0.3.0",
  "capabilities": {
    "streaming": true,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/plain", "application/octet-stream"],
  "defaultOutputModes": ["text/plain"]
}

响应字段如下。

字段	类型	说明
`name`	string	智能体显示名称。
`description`	string	智能体说明。
`url`	string	Card 声明的 A2A 地址；工作区级响应可能包含部署内部地址，见下方说明。
`version`	string	智能体版本。
`protocolVersion`	string	A2A 协议版本。
`capabilities`	object	能力声明。
`capabilities.streaming`	boolean	是否支持流式调用。
`capabilities.pushNotifications`	boolean	是否支持推送通知；有值时返回。
`capabilities.stateTransitionHistory`	boolean	是否支持状态变更历史。
`defaultInputModes`	string[]（字符串数组）	默认输入媒体类型。
`defaultOutputModes`	string[]（字符串数组）	默认输出媒体类型。
`skills`	object[]（对象数组）	智能体声明的技能；有值时返回。
`metadata`	object	协议扩展元数据；可能包含数据分段能力。

类型后的 [] 表示数组，例如 string[] 是字符串数组。

只调用 Card 声明的能力，并兼容未知扩展字段。如果 url 返回部署内部地址，外部客户端使用由其他智能体调用给出的同一工作区级公开路径，并保留 agent_workspace_id；不要将凭据发送到内部地址。

错误响应¶

通用入口无法返回 Card 时，可返回以下错误。通用错误不足以区分具体失败原因。

{
  "code": "ErrServer",
  "data": null,
  "msg": "服务器内部错误"
}

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
500	`ErrServer`	通用入口读取或处理 Card 失败。	保存请求时间及追踪 ID，按工作区级路径核对；持续失败时检查服务日志，不仅凭该错误判断权限或模型配置。

后续操作¶

根据 capabilities，使用工作区级公开路径由其他智能体调用。仅在 Card 声明支持时使用流式调用或其他扩展能力。

最后更新于 2026 年 9 月 28 日