A2A Agent Card 怎么声明代理能力和服务地址

A2A Agent Card 的写法可以先记住一句话：它要让调用方在真正发送任务前知道“这个代理是谁、能做什么、接受什么输入、从哪个协议地址接收请求”。服务地址不能只写成一个孤立的 endpoint 字符串，而应放在 supportedInterfaces 的接口条目中，与 protocolBinding 和 protocolVersion 一起声明。

本文只讨论 Agent Card 的身份、能力、技能和服务接口，不展开代理内部使用哪个模型。下面的示例域名是文档示例，读者需要替换成自己的真实服务地址。

官方规范：https://a2a-protocol.org/latest/specification/

A2A Agent Card 是“发现与协商入口”，不是把 OpenAPI 字段换一个名字后的普通接口文档。先把能力边界写清楚，再按偏好顺序声明可用协议和 URL，客户端才有稳定的选择依据。

先把 Agent Card 和普通 API 文档分开

普通 API 文档主要回答“某个 HTTP 接口怎样调用”；Agent Card 还要回答“是否值得把任务交给这个代理”。A2A 规范要求服务端提供 Agent Card，它描述服务端的身份、能力、技能和交互要求，客户端据此发现合适的代理并配置交互。

因此，Agent Card 的信息可以按三层理解：

一份 Agent Card 至少要表达哪些信息

下面是一份可作为起点的最小扩展示例。它刻意保留了多个接口和一项技能，便于观察“能力描述”和“服务地址”之间的分工。JSON 必须保持有效，因此字段含义放在代码块之后解释。

{
  "name": "文档检索代理",
  "description": "根据企业知识库检索文档并返回结构化摘要。",
  "provider": {
    "organization": "Example AI Lab",
    "url": "https://example.com/"
  },
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://agent.example.com/a2a/jsonrpc",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    },
    {
      "url": "https://agent.example.com/a2a/http",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "knowledge-search",
      "name": "知识库检索",
      "description": "按主题检索文档并生成带引用位置的摘要。",
      "tags": ["search", "knowledge-base"],
      "examples": ["查找报销制度中关于差旅住宿的规定"],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain", "application/json"]
    }
  ]
}

这份卡片的验收基线不是“字段越多越好”，而是调用方能否据此完成选择：

• name、description、version 负责稳定地说明代理身份和用途；描述要写任务结果，不要只写“智能助手”。
• provider 可以补充组织及其公开地址，适合在目录或多租户环境中区分提供方。
• capabilities 描述协议层能力，例如是否支持流式更新、推送通知或扩展 Agent Card；它不等于“模型有多少参数”。
• defaultInputModes 和 defaultOutputModes 是默认的数据模式。技能还可以用自己的 inputModes 和 outputModes 缩小范围。
• skills 面向任务发现，id 应稳定，description 说明边界，examples 帮助调用方判断是否匹配。

服务地址要跟协议绑定一起声明

当前规范使用 supportedInterfaces 表示代理支持的协议组合。每个接口条目至少要把三件事对应起来：调用 URL、传输/协议绑定以及协议版本。这样客户端拿到地址时，不需要猜这个 URL 究竟接收 JSON-RPC、HTTP+JSON 还是其他绑定。

列表本身还有顺序含义。服务端应按偏好顺序列出支持的接口，第一项表示首选接口；客户端在自己支持的选项中优先选择排在前面的条目，并使用该条目的 url。所以不要把不稳定的随机地址放在第一项，也不要让同一个地址在不同条目下声明出互相矛盾的协议。

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

这里的三个 URL 只是说明格式。部署时要把它们换成真实的、可由客户端访问的服务地址，并确认每个地址的协议实现和声明一致。若某个接口还声明了 tenant，客户端发送请求时要使用该接口条目给出的租户值；没有声明时则不要凭空补一个租户字段。

客户端怎样选择正确的接口

可以把客户端选择逻辑压缩成四步，重点是“先匹配支持的绑定，再取对应地址”，而不是扫描到第一个 url 就直接调用：

1. 解析 Agent Card 中的 supportedInterfaces。
2. 从前到后寻找客户端支持的协议绑定和版本。
3. 如果有多个可用项，优先选择列表更靠前的条目。
4. 把请求发送到选中条目的 url，并遵守该条目的 tenant 约束。

一个实用的匹配表如下：

如果要在客户端记录诊断信息，建议同时记录选中的 protocolBinding、protocolVersion 和 URL。这样当请求失败时，可以区分“没有找到兼容接口”和“已经找到接口但服务端返回错误”，而不是把所有问题都归结为网络不可达。

发现入口、认证和扩展卡怎么配合

公开发现时，规范给出的 well-known 地址是 https://{server_domain}/.well-known/agent-card.json。也可以通过注册表、目录或预配置的 Agent Card 地址发现代理。生产部署不应把私有 Token、临时内网地址或用户个人路径写入公开卡片。

认证要求通过 securitySchemes 和相关安全要求表达。客户端先从卡片发现需要的认证方案，再通过规范之外的凭据获取流程拿到凭据，最后在 A2A 请求使用的 Header 或元数据中发送。Agent Card 声明“需要认证”不代表可以把凭据直接放进卡片。

如果公开卡片只展示有限能力，可以用 capabilities.extendedAgentCard 表示支持扩展卡。客户端完成认证后再请求 /extendedAgentCard 获取额外信息；公开卡片和扩展卡的技能集合应有清晰的权限边界。

卡片更新频率通常低于客户端读取频率，服务端和客户端可以使用标准 HTTP 缓存机制减少重复获取。缓存策略不改变接口选择规则：卡片变化后，客户端仍按新的 supportedInterfaces 顺序重新选择。

写完后的六项检查

1. 身份字段能否让调用方知道代理用途、提供方和版本。
2. 每个 skill.id 是否稳定且与具体任务对应，而不是把所有能力写成一个“万能助手”。
3. capabilities 是否只表达协议能力，没有夸大模型或业务效果。
4. 每个 supportedInterfaces 条目是否同时有正确的 url、protocolBinding 和 protocolVersion。
5. 接口顺序是否体现真实偏好，客户端是否能找到至少一个自己支持的绑定。
6. 认证、扩展卡和缓存说明是否与公开信息边界一致，没有暴露凭据或把缓存内容当成永久事实。

当这六项都能回答清楚时，Agent Card 就完成了它最重要的工作：让远端调用方在发送第一条任务消息前，知道该找谁、能做什么，以及应该把请求送到哪里。

相关问题

Agent Card 能不能只写一个 endpoint 字段？

不建议按当前规范这样写。服务地址应放在 supportedInterfaces 条目中，并和协议绑定及版本一起表达；单独的 endpoint 无法告诉客户端怎样使用它。

skills 和 capabilities 有什么区别？

capabilities 说明协议交互能力，例如流式或推送；skills 说明代理能完成的任务。前者适合做传输与交互协商，后者适合做任务发现和匹配。

多个服务地址应该怎么排序？

按服务端的偏好顺序列出。客户端从中选择自己支持的第一个接口，不要根据 URL 字母序或临时延迟自行改写服务端的优先级。