# 获取智能体调用说明

读取 Agent Card，确认目标智能体支持的 A2A 协议版本、调用地址、输入输出类型和能力。常规智能体必须使用 `agent_id`；通用入口只为受支持的内置智能体代码处理 `agent_code`。

```text
GET https://moi.matrixorigin.cn/newmoi/agents/card
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌、目标工作区 ID，以及要查询的智能体 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$AGENT_ID`：目标智能体 ID，通过查询参数 `agent_id` 传递。

## 查询参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `agent_id` | string | 常规查询时是 | 目标智能体 ID。 |
| `agent_code` | string | 否 | 受支持的内置智能体代码。不能作为普通智能体 ID 的替代。 |
| `agent_workspace_id` | string | 否 | 目标智能体所属工作区 ID。未提供时使用当前工作区；只能指定当前工作区或系统工作区。 |

## 请求示例

```bash
curl --get "https://moi.matrixorigin.cn/newmoi/agents/card" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json" \
  --data-urlencode "agent_id=$AGENT_ID"
```

## 成功响应

成功时返回 `200` 和 Agent Card。响应不使用通用 `code`、`message`、`data` 包络。客户端应只调用 Card 明确声明的能力，并兼容未知扩展字段。

```json
{
  "name": "销售分析助手",
  "description": "用于销售数据分析",
  "url": "https://moi.matrixorigin.cn/newmoi/agents/a2a",
  "version": "1.0.0",
  "protocolVersion": "0.3.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "defaultInputModes": ["text/plain", "application/octet-stream"],
  "defaultOutputModes": ["text/plain"],
  "skills": []
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `name` | string | 智能体显示名称。 |
| `description` | string | 智能体说明；未设置时可能为空。 |
| `url` | string | 此智能体的 A2A 调用地址。 |
| `version` | string | 智能体版本。 |
| `protocolVersion` | string | A2A 协议版本。 |
| `capabilities` | object | 能力声明。 |
| `capabilities.streaming` | boolean | 是否支持流式调用。 |
| `capabilities.pushNotifications` | boolean | 是否支持推送通知。 |
| `capabilities.stateTransitionHistory` | boolean | 是否支持状态变更历史。 |
| `defaultInputModes` | string（字符串数组） | 默认输入媒体类型。 |
| `defaultOutputModes` | string（字符串数组） | 默认输出媒体类型。 |
| `skills` | object（对象数组） | 智能体声明的技能。每项的字段由 A2A Agent Card 定义。 |
| `metadata` | object | 协议扩展元数据；可能包含平台声明的数据分段能力。 |

## 错误响应

无法生成 Agent Card 时，接口返回通用错误包络。

```json
{
  "code": "ErrParamInvalid",
  "msg": "agent_code or agent_id is required",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 未提供 `agent_id` 或受支持的 `agent_code`，或者选择器格式无效。
  - 提供有效选择器和工作区请求头。
* - `500`
  - `ErrServer`
  - 目标智能体不存在、不可用，或服务端无法生成 Agent Card。
  - 检查智能体 ID 和运行状态；确认无误后稍后重试。
```

## 后续操作

根据 `capabilities` 和 `url` 调用[由其他智能体调用](call-agent-from-agent.md)；仅在 Card 声明支持时使用流式调用或其他扩展能力。