心 智 七 篇 · Seven Mental Models
中 EN
← Knowledge Atlas · 概念

Agent Card — Agent 能力发现机制

Agent Card：A2A 的 agent 能力发现机制，JSON 元数据文档，`/.well-known/agent-card` 端点
念
概念 · AGENT CARD · A2A 能力发现

Agent Card

Agent 的数字名片 — A2A 能力发现的核心载体

Client agent 只需知道 domain，GET /.well-known/agent-card 即可在运行时发现：对方能做什么、向哪里发请求、需要什么鉴权、支持流式吗？

Agent Card 核心字段
name / description
agent 身份声明
url
A2A 服务端点（sendMessage 目标）
capabilities
streaming · pushNotifications 等布尔能力标志
skills
擅长的任务类型列表（细粒度能力公告）
securitySchemes
OAuth2 / OpenID Connect / API Key 认证要求
extensions
自定义协议扩展声明
GET /.well-known/agent-card→解析 securitySchemes，取 token→向 url 发 sendMessage

capabilities 是运行时能力协商——streaming: true 才用 SSE；pushNotifications: true 才注册 webhook。

→ A2A Protocol · Agent InteroperabilityGoogle A2A (2025)

Agent Card — Agent 能力发现机制

A2A 协议中 agent 的”数字名片”，JSON 格式元数据文档，发布于标准化端点 /.well-known/agent-card。Agent Card 是 A2A 能力发现（discovery）机制的核心载体，让 client agent 在与 remote agent 通信前能够了解对方的身份、能力和认证要求。

问题背景

多 agent 系统中，一个 client agent 在委派任务给 remote agent 前需要知道：

  • 这个 agent 能做什么？擅长什么？
  • 向哪个 URL 发请求？
  • 需要什么鉴权方式？
  • 支持流式传输吗？支持 push notification 吗？

硬编码这些信息会导致紧耦合；Agent Card 提供了运行时可发现的标准化答案。

Agent Card 的结构

Agent Card 是一个 JSON 文档，核心字段：

字段描述
nameagent 名称
descriptionagent 描述
urlA2A 服务端点（sendMessage 的目标 URL）
capabilities能力声明（streaming、pushNotifications 等布尔标志）
skills技能列表（每项描述 agent 擅长的具体任务类型）
securitySchemes认证要求（OAuth2、OpenID Connect、API Key 等）
extensions自定义协议扩展声明

发现流程

Client Agent
  │
  ├─ GET /.well-known/agent-card
  │    → Remote Agent 返回 Agent Card JSON
  │
  ├─ 解析 securitySchemes
  │    → 向 Auth Server 请求 token（若需要）
  │
  └─ 解析 url
       → 向该 URL 发送 sendMessage / sendMessageStream 请求

Agent Card 端点是协议规定的固定路径，client 无需预先知道 agent 的任何信息，只需知道 domain/host 即可完成发现。

Skills：能力细粒度声明

Agent Card 中的 skills 字段允许 agent 声明自己擅长的特定任务类型。这与 Agent Skills（Anthropic 提出的单 agent 内部能力打包标准）处于不同层次：

  • Agent Skills（Anthropic）：agent 内部的能力封装，供单个 agent 使用
  • Agent Card skills（A2A）：agent 对外暴露的能力公告，供 client agent 决策路由

Capabilities 字段的作用

capabilities 是 client 在选择交互模式时的依据：

  • streaming: true → client 可以使用 sendMessageStream + SSE
  • pushNotifications: true → client 可以注册 webhook，接收异步更新

这实现了运行时能力协商，避免了 client 使用 server 不支持的功能导致报错。

与 Agent Discovery 的关系

Agent Card 是 A2A 协议 能力发现（agent discovery）子系统的核心。更广义的发现机制还包括：

  • DNS-based 发现（通过 well-known URI 推导）
  • 注册表/目录服务（非 A2A 核心，属于生态扩展）

关联概念

References