数据结构

A2A 数据模型的字段参考，按 JSON 序列化后的 camelCase 字段名列出（a2a.proto 中为 snake_case）。标注“必填”的字段对应 proto 中的 REQUIRED。权威定义以 a2a.proto 为准。

Task 与 TaskStatus

Task 是 A2A 的核心工作单元：有当前状态，产出结果时保存为产出物，多轮交互保存在历史中。

字段说明
id必填。任务的唯一标识，由服务端为新任务生成
contextId把任务与消息归入同一上下文的标识
status必填。TaskStatus，包含 state（必填）、可选的 message 与 ISO 8601 timestamp
artifacts任务的输出产出物列表
history任务的交互历史（消息列表）
metadata任务的自定义键值元数据

TaskState

值类型含义
TASK_STATE_SUBMITTED进行中任务已提交并被确认
TASK_STATE_WORKING进行中智能体正在处理
TASK_STATE_INPUT_REQUIRED中断需要用户补充输入才能继续
TASK_STATE_AUTH_REQUIRED中断需要先完成认证才能继续。进入该状态本身不构成对任何具体操作的授权，授权的范围与语义由实现自行定义
TASK_STATE_COMPLETED终态成功完成
TASK_STATE_FAILED终态因错误结束
TASK_STATE_CANCELED终态在完成前被取消
TASK_STATE_REJECTED终态智能体决定不执行（可发生在创建时或之后）

另有 TASK_STATE_UNSPECIFIED，表示未知或不确定的状态。各状态的流转见任务的生命周期 。

Message、Role 与 Part

Message 是客户端与服务端之间的一次沟通。

字段说明
messageId必填。消息标识，由消息的创建方生成
contextId / taskId可选，关联到上下文或任务。服务端消息必须带 contextId，仅在创建了任务时带 taskId；客户端消息两者皆可选，同时提供时必须匹配
role必填。ROLE_USER（客户端到服务端）或 ROLE_AGENT（服务端到客户端）
parts必填。消息内容，至少一个 Part
metadata可选元数据
extensions出现在或贡献给本消息的扩展 URI
referenceTaskIds为提供额外上下文而引用的任务 ID

Part 是消息或产出物中最小的内容单元，v1.0 统一为一个结构：以下四个内容字段四选一，再叠加公共字段。

字段说明
text文本内容
raw文件的原始字节，JSON 中为 base64 字符串
url指向文件内容的 URL
data任意结构化 JSON 值（对象、数组、字符串、数字、布尔或 null）
mediaType内容的媒体类型（MIME），适用于所有类型的 Part
filename文件名（可选）
metadataPart 的元数据（可选）

Artifact 与流式事件

Artifact 表示任务的输出。

字段说明
artifactId必填。在任务内唯一
name / description可读的名称与描述
parts必填。内容，至少一个 Part
metadata / extensions元数据与扩展 URI

流式操作与订阅返回 StreamResponse，其内容为以下四者之一：task、message、statusUpdate、artifactUpdate。

事件关键字段
TaskStatusUpdateEventtaskId、contextId、status（均必填）、metadata。v1.0 不再有 kind 与 final，结束由终态和流关闭判断
TaskArtifactUpdateEventtaskId、contextId、artifact（均必填）、append（为 true 时把内容追加到同 ID 的已发送产出物）、lastChunk（为 true 表示这是该产出物的最后一块）、metadata

请求配置与推送通知

SendMessageRequest 包含必填的 message，以及可选的 tenant、configuration 与 metadata。SendMessageConfiguration 的字段：

字段说明
acceptedOutputModes客户端愿意接收的响应媒体类型，智能体应当据此调整输出
taskPushNotificationConfig让智能体为任务更新发送推送通知的配置；在 SendMessage 请求中任务 ID 应为空
historyLength响应中最多包含的最近消息数，语义见核心协议规范
returnImmediately为 true 时创建任务后立即返回；默认 false，等待终态或中断状态

TaskPushNotificationConfig（Webhook 配置）的字段：

字段说明
tenant可选的路由标识，设置时必须与所选 AgentInterface 的 tenant 一致
id该配置的唯一标识
taskId配置所属的任务
url必填。接收通知的 URL
token对该任务或会话唯一的令牌
authentication发送通知所需的认证信息：scheme（必填，来自 IANA 的 HTTP 认证方案，如 Bearer）与 credentials

AgentCard 与相关对象

AgentCard 是智能体的自描述清单，发现与验证规则见智能体发现与 Agent Card 。

字段说明
name、description、version必填。基本身份信息
supportedInterfaces必填。有序的接口列表，第一项为首选
provider服务提供方：organization、url（均必填）
documentationUrl、iconUrl可选的文档与图标地址
capabilities必填。AgentCapabilities
securitySchemes认证方案映射（名称到 SecurityScheme）
securityRequirements访问智能体所需的安全要求
defaultInputModes、defaultOutputModes必填。默认的输入输出媒体类型，可被技能覆盖
skills必填。AgentSkill 列表
signatures为该卡片计算的 JSON Web Signature 列表
  • AgentInterface：url（HTTP 类传输在生产环境必须是有效的绝对 HTTPS URL，gRPC 使用 hostname:port 形式的地址）、protocolBinding（核心绑定为 JSONRPC、GRPC、HTTP+JSON，自定义绑定为开放字符串）、protocolVersion（如 1.0）均必填；可选 tenant 是一个不透明的路由字符串，设置后客户端必须在发往该接口的所有请求中带上它；
  • AgentCapabilities：streaming、pushNotifications、extendedAgentCard 三个可选布尔值，以及 extensions（AgentExtension 列表）；
  • AgentExtension：uri、description、required（为 true 时客户端必须理解并遵守该扩展）、params；
  • AgentSkill：id、name、description、tags 必填；examples、inputModes、outputModes（覆盖默认值）、securityRequirements 可选；
  • AgentCardSignature：protected（base64url 编码的 JWS 受保护头，必填）、signature（base64url 签名，必填）、header（未受保护头，可选）。

安全方案

SecurityScheme 基于 OpenAPI 3.2 的 Security Scheme Object，是以下五种之一：

方案关键字段
apiKeySecuritySchemelocation（query、header 或 cookie）、name
httpAuthSecuritySchemescheme（如 Bearer，应登记于 IANA 认证方案注册表）、bearerFormat（如 JWT，仅作提示）
oauth2SecuritySchemeflows（必填）、oauth2MetadataUrl（RFC 8414 授权服务器元数据，要求 TLS）
openIdConnectSecuritySchemeopenIdConnectUrl（OIDC Discovery URL，必填）
mtlsSecurityScheme双向 TLS，无额外必填字段

OAuthFlows 支持：

  • 授权码：authorizationUrl、tokenUrl、scopes 必填，refreshUrl 可选，pkceRequired 表示是否强制 PKCE（RFC 7636；公开客户端应始终使用，建议所有客户端使用）；
  • 客户端凭据：tokenUrl、scopes 必填，refreshUrl 可选；
  • 设备码（RFC 8628，适合 IoT 设备与 CLI 等输入受限场景）：deviceAuthorizationUrl、tokenUrl、scopes 必填，refreshUrl 可选；
  • 隐式与密码流：在 proto 中已标记为 deprecated，请改用授权码 + PKCE，或设备码。

securityRequirements 中每一项的 schemes 是“方案名称到所需 scope 列表”的映射。

相关页面

来源：A2A 官方规范 · 协议数据模型 与 a2a.proto