核心协议规范

本文从实现视角解释 A2A 核心规范，帮助你把协议条款转成可落地的系统设计。

适用范围

适用于以下场景：

  • 设计 A2A Client/Server 的通信行为
  • 对齐 v1.0 release candidate 语义
  • 从旧版本实现迁移到新语义

规范源（必须先统一）

当前版本中：

  • specification/a2a.proto 是规范事实源。
  • 生成的 JSON 工件主要用于工具链和文档展示。
  • SDK 与 schema 应由 proto 生成，不建议手工维护分叉定义。

三层模型

第一层：数据模型

核心对象包括：

  • AgentCard
  • Task
  • Message
  • Artifact
  • Part

第二层：抽象操作

核心操作包括：

  • SendMessage
  • SendStreamingMessage
  • GetTask
  • ListTasks
  • CancelTask
  • SubscribeToTask
  • 推送配置相关操作
  • GetExtendedAgentCard

第三层：协议绑定

A2A 把上述操作映射到：

  • JSON-RPC over HTTP
  • gRPC
  • HTTP+JSON/REST

v1.0 高影响变化

  • 流式结束不再依赖 final 字段，而应依据任务状态和流关闭。
  • 术语统一使用 canceled。
  • A2A-Version、A2A-Extensions 等服务参数需要显式处理。
  • 新任务的 taskId 由服务端生成，客户端不应自造。

四类读者的落地关注点

决策者

  • 明确版本治理策略和兼容窗口。
  • 先定义发现与信任边界，再做规模化接入。

初学者

  • 建议按“发现卡片 -> 发消息 -> 查任务 -> 流式/订阅”顺序学习。
  • 先吃透任务生命周期，再碰扩展机制。

开发者

  • 把 Task 作为可恢复的事实对象。
  • 把 Message 当交互载体，把 Artifact 当结果载体。
  • 提前做能力位与认证要求校验。

高级用户

  • 做跨绑定一致性与版本迁移自动化测试。
  • 用订阅+推送提高长任务鲁棒性。
  • 为扩展建立严格 schema 与版本策略。

相关链接