A2A Agent Card：结构、发现与签名

A2A Protocol 技术文档

核心对象

Agent Card 是 A2A 服务器描述自身的 JSON 文档：它是谁、暴露哪些接口、能做什么、客户端必须如何认证。A2A 服务器必须提供一份。客户端读取它，判断某个智能体是否适合当前任务，以及如何与之通信。

客户端从哪里获取

规范列出了获取 Agent Card 的三种方式：

Well-Known URI：https://{server_domain}/.well-known/agent-card.json
注册表或目录：经过整理的智能体集合
直接配置：预先配置的 Agent Card 地址，或直接配置卡片内容

各种策略及取舍见 A2A 智能体发现。

最小的卡片

这是规范用来解释规范化（canonicalization）的示例：

{
  "name": "Example Agent",
  "description": "An example agent that echoes messages.",
  "supportedInterfaces": [
    {
      "url": "https://example.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extensions": []
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "echo",
      "name": "Echo",
      "description": "Echoes the input.",
      "tags": ["echo"]
    }
  ]
}

v1.0 中的必填字段是 name、description、version、supportedInterfaces、capabilities、defaultInputModes、defaultOutputModes 和 skills。可选字段包括 provider、documentationUrl、iconUrl、securitySchemes、securityRequirements 和 signatures。

声明接口

supportedInterfaces 按优先顺序列出智能体支持的所有「协议绑定 + URL」组合。第一项是首选接口；多种传输共用同一个端点时，URL 可以重复使用。下面的片段来自规范的示例卡片：

"supportedInterfaces": [
  {"url": "https://georoute-agent.example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"},
  {"url": "https://georoute-agent.example.com/a2a/grpc", "protocolBinding": "GRPC", "protocolVersion": "1.0"},
  {"url": "https://georoute-agent.example.com/a2a/json", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0"}
]

客户端必须遵守以下规则：

解析 supportedInterfaces，选择客户端支持的第一个传输。
支持多个选项时，优先选择靠前的条目。
使用所选传输对应的 URL。
每条请求消息中的 tenant 必须与所选条目中的值完全一致；条目没有该字段时则省略。见多租户与多智能体路由。

能力、模式与技能

capabilities 声明可选特性：

streaming：智能体支持流式传输。流式操作要求它为 true。
pushNotifications：智能体可以发送 webhook 通知。推送通知相关操作要求它为 true。
extendedAgentCard：已认证的客户端可以调用 GetExtendedAgentCard 获取更完整的卡片，其中可能包含公开卡片中没有的技能或设置。客户端应当在已认证会话期间，用它替换缓存的公开卡片。
extensions：智能体支持的协议扩展。见 A2A 扩展。

defaultInputModes 和 defaultOutputModes 是智能体在所有技能上接受和返回的媒体类型，每个技能都可以覆盖它们。一个技能由 id、name、description 和 tags 描述，另有可选的 examples、inputModes、outputModes 和 securityRequirements；完整字段与规则见 AgentSkill 页面。下面是规范示例卡片中的一个技能（此处省略了第二条示例提示）：

{
  "id": "route-optimizer-traffic",
  "name": "Traffic-Aware Route Optimizer",
  "description": "Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).",
  "tags": ["maps", "routing", "navigation", "directions", "traffic"],
  "examples": [
    "Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls."
  ],
  "inputModes": ["application/json", "text/plain"],
  "outputModes": ["application/json", "application/vnd.geo+json", "text/html"]
}

安全

securitySchemes 是一个映射，键是您自定义的名称，值是安全方案定义；securityRequirements 说明客户端必须满足哪些方案以及哪些 scope。示例卡片使用 OpenID Connect：

"securitySchemes": {
  "google": {
    "openIdConnectSecurityScheme": {
      "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
    }
  }
},
"securityRequirements": [{ "schemes": { "google": { "list": ["openid", "profile", "email"] } } }]

五种方案类型分别是 API Key、HTTP 认证、OAuth 2.0、OpenID Connect 和双向 TLS；各类型的字段和 OAuth 2.0 流程见 SecurityScheme 页面。客户端从卡片读取要求，通过带外方式（例如 OAuth 2.0 流程）获取凭据，并在每个请求中通过协议约定的请求头或元数据发送。服务器必须认证每一个收到的请求。见 A2A 企业级特性。

签名

Agent Card 可以签名，让客户端校验它是否真实、是否被篡改：

先用 JSON 规范化方案（RFC 8785）对卡片做规范化，再按 JSON Web Signature（RFC 7515）签名。规范化之前，持有默认值的字段会被移除，除非它们是必填字段或标记了 optional；对上面的最小卡片来说，被移除的是空的 extensions 数组。signatures 字段本身不参与签名。
signatures 中的每一项包含 base64url 编码的 protected 头、base64url 编码的 signature，以及可选的未保护 header。protected 头必须包含 alg 和 kid，typ 应为 JOSE，还可以包含密钥集地址 jku。
客户端应当在信任卡片之前至少验证一个签名。可以同时存在多个签名以支持密钥轮换，已过期或已吊销的密钥不得使用。

完整流程见智能体发现与 Agent Card 。

缓存

Agent Card 很少变化，所以服务器应当发送带合适 max-age 的 Cache-Control 和 ETag。客户端应当遵循 HTTP 缓存规则（RFC 9111），缓存过期后使用条件请求，即 If-None-Match 或 If-Modified-Since。

从 v0.3 升级？

v0.3 字段	v1.0
`url`、`preferredTransport`、`additionalInterfaces`	合并为 `supportedInterfaces[]`；主端点是 `supportedInterfaces[0].url`
`protocolVersion`	移到每个接口中
`supportsAuthenticatedExtendedCard`	`capabilities.extendedAgentCard`
`security`	`securityRequirements`；每条要求的形状是 `{"schemes": {"名称": {"list": [scope]}}}`
`agent/getAuthenticatedExtendedCard`	重命名为 `GetExtendedAgentCard`
签名	明确了签名时使用 RFC 8785 规范化

完整变更列表见 A2A v1.0 有哪些变化。这些变化背后的 protobuf 字段编号，包括扩展 Agent Card 标志的去向，见 Agent Card Proto 字段编号。

A2A Agent Card：结构、发现与签名

客户端从哪里获取

最小的卡片

声明接口

能力、模式与技能

安全

签名

缓存

从 v0.3 升级？

相关页面