协议扩展
A2A 的扩展机制
A2A 提供了一个强、可互操作的基础协议。但在特定领域或高级用例中，往往需要更强的结构、更丰富的数据或新的交互模式。为此，A2A 设计了 扩展（Extensions）：一种按需启用（opt-in）的机制，在不分裂核心标准的前提下叠加新能力。
扩展可以引入新的结构化数据、额外要求、可选 RPC 方法，或对任务状态机语义做增强。每个扩展由一个 URI 标识，并由独立的规范定义。
扩展的常见作用范围
- 仅数据扩展：新增结构化元数据（例如合规属性），不改变交互流程。
- Profile 扩展：对消息结构提出更严格约束（例如强制使用特定 schema 的
DataPart）。 - 方法扩展（扩展技能）：在核心方法之外新增 RPC 方法。
- 状态机扩展：通过元数据细化/标注任务状态的子语义。
限制
为保持核心兼容性，扩展通常不应：
- 修改核心对象 schema（把自定义字段放入
metadata）。 - 往核心枚举里加新值（用 metadata 表达额外语义）。
声明扩展
智能体在 AgentCard 的 capabilities 中声明支持的扩展。例如：
{
"name": "Magic 8-ball",
"description": "An agent that can tell your future... maybe.",
"version": "0.1.0",
"url": "https://example.com/agents/eightball",
"capabilities": {
"streaming": true,
"extensions": [
{
"uri": "https://example.com/ext/konami-code/v1",
"description": "Provide cheat codes to unlock new fortunes",
"required": false,
"params": {
"hints": ["When your sims need extra cash fast"]
}
}
]
}
}激活扩展
客户端通常在“每次请求”维度选择启用哪些扩展。常见做法是使用 HTTP Header 列出扩展 URI，并在请求体中携带扩展相关的 metadata。
示例请求：
POST /agents/eightball HTTP/1.1
Host: example.com
Content-Type: application/json
X-A2A-Extensions: https://example.com/ext/konami-code/v1
{
"jsonrpc": "2.0",
"method": "message/send",
"id": "1",
"params": {
"message": {
"kind": "message",
"messageId": "1",
"role": "user",
"parts": [{ "kind": "text", "text": "Oh magic 8-ball, will it rain today?" }]
},
"metadata": {
"https://example.com/ext/konami-code/v1/code": "motherlode"
}
}
}示例响应（回显已激活扩展）：
HTTP/1.1 200 OK
Content-Type: application/json
X-A2A-Extensions: https://example.com/ext/konami-code/v1
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"kind": "message",
"messageId": "2",
"role": "agent",
"parts": [{ "kind": "text", "text": "That's a bingo!" }]
}
}必选扩展（Required）
当 AgentCard 将扩展标记为 required: true 时，表示客户端必须遵循该扩展的约束，否则服务端应拒绝请求。仅数据扩展一般不建议标记为 required。
实现建议
- 版本策略：URI 中包含版本号；破坏性变更使用新 URI。
- 规范发布：尽量把扩展规范托管在扩展 URI 所指向的位置。
- 安全：对扩展输入严格校验；扩展方法必须与核心方法一样接受认证/授权控制。