获取智能体调用信息¶

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

前提条件¶

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

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：

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 包络。实际字段和能力由目标智能体决定：

{
  "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	以当前响应为准；智能体发布新版本后清除旧缓存并重新读取。

下一步¶

最后更新于 2026 年 8 月 14 日