Schema 参考 · 14 fieldsA2A v1.0

A2A Agent Card schema，逐字段详解

Agent Card 是标准化的 JSON 文档，用于告知 A2A 客户端：这个智能体是谁、去哪里联系它、它能做什么，以及访问如何被保护。本参考涵盖每一个 v1.0 字段的类型、必填要求、示例，以及校验器最常捕获的错误。

本页内容

发现机制 name description supportedInterfaces provider version documentationUrl capabilities securitySchemes security defaultInputModes defaultOutputModes skills signatures iconUrl v0.x → v1.0 迁移 TypeScript 类型完整示例 Agent Card 常见问题

发现机制是如何工作的

一个 well-known URL，启动每一次 A2A 集成。

A2A 客户端从 well-known URI 获取 Agent Card，对照自己的任务评估技能、能力与安全要求，然后调用首选接口——即 supportedInterfaces 中的第一项。如果 capabilities.extendedAgentCard 为 true，经过身份验证的客户端可以通过 GetExtendedAgentCard 操作请求更丰富的 Agent Card。

规范将 /.well-known/agent-card.json 注册为标准位置。较旧的 v0.x 部署使用 /.well-known/agent.json，这也是我们的校验器会同时检查两者的原因。

# Fetch a public Agent Card

GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "GeoSpatial Route Planner Agent",
  "supportedInterfaces": [
    { "url": "https://georoute-agent.example.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0" }
  ],
  ...
}

字段参考

每一个 AgentCard 字段，以及决定通过或失败的细节。

必填标记遵循官方规范中的 v1.0 protobuf 定义。锚点链接让每个字段都可以在 issue、评审和 CI 输出中被引用。

name

string必填

智能体的人类可读名称。

会显示在市场列表和客户端界面中。保持简短且具体——客户端会将其作为比较候选智能体时的主要标签。

常见错误：使用像“AI Assistant”这样的通用名称，让路由系统无从区分。

"name": "地理空间路径规划智能体"

description

string必填

智能体做什么，以及其他智能体何时应该调用它。

这是人类集成者和基于 LLM 的路由系统判断你的智能体是否适合某项任务的主要自由文本信号。请说明任务领域、关键能力和边界。

常见错误：少于 20 个字符的一行式描述。路由系统无法匹配你没有描述的内容。

"description": "提供高级路线规划、交通分析和自定义地图生成服务。"

supportedInterfaces

AgentInterface[]必填

端点与协议绑定的有序列表。第一项为首选。

v1.0 新增：取代了旧版顶层的 url、preferredTransport 和 additionalInterfaces 字段。每一项都声明自己的 url、protocolBinding（JSONRPC、GRPC、HTTP+JSON，或自定义绑定 URI）、protocolVersion，以及可选的租户路由键——因此一个智能体可以同时服务多个协议版本和传输方式。

常见错误：声明了服务器实际上并未在该 URL 上提供的绑定——规范要求每一项都必须准确。

"supportedInterfaces": [
  { "url": "https://api.example.com/a2a/v1",
    "protocolBinding": "JSONRPC",
    "protocolVersion": "1.0" }
]

provider

AgentProvider可选

谁在运营这个智能体：组织与网站。

面向市场和企业审计的信任信号。v1.0 将 name 字段重命名为 organization；当该对象存在时，其内部的 url 是必填的。

常见错误：仍在使用 provider.name（v1.0 之前的字段）。读取 v1.0 Agent Card 的校验器将无法识别它。

"provider": {
  "organization": "示例地理服务公司",
  "url": "https://www.examplegeoservices.com"
}

version

string必填

智能体自身的版本，而不是协议版本。

让客户端能够检测到 Agent Card 何时发生了实质性变化，并重新评估兼容性。遵循你自己的发布方案，通常是 semver。

常见错误：把它和 A2A 协议版本混淆——协议版本现在位于每个 supportedInterfaces 条目中。

"version": "1.2.0"

documentationUrl

string可选

指向智能体人类可读文档的链接。

为集成者提供一个阅读完整 API 契约、速率限制以及不属于发现文档内容的条款的地方。

常见错误：指向营销首页，而不是技术文档。

"documentationUrl": "https://docs.example.com/agent"

capabilities

AgentCapabilities必填

协议功能标志：streaming、pushNotifications、extensions、extendedAgentCard。

客户端不得调用你未声明的功能——对未声明的流式调用会返回错误。extendedAgentCard: true 表示可通过 GetExtendedAgentCard 操作获取更丰富的经身份验证 Agent Card。v1.0 移除了 stateTransitionHistory。

常见错误：在服务器没有流式端点的情况下声明 streaming: true。客户端会调用它并失败。

"capabilities": {
  "streaming": true,
  "pushNotifications": true,
  "extendedAgentCard": false
}

securitySchemes

map<string, SecurityScheme>可选

命名的身份验证方案：API 密钥、HTTP 认证、OAuth 2.0、OpenID Connect，或双向 TLS。

每个命名方案包裹一个具体的方案对象（apiKeySecurityScheme、httpAuthSecurityScheme、oauth2SecurityScheme、openIdConnectSecurityScheme、mtlsSecurityScheme）。客户端由此了解如何进行身份验证——凭据本身总是通过带外方式获取。

常见错误：在 Agent Card 中嵌入实际的 API 密钥或令牌。Agent Card 是一份公开文档。

"securitySchemes": {
  "google": {
    "openIdConnectSecurityScheme": {
      "openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
    }
  }
}

security

array可选

调用该智能体需要哪些已声明的方案（及作用域）。

每一项都将 securitySchemes 中的一个方案名映射到它所需的作用域，与 OpenAPI 的安全要求模式类似。对于刻意公开的智能体，可以完全省略这两个字段。

常见错误：声明了 securitySchemes 却没有 security 要求，让客户端只能猜测是否强制执行身份验证。

"security": [{ "google": ["openid", "profile", "email"] }]

defaultInputModes

string[]必填

智能体在所有技能中接受的媒体类型。

标准 MIME 类型，如 text/plain、application/json 或 image/png。各个技能可以用自己的 inputModes 进行覆盖。

常见错误：省略该字段。它在 v1.0 中是必填的——客户端需要它来构造请求。

"defaultInputModes": ["application/json", "text/plain"]

defaultOutputModes

string[]必填

智能体在所有技能中返回的媒体类型。

告诉调用方应该期待文本、结构化 JSON、图片还是文件。技能可以用 outputModes 按技能级别覆盖。

常见错误：在智能体实际返回结构化产物时，却只列出 text/plain。

"defaultOutputModes": ["application/json", "image/png"]

skills

AgentSkill[]必填

该智能体很可能成功完成的具体能力。

每个技能都需要 id、name、description 和 tags；examples、按技能的模式以及按技能的安全设置都是可选的。技能是发现的基本单元——路由系统会将任务与它们匹配，因此每个技能都应限定在单一的任务边界内。

常见错误：没有标签的技能。标签在 v1.0 中成为必填项，并驱动技能级别的匹配。

"skills": [{
  "id": "route-optimizer-traffic",
  "name": "感知交通的路线优化器",
  "description": "使用实时交通信息计算最优驾车路线……",
  "tags": ["maps", "routing", "traffic"],
  "examples": ["规划一条从 A 到 B 且避开收费站的路线。"]
}]

signatures

AgentCardSignature[]可选

证明该 Agent Card 由提供方签发的 JSON Web 签名。

每个签名都带有一个 base64url 编码的受保护 JWS 头和签名值，计算基于经 RFC 8785（JCS）规范化后的 Agent Card。客户端在信任从公开网络获取的 Agent Card 之前，应当验证至少一个签名。

常见错误：签名之后又编辑了任意字段——即便是空白字符层面无关紧要的值变更也会使 JWS 失效。

"signatures": [{
  "protected": "eyJhbGciOiJFUzI1NiIs...",
  "signature": "QFdkNLNszlGj3z3u0YQ..."
}]

把 v0.x Agent Card 迁移到 A2A v1.0。

如果你的 Agent Card 仍然带有顶层的 url 或 preferredTransport，说明它早于 v1.0。校验器会自动标记这两者。

v0.x 字段	v1.0 替代方案	变更原因
url	supportedInterfaces[0].url	首选端点现在就是第一个接口条目。
preferredTransport	supportedInterfaces[] ordering	偏好通过数组顺序表达，而不再是单独的字段。
additionalInterfaces	supportedInterfaces[]	所有接口都存放在一个有序数组中。
protocolVersion (top level)	supportedInterfaces[].protocolVersion	每个接口声明自己的协议版本，从而支持多版本共存。
supportsAuthenticatedExtendedCard	capabilities.extendedAgentCard	移入了 capabilities 对象；对应的 RPC 被重命名为 GetExtendedAgentCard。
provider.name	provider.organization	为了更清晰而重命名。
capabilities.stateTransitionHistory	— removed	不属于 v1.0；如有需要，可将等效行为建模为扩展。

样板代码

v1.0 Agent Card 的 TypeScript 类型。

把这些接口放进客户端、服务端或 CI 检查中，即可以类型安全的方式解析和生成 Agent Card。它们与官方规范仓库中的 protobuf 定义一致，采用 Agent Card 实际发布时的 camelCase JSON 形式。

更想手写 Agent Card？生成器产出的正是这种确切结构。

生成一份 Agent Card 对照 v1.0 校验

// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
  name: string
  description: string
  supportedInterfaces: AgentInterface[]
  provider?: AgentProvider
  version: string
  documentationUrl?: string
  capabilities: AgentCapabilities
  securitySchemes?: Record<string, SecurityScheme>
  security?: Record<string, string[]>[]
  defaultInputModes: string[]
  defaultOutputModes: string[]
  skills: AgentSkill[]
  signatures?: AgentCardSignature[]
  iconUrl?: string
}

export interface AgentInterface {
  url: string
  protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
  protocolVersion: string
  tenant?: string
}

export interface AgentProvider {
  organization: string
  url: string
}

export interface AgentCapabilities {
  streaming?: boolean
  pushNotifications?: boolean
  extensions?: AgentExtension[]
  extendedAgentCard?: boolean
}

export interface AgentExtension {
  uri: string
  description?: string
  required?: boolean
  params?: Record<string, unknown>
}

export interface AgentSkill {
  id: string
  name: string
  description: string
  tags: string[]
  examples?: string[]
  inputModes?: string[]
  outputModes?: string[]
}

export interface AgentCardSignature {
  protected: string
  signature: string
  header?: Record<string, unknown>
}

export type SecurityScheme =
  | { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
  | { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
  | { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
  | { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
  | { mtlsSecurityScheme: Record<string, never> }

完整性

Agent Card 签名，简要说明。

由于 Agent Card 是从公开网络上获取的，v1.0 将签名机制正式化：Agent Card（去除 signatures 字段和默认值后）先按 RFC 8785 JSON 规范化处理，再以 JWS 形式签名。客户端在依据 Agent Card 采取行动之前，应当通过 kid/jku 头部或受信任的密钥库验证至少一个签名。多重签名支持密钥轮换。

发布前检查清单

通过 HTTPS 在 /.well-known/agent-card.json 提供该 Agent Card。

每一个 supportedInterfaces 条目都可访问，并且确实使用了所声明的绑定方式。

技能带有必填标签以及边界清晰的描述。

声明的能力与服务器实际情况相符——未声明的功能必须返回错误，已声明的功能必须真正可用。

securitySchemes 描述了如何进行身份验证；Agent Card 中任何地方都不出现凭据。

每当 Agent Card 内容发生变化时，都提升 version。

一份完整的 v1.0 Agent Card。

一个带有 OAuth 2.0、流式传输和推送通知的客服智能体——所有必填字段一应俱全。更多模式可以在示例库中找到。

浏览全部示例

{
  "name": "客服智能体",
  "description": "回答客户支持问题、获取订单上下文，并将未解决的问题升级给人工团队。",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/customer-support",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "示例公司",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "resolve-customer-support-request",
      "name": "处理客户支持请求",
      "description": "对客户支持请求进行分类、收集所需上下文、提出解决方案，并在置信度较低时升级处理。",
      "tags": [
        "support",
        "orders",
        "returns"
      ],
      "examples": [
        "帮我退掉这个订单。"
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

常见问题

Agent Card schema 常见问题

决定 Agent Card 能否通过评审的版本变更、发现字段和发布细节。

A2A v1.0 的 Agent Card 有哪些变化？

v1.0 将 url、preferredTransport 和 additionalInterfaces 合并为一个有序的 supportedInterfaces 数组，其中每一项都声明自己的 url、protocolBinding 和 protocolVersion。supportsAuthenticatedExtendedCard 迁移到了 capabilities.extendedAgentCard，provider.name 变成了 provider.organization，技能标签成为必填项，并且通过 RFC 8785 规范化正式确立了 JWS Agent Card 签名机制。

Agent Card 和 API schema 是一回事吗？

不是。Agent Card 是智能体的发现文档。它概述了身份、接口、能力、技能、模式、提供方和安全元数据，而完整的 API schema 描述的是详细的请求和响应结构。它对一个服务所扮演的角色，相当于 README 或 OpenAPI 概览：足以判断是否要调用它、以及如何调用。

哪些字段对发现最重要？

name、description、supportedInterfaces、skills（带标签）、defaultInputModes、defaultOutputModes、capabilities、provider，以及安全元数据。路由系统会将任务与你的描述和技能标签进行匹配，然后使用接口和能力信息来规划实际调用。

私有技能应该出现在公开 Agent Card 中吗？

只发布那些对未经身份验证的发现来说是安全的技能。如果需要更丰富的私有 Agent Card，将 capabilities.extendedAgentCard 设为 true，并通过经过身份验证的 GetExtendedAgentCard 操作暴露敏感技能。

Agent Card 发布在哪里？

发布在 well-known URI https://{your-domain}/.well-known/agent-card.json，内容类型为 application/a2a+json（实践中 application/json 同样可行）。早期实现使用 /.well-known/agent.json，因此在过渡期间同时发布两者是务实的选择。

让 schema 派上用场

构建一份能一次通过校验的 Agent Card。

根据你的服务详情生成一份符合 v1.0 结构的 Agent Card，或者把已有的 Agent Card 粘贴到校验器中，精确查看哪些字段需要注意。

打开生成器校验一份 Agent Card