# 获取智能体调用说明

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

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

## 调用前准备

先[查询智能体列表](../agents/list-agents.md)，选择活动智能体并记录其所属工作区。

准备具有目标工作区访问权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。

## 请求示例

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

```bash
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，不使用通用响应包络。以下节选工作流助手的能力声明，实际响应还包含调用地址和扩展元数据。

```json
{
  "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` 返回部署内部地址，外部客户端使用[由其他智能体调用](call-agent-from-agent.md)给出的同一工作区级公开路径，并保留 `agent_workspace_id`；不要将凭据发送到内部地址。

## 错误响应

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

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1

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

## 后续操作

根据 `capabilities`，使用工作区级公开路径[由其他智能体调用](call-agent-from-agent.md)。仅在 Card 声明支持时使用流式调用或其他扩展能力。