Agent 卡片¶

Agent 卡片是调用 Agent 前的发现文档。它描述 Agent 的名称、协议版本、输入输出模式和可用能力，适合用于连接检查、能力协商和客户端功能开关，不应被当作 Agent 的运行状态。

获取 Card¶

使用 agent_code 或 agent_id 选择一个 Agent：

GET /newmoi/agents/card?agent_code=explore HTTP/1.1
Host: <moi-host>
moi-key: <api-key>
Accept: application/json

如果服务端为该 Agent 分配了 Agent 工作区，再增加 agent_workspace_id 查询参数。调用身份仍需携带正常的 MOI 认证和工作区上下文。

下面的 Python 示例故意使用 requests，而不是 moi.RawClient.get_json。当前官方 Python SDK 的 JSON helper 会按 Catalog envelope 解包，而此接口直接返回 Agent 卡片。

import os
import requests

base_url = os.environ["MOI_BASE_URL"].rstrip("/")
response = requests.get(
    f"{base_url}/newmoi/agents/card",
    params={"agent_code": "explore"},
    headers={
        "moi-key": os.environ["MOI_API_KEY"],
        "Accept": "application/json",
    },
    timeout=30,
)
response.raise_for_status()
card = response.json()

print(card["name"])
print(card.get("capabilities", {}).get("streaming", False))

MOI_BASE_URL 表示 MOI 服务根地址；如果部署提供的地址已经带 /newmoi，应相应去掉示例 URL 中重复的路径段。

读取关键字段¶

实际字段取决于 Agent 实现及其协议版本。当前 Card 可能包含：

字段	用途
`name`	面向用户的 Agent 名称；不能代替稳定标识
`version`	Agent 实现版本
`protocolVersion`	Card 所声明的 A2A 协议版本
`capabilities.streaming`	是否声明支持流式消息
`capabilities.stateTransitionHistory`	是否声明提供状态转换历史
`defaultInputModes`	默认接受的媒体类型
`defaultOutputModes`	默认输出的媒体类型

一个最小的示例响应如下：

{
  "name": "Matrixflow Explore Agent",
  "version": "v2",
  "protocolVersion": "0.3.0",
  "capabilities": {
    "streaming": true,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"]
}

不要把示例值硬编码为所有 Agent 的固定能力。客户端应容忍未知扩展字段，并在可选字段缺失时采用保守行为。例如，未声明 streaming 时使用 message/send，或者提示调用方无法确认流式支持。

校验与缓存¶

确认响应是 JSON 对象，并至少包含客户端显示或选择 Agent 所需的字段。
只有 Card 明确声明的媒体类型才可用于自动协商；当前文档中的消息示例使用 text/plain。
可以短期缓存 Card，但发布新 Agent 版本或切换目标后应重新读取。
Card 获取失败时不要继续盲调 A2A。先检查选择器、API Key、当前工作区和 Agent 可见范围。

取得 Card 后，继续发送消息或建立流式调用。