A2A协议与规范

1. 场景概述

A2A 中心适合用于多智能体协作已经成为刚需，但单个智能体又不适合承载全部职责的场景。最典型的情况是业务链路天然由多个专业角色组成，例如一个总控智能体负责接收用户需求，另一个检索智能体负责信息收集，再由规划智能体、执行智能体或领域专家智能体分别完成后续处理。此时，A2A 中心能够把这些角色化能力沉淀为可发现、可复用、可治理的智能体资产。

企业内部的专业分工协作

客服总控智能体需要在工单排查时调用“知识检索智能体”、“权限诊断智能体”、“履约补偿智能体”；研发助手需要调用“代码分析智能体”、“文档问答智能体”、“发布检查智能体”。A2A 中心可以将这些专业能力集中注册，让上层智能体按需发现和调用。

跨团队或跨系统的能力共享

当不同团队分别维护自己的智能体服务时，如果每个调用方都手工维护对接地址、字段和版本，协作成本会快速上升。通过 A2A 中心，调用方可以优先面向统一的空间与元数据做发现，再根据规范化的智能体描述发起调用，降低耦合度。

智能体广场 A2A 服务不改变后端 A2A 协议行为，并在入口层提供以下能力：

• 统一入站认证：为 A2A Agent 增加统一的访问控制，避免后端端点裸暴露。
• 统一 Agent 发现：通过 Agent 名册集中管理可调用的 Agent 与其技能入口，降低多智能体场景下的配置成本。

2. 核心概念

2.1 AgentCard

AgentCard 是 A2A 的能力声明与发现载体，用于声明 Agent 的身份、接口地址、能力、鉴权方案与技能清单。

项	说明
标准位置	https://{domain}/.well-known/agent-card.json（0.3.0 起为推荐位置；1.0 已注册为永久 well-known URI，访问该 URI 必须返回 AgentCard 对象）
获取方式	广场网关按该地址读取，或由提供方在注册时直接提交 AgentCard URL
更新要求	Agent 的技能、接口或鉴权方案发生变更时，必须同步更新 AgentCard；平台按 AgentCard 做能力发现与路由

AgentCard 必填字段（协议 1.0）：

字段	说明
name	Agent 名称
description	用途描述
supportedInterfaces	有序接口列表，首项为优选接口；每项含url、protocolBinding、protocolVersion
version	Agent 自身版本号（非协议版本）
capabilities	能力集合，如streaming、pushNotifications
defaultInputModes	默认输入媒体类型
defaultOutputModes	默认输出媒体类型
skills	技能列表（编写规范见第 3 章）

可选字段包括 provider、documentationUrl、securitySchemes、securityRequirements、signatures、iconUrl。

2.2 消息发送与任务查询

A2A 以「消息（Message）—任务（Task）—产物（Artifact）」为基本模型：一次调用发起或续接一个 Task，结果以 Artifact 形式返回。

能力	协议 1.0（JSON-RPC 方法名）	协议 0.3.0
发送消息	SendMessage	message/send
流式发送消息	SendStreamingMessage	message/stream
查询任务	GetTask	tasks/get
取消任务	CancelTask	tasks/cancel
订阅任务更新	SubscribeToTask	tasks/resubscribe
推送通知配置	CreateTaskPushNotificationConfig 等	tasks/pushNotificationConfig/set 等

两种方法名网关均接受：1.0 使用 PascalCase 形式，0.3.0 使用 {category}/{action} 形式，网关在入口层完成映射，调用方无需为本篇未使用的版本做改造。

传输与消息格式：

项	要求
消息格式	JSON-RPC 2.0 over HTTP(S)，Content-Type: application/json
流式	Server-Sent Events（text/event-stream）
其他绑定	协议另定义 gRPC 与 HTTP+JSON（REST）绑定，由 AgentCard 的supportedInterfaces[].protocolBinding 声明
版本声明	协议 1.0 要求客户端发送A2A-Version 请求头（空值按 0.3 处理）

3. AgentCard 与技能描述编写规范

要求	反例 → 正例
Agent 的 description 说明用途与适用场景	❌「智能助手」 → ✅「受理工单创建与状态查询。适用于用户提出故障报修、进度查询时」
技能 description 含用途、适用场景与触发关键词	❌「查询」 → ✅「按工单号查询处理进度。用户提到工单、进度、受理时使用」
技能输入输出结构完整	❌ 字段均为可选且无说明 → ✅ 标注类型、必填、枚举与默认值，并为每个字段提供说明
单一技能单一职责	❌「创建工单并派单并回访」 → ✅ 拆分为三个技能
媒体类型与实际一致	❌ 声明支持image/png 而实际只接受文本 → ✅ defaultInputModes 与真实支持范围一致
返回产物结构稳定	❌ 有时返回文本、有时返回结构化数组 → ✅ 固定 Artifact 字段名与结构，供调用方依赖
错误语义可判定	须区分不可重试错误（参数错误、权限不足）与可退避重试错误（限流、上游超时），并在error.code 中给出稳定取值
能力声明真实	capabilities.streaming、capabilities.pushNotifications 必须与实际实现一致，否则调用方会进入不可用路径

4. 协议版本兼容

4.1 A2A 支持的协议版本

智能体广场 A2A 网关同时支持 0.3.0 与 1.0 两个协议版本：开发者可按自身实现选择版本接入，无需为接入而升级协议；网关在入口层完成版本识别与适配。

A2A 协议的版本号只取主次版本（如 1.0），补丁号不参与版本协商，必须忽略。当前稳定版本与上一稳定版本：

版本	状态	说明
1.0	当前稳定	方法名为 PascalCase；顶层url 改为 supportedInterfaces[].url；security 改名 securityRequirements；新增 ListTasks、A2A-Version 请求头与部分错误码
0.3.0	上一稳定	方法名为{category}/{action} 形式；顶层含 url、protocolVersion 字段

4.2 广场 A2A 网关的双版本支持说明

广场 A2A 网关在入口层完成协议适配，调用方无需感知后端 Agent 实际使用的协议版本：

• 后端 Agent 可继续使用既有协议版本，无需升级即可接入广场。
• 网关负责协议版本适配与消息转换；调用方统一按广场声明的版本调用。
• 需要 MRTR（多轮往返）等新协议能力的场景，须由支持对应版本的接口承载。

两个版本的差异由网关统一转换，开发者按所选版本实现即可：

项	0.3.0	1.0
JSON-RPC 方法名	message/send、tasks/get、tasks/cancel	SendMessage、GetTask、CancelTask
接口地址字段	顶层url（配 additionalInterfaces）	supportedInterfaces[].url
安全需求字段	security	securityRequirements
任务状态取值	submitted、working、completed 等	TASK_STATE_SUBMITTED、TASK_STATE_WORKING、TASK_STATE_COMPLETED 等
版本声明	无该请求头	必须发送A2A-Version（空值按 0.3 处理）
AgentCard 路径	.well-known/agent-card.json	同左（已注册为永久 well-known URI）

4.3 AgentCard 统一转换与长任务规则

规则	说明
AgentCard 统一转换	广场对外暴露统一的 AgentCard，隐藏后端真实端点；技能名称与描述按平台口径重写后对外可见
端点不对外暴露	后端 Agent 的真实地址仅平台侧可见，外部调用一律经广场域名
长任务三种模式	① 轮询查询（GetTask）；② 流式订阅（SubscribeToTask / 流式发送）；③ 推送通知回调（Push Notification，HTTP POST 回调到调用方注册的 webhook）
终态任务处理	任务进入终态后再次发送消息会返回错误；对终态任务订阅更新返回「不支持该操作」错误，调用方须先判断任务状态

5. 安全与鉴权方案

以下要求适用于接入智能体广场的三方 A2A Agent。

5.1 传输与端点

要求	具体标准
强制 HTTPS	TLS 1.2 及以上（建议 1.3），证书由公共 CA 签发且在有效期内；不接受明文 HTTP
仅 remote 形态	必须提供可被网关调用的 HTTP(S) 端点；不支持本地进程或随包分发形态
AgentCard 可达	.well-known/agent-card.json 必须公网可达且内容与注册信息一致
无内网依赖	端点不得指向内网地址、回环地址，也不得依赖内部 DNS

5.2 鉴权

A2A 通过 AgentCard 的 securitySchemes + securityRequirements 声明鉴权方案。协议支持的方案类型：

方案类型	关键字段	典型用途
API Key	location（query / header / cookie）、name	静态凭据场景
HTTP 认证	scheme（如 Bearer）、bearerFormat	静态令牌场景
OAuth 2.0	flows、oauth2MetadataUrl	用户级或企业级授权
OpenID Connect	openIdConnectUrl	统一身份（OIDC）场景
双向 TLS（mTLS）	仅说明字段	企业内网或高保障场景

广场按 Agent 级声明配置出站鉴权，四类口径与 MCP 篇一致：

平台口径	对应 AgentCard 声明	适用场景
无鉴权	不声明securitySchemes	公网开放能力，由平台在入口层兜底限流
静态凭据	apiKeySecurityScheme 或 httpAuthSecurityScheme（Bearer）	凭据由平台托管与轮换，Agent 侧不得落盘
用户 OAuth	oauth2SecurityScheme 的授权码流	访问用户自有数据

OAuth 类必须实现的要点：

要求	对应标准
使用授权码流，禁止隐式流与密码流	协议 1.0 已将二者标注为废弃，并要求以授权码 + PKCE 替代
支持 PKCE	RFC 7636；协议 1.0 提供pkceRequired 字段声明
提供授权服务器元数据地址	RFC 8414（oauth2MetadataUrl 必须为 TLS 地址）
敏感场景支持设备码流程	协议定义deviceCode 流程
401 返回WWW-Authenticate；scope 不足返回 403	RFC 6750

鉴权红线：

1. 一个 Agent 只允许一种鉴权方式，不拆分到技能级；同一 Agent 混装「公开数据技能」与「用户数据技能」必须拆成两个 Agent。
2. 授权懒触发：用户首次实际调用时才授权，装配阶段不预授权。
3. 授权失效（过期或撤销）后调用必须返回 401 / 403，由平台提示重新授权。

注意：A2A 官方规范未引用 RFC 9728（受保护资源元数据），这与 MCP 规范不同。若平台要求 A2A Agent 一并发布受保护资源元数据，属于平台附加要求，需在注册信息中单独声明。

5.3 凭据与密钥管理

要求	说明
禁止硬编码	Agent 内不得出现 AK/SK、令牌、密码、PRIVATE KEY、数据库连接串、内网地址
不得接收用户凭据	后端只接受网关注入的凭据，不接收、不存储调用方的用户令牌
支持轮换	静态凭据可经平台控制台更新；OAuth refresh token 须支持轮换
日志脱敏	日志与错误响应不得包含令牌、Authorization 头或凭据原文

5.4 数据安全与多租户隔离

要求	说明
数据最小化	仅返回完成本次任务所必需的数据
租户隔离	任务与产物必须以 tenant + user 为边界；taskId、contextId 不得跨用户复用或猜解
越权防护	声明范围之外的数据一律不得返回；入参中的资源标识须做归属校验（防越权访问对象）
敏感信息	个人信息按最小必要处理；涉及数据出境须完成合规评估

附录 A：规范依据与协议对照

项	内容
官方规范（当前稳定）	A2A Protocol 规范 1.0，https://a2a-protocol.org/latest/specification/
官方规范（上一稳定）	A2A Protocol 规范 0.3.0，https://a2a-protocol.org/v0.3.0/specification/