A2A AgentSkill：描述智能体能做什么

AgentSkill 是 Agent Card 中 skills 数组的一项，描述智能体能做的一件事：名称、说明、标签，以及可选的示例提示、媒体类型和安全要求。在 v1.0 中，skills 是卡片的必填字段。

proto 定义对技能的定位很直接：它"主要是一个描述性概念"，即智能体大概率能做好的一组较聚焦的行为。

技能是描述，不是端点

没有任何 A2A 操作用来选择技能。SendMessageRequest 只有 tenant、message、configuration 和 metadata，SendMessageConfiguration 里同样没有技能字段。客户端发送一条普通的 Message ，由智能体决定如何处理。

所以技能是写给卡片读者看的。客户端智能体，或者在注册中心浏览的人，用它判断这个智能体是否适合当前任务，以及该发送哪些媒体类型。

字段

字段	必填	含义
`id`	是	技能的唯一标识
`name`	是	人类可读的名称
`description`	是	技能的详细说明
`tags`	是	描述技能能力的关键词
`examples`	否	该技能可处理的示例提示或场景
`inputModes`	否	该技能支持的输入媒体类型，覆盖智能体的默认值
`outputModes`	否	该技能支持的输出媒体类型，覆盖智能体的默认值
`securityRequirements`	否	该技能需要的安全方案

规范规定，标记为必填的数组必须至少包含一个元素（第 5.7 节）。按这条规则，skills 为空的卡片无效，没有 tags 的技能同样无效。

规范中的示例

下面是规范示例 Agent Card（GeoSpatial Route Planner Agent）的第一个技能：

{
  "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.",
    "{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}"
  ],
  "inputModes": ["application/json", "text/plain"],
  "outputModes": ["application/json", "application/vnd.geo+json", "text/html"]
}

examples 是字符串列表。第二条示例是序列化成字符串的 JSON 对象，与 inputModes 中的 application/json 对应：示例是客户端会放进请求里的任何内容，不限于自然语言。

技能级的输入输出模式

卡片上的 defaultInputModes 和 defaultOutputModes 是必填字段，对所有技能生效。技能自己的 inputModes 和 outputModes 会替换这些默认值。示例卡片展示了两个方向：

	`inputModes`	`outputModes`
卡片默认值	`application/json`、`text/plain`	`application/json`、`image/png`
`route-optimizer-traffic`	`application/json`、`text/plain`	`application/json`、`application/vnd.geo+json`、`text/html`
`custom-map-generator`	`application/json`	`image/png`、`image/jpeg`、`application/json`、`text/html`

第二个技能把输入收窄到只接受 JSON，第一个技能列出了不在卡片默认值中的输出类型。请如实声明：规范对 ContentTypeNotSupportedError 的描述是，请求中的媒体类型"不被智能体或被调用的具体技能支持"时返回。见 A2A 错误码。

在请求一侧，客户端还可以通过 SendMessageConfiguration 中的 acceptedOutputModes 说明自己接受哪些返回媒体类型。

技能级的安全要求

技能可以带自己的 securityRequirements，结构与卡片级字段相同：每一项把方案名称（定义在卡片的 securitySchemes 中）映射到 scope 列表。规范的示例卡片没有在技能上设置它。下面的片段沿用同一示例中卡片级的要求，仅用来说明该字段的位置：

{
  "id": "route-optimizer-traffic",
  "securityRequirements": [{ "schemes": { "google": { "list": ["openid"] } } }]
}

方案本身如何声明，见 A2A SecurityScheme 。

从 v0.3 升级？

根据 proto 定义，AgentSkill 的 1 至 7 号字段编号及含义保持不变，只有一个字段变了：

v0.3.0	v1.0.1
`security`（8 号字段），类型 `Security`	`security_requirements`（8 号字段），类型 `SecurityRequirement`，因此 JSON 键为 `securityRequirements`

消息结构不变（map<string, StringList> schemes），变的只是名称。官方迁移指南没有列出这次重命名，两个版本的 proto 文件可以看到。AgentCard.security（9 号字段）也做了同样的重命名。见 Agent Card Proto 字段编号：v0.3.0 与 v1.0.1 。