# 获取智能体调用信息

调用智能体前，先读取 Agent Card。它是智能体提供的调用说明，包含名称、协议版本、输入输出类型和流式能力等信息；它不是智能体的实时运行状态。

## 前提条件

- 已准备 Product API Base URL、个人访问令牌和工作区 ID。
- 已取得目标智能体的 `agent_id` 或 `agent_code`。二者选择一个即可。

```bash
export PRODUCT_API_BASE_URL='<Product API Base URL ending in /newmoi>'
export PRODUCT_API_KEY='<your-personal-access-token>'
export WORKSPACE_ID='<workspace-id>'
export AGENT_ID='<agent-id>'
```

## 获取调用信息

以下示例使用智能体 ID：

```bash
curl --get "$PRODUCT_API_BASE_URL/agents/card" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Accept: application/json" \
  --data-urlencode "agent_id=$AGENT_ID"
```

也可以将查询参数改为 `agent_code=<AGENT_CODE>`。不要同时省略 `agent_id` 和 `agent_code`。

| 查询参数 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `agent_id` | string | 与 `agent_code` 二选一 | 智能体 ID。调用工作区内已知智能体时优先使用稳定 ID。 |
| `agent_code` | string | 与 `agent_id` 二选一 | 智能体代码。适合部署明确提供固定代码的智能体。 |
| `agent_workspace_id` | string | 否 | 智能体所属运行工作区。只有接入信息明确要求时才传递。 |

成功时，接口直接返回 Agent Card，不使用 `code/msg/data` 包络。实际字段和能力由目标智能体决定：

```json
{
  "name": "<AGENT_NAME>",
  "version": "<AGENT_VERSION>",
  "protocolVersion": "<A2A_PROTOCOL_VERSION>",
  "capabilities": {
    "streaming": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"]
}
```

| 字段 | 类型 | 返回条件 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 智能体提供时返回 | 面向用户的智能体名称，不能代替 `agent_id` 或 `agent_code`。 |
| `version` | string | 智能体提供时返回 | 当前智能体实现版本。智能体重新发布后应重新获取调用信息。 |
| `protocolVersion` | string | 智能体提供时返回 | 智能体声明的 A2A 协议版本。 |
| `capabilities.streaming` | boolean | 声明流式能力时返回 | 是否声明支持流式消息。未返回时不要默认支持。 |
| `defaultInputModes` | string[] | 智能体提供时返回 | 默认接受的内容类型。 |
| `defaultOutputModes` | string[] | 智能体提供时返回 | 默认可能返回的内容类型。 |

客户端应容忍未知扩展字段。只使用响应明确声明的能力；调用信息未声明流式支持时，先使用 `message/send`。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 返回参数错误 | `agent_id` 和 `agent_code` | 至少提供一个选择器，并去掉空字符串。 |
| 找不到智能体 | 工作区 ID、智能体 ID 或代码 | 从当前工作区重新取得智能体标识，不复用其他工作区的值。 |
| Card 与预期能力不同 | 智能体版本和当前 Card | 以当前响应为准；智能体发布新版本后清除旧缓存并重新读取。 |

## 下一步

- [发送消息并启动任务](call-agent-a2a.md)
- [查询任务状态与结果](query-task-status-results.md)