A2A v1.0 有哪些变化

A2A 协议已于 2026 年 3 月 12 日发布 v1.0.0，并在 2026 年 5 月 28 日发布了勘误版本 v1.0.1。本文梳理 v0.3.0 到 v1.0 的全部关键变化，帮助你评估影响并规划迁移。

一分钟结论

• v1.0 是协议走向成熟的一次版本：a2a.proto 成为唯一的规范性定义来源，JSON-RPC、gRPC、HTTP+JSON/REST 三种绑定共享同一套数据模型，并有明确的等价性保证。
• 有一批破坏性变更：操作改名、Part 合并为单一结构、枚举取值改为 SCREAMING_SNAKE_CASE、流式事件不再使用 kind、Agent Card 的接口声明重构、HTTP 路径去掉 /v1 前缀等。
• 同时新增了企业级能力：Agent Card 签名、多租户、版本协商、基于游标的分页、现代化的 OAuth 流程，以及标准化的错误模型。
• v1.0.1 是勘误版本，没有引入新的破坏性变更（见文末）。

四大主题

1. 协议成熟与标准化

• a2a.proto 从 gRPC 专用的实现文件提升为通用的、规范性的单一事实来源；
• 在可能之处采用正式的规范标准（RFC 8785、RFC 7515）和 google.rpc.Status；
• 更严格地遵循 REST、gRPC、JSON-RPC 各绑定的行业惯例；
• 强化的版本策略，并有明确的向后兼容规则；
• 完整的错误分类，以及各协议的映射。

2. 更强的类型安全与清晰度

• 取消 kind 判别字段，改用 JSON 成员名区分多态；
• 破坏性：枚举取值由 kebab-case 改为 SCREAMING_SNAKE_CASE，以符合 ProtoJSON 规范；
• 更严格的字段命名约定（JSON 使用 camelCase）；
• 更精确的时间戳规范（带毫秒精度的 ISO 8601）；
• 对可选与必填语义的定义更明确。

3. 更好的开发者体验

• 操作重命名，更一致、更清晰；
• 重新组织 Agent Card 结构，逻辑分组更合理；
• 增强的扩展机制，支持版本与必需声明；
• 更明确的服务参数处理（A2A-Version、A2A-Extensions 头）；
• 简化的 ID 格式：去掉 tasks/{id} 这类复合 ID，改用简单的 UUID；
• 按接口声明协议版本：每个 AgentInterface 指定自己的协议版本，便于向后兼容；
• 多租户支持：请求中原生支持租户范围。

4. 企业级特性

• 基于 JWS 与 JSON 规范化的 Agent Card 签名验证；
• 三种协议绑定的正式规范及等价性保证；
• 增强的安全方案声明，支持双向 TLS；
• 现代 OAuth 2.0 流程：新增设备码流程（RFC 8628），弃用 implicit 与 password 流程（proto 中标记为 deprecated）；
• PKCE 支持：授权码流程新增 pkceRequired 字段；
• 基于游标的分页，便于大规模任务列表。

核心操作的变化

此外还有几项协议层面的简化：

• ID 格式：所有 ID 都是简单字面量。原先使用复合 ID（如 tasks/{taskId}/pushNotificationConfigs/{configId}）的操作，现在拆成独立的 task_id 与 id 字段，ID 可以直接映射为数据库主键。
• HTTP URL 路径：HTTP+JSON 绑定去掉 /v1 前缀（原来是 POST /v1/message:send，现在是 POST /message:send、GET /tasks/{id}）；如果需要版本，可以放在基础 URL 中，在接口层面管理。
• 多租户：所有请求消息新增 tenant 字段，AgentInterface 也新增 tenant 字段用于指定默认租户，详见多租户 。

核心数据对象的变化

TaskStatus 与 Message：枚举取值

timestamp 现在明确要求 ISO 8601 UTC、毫秒精度（YYYY-MM-DDTHH:mm:ss.sssZ）。

// v0.3.0
{ "status": { "state": "completed", "timestamp": "2024-03-15T10:15:00Z" } }

// v1.0
{ "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2024-03-15T10:15:00.000Z" } }

Message 与 Artifact 新增 extensions[] 数组（适用的扩展 URI）。

Part：彻底重新设计

这是影响最大的破坏性变更。原先分开的 TextPart、FilePart、DataPart 被移除，取而代之的是单一的 Part 消息，用 oneof 区分内容。

v0.3.0（分开的类型，带 kind 判别）：

{ "kind": "text", "text": "Hello world" }

{ "kind": "file", "file": { "fileWithUri": "https://example.com/doc.pdf", "mimeType": "application/pdf" } }

{ "kind": "data", "data": {"key": "value"} }

v1.0（统一的 Part）：

{ "text": "Hello world", "mediaType": "text/plain" }

{ "url": "https://example.com/doc.pdf", "filename": "doc.pdf", "mediaType": "application/pdf" }

{ "raw": "base64encodedcontent==", "filename": "image.png", "mediaType": "image/png" }

{ "data": {"key": "value"}, "mediaType": "application/json" }

变化要点：

• 移除独立的 TextPart、FilePart、DataPart 类型，移除 kind 判别字段，移除嵌套的 file 对象；
• 新增单一 Part，通过 text、raw、url、data 中出现的是哪一个字段确定内容类型；
• mediaType 取代 mimeType，对所有 Part 类型都可用；
• filename 对所有 Part 类型都可用（不再限于文件）；
• raw 用于内联的二进制内容（JSON 中为 base64），url 取代 file.fileWithUri。

// 判别方式：由 kind 字段变为成员存在性
if (part.kind === "text") { /* ... */ }   // v0.3.0
if ("text" in part) { /* ... */ }         // v1.0

流事件对象

TaskStatusUpdateEvent 与 TaskArtifactUpdateEvent 不再用 kind 区分，而是用外层的 JSON 成员名区分，并移除 final 字段（流的关闭本身就表示结束）。

// v0.3.0
{ "kind": "status-update", "taskId": "...", "contextId": "...", "status": {}, "final": true }

// v1.0
{ "statusUpdate": { "taskId": "...", "contextId": "...", "status": {} } }

// v1.0：产出物更新
{ "artifactUpdate": { "taskId": "...", "contextId": "...", "artifact": {}, "index": 0 } }

artifactUpdate 中新增的 index 字段表示产出物在任务 artifacts 数组中的位置。

AgentCard：接口声明重构

// v0.3.0
{
  "protocolVersion": "0.3",
  "url": "https://agent.example.com/a2a",
  "preferredTransport": "JSONRPC",
  "supportsAuthenticatedExtendedCard": true
}

// v1.0
{
  "supportedInterfaces": [
    { "url": "https://agent.example.com/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "capabilities": { "extendedAgentCard": true }
}

同时新增 signatures[]，用于 Agent Card 签名（JWS，签名前使用 RFC 8785 规范化）。

OAuth 2.0 现代化

v1.0 依据 OAuth 2.0 安全最佳实践（BCP）更新了安全方案：

• 弃用：ImplicitOAuthFlow（存在令牌泄露风险）、PasswordOAuthFlow（存在凭据暴露风险），在 a2a.proto 中已标记为 deprecated，新实现不应使用；
• 新增：DeviceCodeOAuthFlow（RFC 8628），适用于命令行工具、物联网设备等输入受限场景；
• 增强：AuthorizationCodeOAuthFlow 新增 pkceRequired（RFC 7636），推荐所有 OAuth 客户端使用，公共客户端必须使用。

// v0.3.0：隐式流程（v1.0 已弃用）
{ "implicitFlow": { "authorizationUrl": "https://auth.example.com/authorize", "scopes": {"read": "Read access"} } }

// v1.0：改用授权码流程 + PKCE
{
  "authorizationCodeFlow": {
    "authorizationUrl": "https://auth.example.com/authorize",
    "tokenUrl": "https://auth.example.com/token",
    "pkceRequired": true,
    "scopes": {"read": "Read access"}
  }
}

错误模型：google.rpc.Status

HTTP+JSON 的错误响应改用 google.rpc.Status 的 ProtoJSON 表示，取代 RFC 9457（Problem Details）。JSON-RPC 与 HTTP+JSON 绑定都在 data / details 数组中使用 google.rpc.ErrorInfo，提供 A2A 特有的错误上下文：

• HTTP+JSON 的 Content-Type 从 application/problem+json 改为 application/json；
• 错误模型使用 google.rpc.Status 的字段（code、message、details）；
• A2A 错误必须在 details 中包含一个 google.rpc.ErrorInfo，其 reason 为 A2A 错误类型对应的 UPPER_SNAKE_CASE，domain 为 a2a-protocol.org。

// v0.3.0（JSON-RPC）
"error": { "code": -32001, "message": "Task not found", "data": { "taskId": "123" } }

// v1.0（JSON-RPC）
"error": {
  "code": -32001,
  "message": "Task not found",
  "data": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "TASK_NOT_FOUND",
      "domain": "a2a-protocol.org",
      "metadata": { "taskId": "123" }
    }
  ]
}

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "The specified task ID does not exist",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "TASK_NOT_FOUND",
        "domain": "a2a-protocol.org"
      }
    ]
  }
}

新增的规范依赖

沿用自 v0.3.0 的依赖包括：JSON-RPC 2.0、gRPC / Protocol Buffers 3、HTTP/HTTPS、SSE、RFC 8615（Well-Known URI）、OAuth 2.0 与 OpenID Connect、TLS。

A2A 与 MCP 的关系也更为明确：MCP 负责工具和资源集成，A2A 负责智能体之间的协调，两者互补而非竞争，智能体可以按不同用例同时支持两种协议。详见 A2A 与 MCP 。

对开发者的影响

需要改动代码的破坏性变更

1. Part 类型统一（影响：关键）

// v0.3.0
if (part.kind === "text") {
  return part.text;
} else if (part.kind === "file") {
  if (part.file.fileWithUri) return fetchFile(part.file.fileWithUri);
  return part.file.fileWithBytes;
} else if (part.kind === "data") {
  return part.data;
}

// v1.0
if ("text" in part) return part.text;
if ("url" in part) return fetchFile(part.url);
if ("raw" in part) return decodeBase64(part.raw);
if ("data" in part) return part.data;

2. 流事件的判别方式（影响：高）

// v0.3.0
if (event.kind === "status-update") handleStatusUpdate(event);
else if (event.kind === "artifact-update") handleArtifactUpdate(event);

// v1.0
if ("statusUpdate" in event) handleStatusUpdate(event.statusUpdate);
else if ("artifactUpdate" in event) handleArtifactUpdate(event.artifactUpdate);

3. Agent Card 结构（影响：高）

// v0.3.0
const endpoint = agentCard.url;
const transport = agentCard.preferredTransport;
const supportsExtended = agentCard.supportsAuthenticatedExtendedCard;

// v1.0
const primaryInterface = agentCard.supportedInterfaces[0];
const endpoint = primaryInterface.url;
const transport = primaryInterface.protocolBinding;
const supportsExtended = agentCard.capabilities.extendedAgentCard;

4. 分页（影响：中）：任务列表由页码分页改为游标分页。

// v0.3.0
const response = await listTasks({ page: 1, perPage: 50 });

// v1.0
let pageToken = undefined;
do {
  const response = await listTasks({ pageToken, pageSize: 50 });
  // process response.tasks
  pageToken = response.nextPageToken;
} while (pageToken);

5. 枚举取值（影响：高）：见上文对照表。

6. 字段名（影响：低）：file.mimeType 改为 mediaType；操作名在过渡期提供别名。

7. 错误处理（影响：高）：改用 google.rpc.Status / ErrorInfo，见上文。

值得利用的新能力

• 执行模式控制：SendMessage 可通过 returnImmediately 选择是等待任务完成（默认），还是立刻返回稍后轮询。
• Agent Card 签名验证：存在 signatures 时验证签名，验证失败应拒绝使用。
• 必需扩展检查：读取 Agent Card 中 required: true 的扩展，确认客户端全部支持。
• 版本协商：客户端发送 A2A-Version 头；服务端不支持该版本时拒绝。

迁移策略建议

阶段 1：兼容层

1. 同时支持解析新旧两种判别方式；
2. 基于协议版本实现版本检测；
3. 过渡期同时支持两种 Agent Card 结构。

阶段 2：双栈支持

1. 所有 API 改为输出 v1.0 格式；
2. 保留对 v0.3.0 的向后兼容读取；
3. 增加 A2A-Version 头处理；
4. 在旧的页码分页之外实现游标分页。

阶段 3：仅 v1.0

1. 弃用 v0.3.0 兼容代码；
2. 移除旧的判别方式解析；
3. 移除页码分页；
4. 清理双格式支持代码。

向后兼容策略

v1.0 引入了正式的协议版本化做法，支持 SDK 的向后兼容：

• 每个 AgentInterface 通过自己的 protocolVersion 声明版本；
• 智能体可以暴露多个接口，同时支持多个协议版本；
• 客户端从 Agent Card 中选择合适的接口，完成版本协商。

SDK 可以据此同时支持多个协议版本，让智能体逐步迁移，客户端自动选择最佳的兼容版本，并平滑弃用旧版本。

测试要点

• 同时用 v0.3.0 与 v1.0 格式的数据测试；
• 验证 Agent Card 签名验证；
• 测试游标分页的边界情况（空结果、单页等）；
• 验证对新增错误类型的正确处理；
• 测试扩展要求的校验。

建议的优先级

v1.0.1 勘误

v1.0.1（2026 年 5 月发布）仅包含规范层面的修复，没有新增破坏性变更：

• HTTP 绑定中优先使用 application/a2a+json 媒体类型；
• 修正近期与转码（transcoding）相关的错误处理变更；
• 修正规范中 TaskStatus 取值的描述。

完整记录见 GitHub 发布页 。

进一步阅读

• 协议规范
• 核心概念
• 任务的生命周期
• A2A 官方 · What’s New in v1.0