03 · A2A:跨服务协作与认证授权
读完你会知道:
- A2A 为什么出现,它和 REST、MCP 的本质区别;
- 名片 / 信封 / 工单三件套分别解决什么问题;
- 一次真实调用长什么样,从零写一个 A2A 服务要几步;
- 身份到底该放在哪:SDK 的四条硬事实,以及为什么元数据到不了工具;
- 超时与幂等:为什么「超时不是失败」,以及重复下单是怎么发生的。
三句话版本
- A2A 的前提是能力对调用方不透明:只声明会什么,不暴露怎么实现。它和 REST 的差别不在传输,在契约松紧。
- 三件套各管一段:名片负责发现,消息负责委托,任务负责长活的进度;身份只能落在 HTTP 请求级,
因为 SDK 没有身份抽象、卡片里的安全声明不会被执行、metadata到不了工具。- 超时不是失败,是结果未知:写操作先查后重试,失败结果不进缓存;幂等键由服务端定,不能由模型传。
官方定位(意译) :A2A(Agent2Agent)是一个开放的 Agent 互操作协议,最初由 Google 提出、现由 Linux Foundation 托管。它让不同框架、不同厂商实现的 Agent 能够互相发现能力、委托任务并交换结果------调用方不需要知道对方内部怎么实现。
一、为什么会有它
1.1 起因:REST 的隐含前提,是「接口提前约定」
REST 的世界里,A 调 B 只写一行:POST https://b.example.com/orders,体里带 {"sku":"X50","qty":1}。
它能成立,靠一个从没写进文档的前提:A 知道 B 有哪些接口、字段叫什么 。接口是双方提前谈好的------
这个前提撑了 Web 二十年,因为接口一直是人写死的。
1.2 撞墙:当 B 变成一个会自己思考的 Agent
2023 年之后,越来越多的「B」不再是固定接口,而是会推理、会自己挑工具的 Agent。
于是三件事同时发生:B 内部今天用两个工具、明天用三个,路径没变但行为变了;B 可能属于另一个团队或厂商,
你没法要求它按你的字段改造;而你真正想说的其实是「帮我下单一台手机」,不是「调 createOrder 并传五个参数」。
继续用 REST 硬编码,等于把对方实现钉进自己的代码:对方一调整,你就发一次版。
1.3 转折:把「调接口」换成「派活」
2025 年 4 月,Google 在 Cloud Next 上发布 A2A(Agent2Agent)。它做了一次朴素的替换:
不问「你的接口是什么」,先问「你会什么」。
flowchart LR subgraph OLD"传统集成:接口耦合" A1"调用方" -->|"写死接口" | B1"提供方" end subgraph NEW"A2A:能力发现 + 任务委托" A2"调用方" -->|"① 你会什么"| B2"提供方" B2 -->|"② 名片"| A2 A2 -->|"③ 派活"| B2 end
核心转向是:调用方只知道「你能干什么」,不知道「你怎么干」 ------能力对调用方 opaque。
B 内部换工具、换模型、换流程,名片不变,A 一行都不用改。落地节奏也说明它不是实验室玩具:
2025 年 6 月捐给 Linux Foundation,7 月 v0.3 补 gRPC 与签名名片,2026 年 4 月到 v1.0(多租户 + 可验证签名)。
协议是被「跨组织协作」这个真实场景逼出来的,不是先设计好再找人用。
1.4 三代集成方式放在一起
| 直接调 REST 接口 | 复用对方 SDK | A2A | |
|---|---|---|---|
| 耦合对象 | 字段与路径 | 版本与依赖树 | 只有「能力声明」 |
| 对方改内部实现 | 调用方跟着改 | 升级 SDK 再说 | 无感 |
| 跨厂商 | 要一家家谈 | 要一家家装 | 名片即契约 |
| 适合粒度 | 函数级 | 函数级 | 任务级 |
| 代价 | 简单、快 | 类型安全 | 多一次发现、多一层信任问题 |
A2A 不是把 REST 做得更好,而是把契约的位置从「接口」挪到了「能力」------这正是 1.2 那三件事的解法。
1.5 A2A 与 MCP 不是一回事
| MCP | A2A | |
|---|---|---|
| 连接 | Agent ↔ 工具/数据 | Agent ↔ Agent |
| 粒度 | 函数级(工具名 + 参数) | 任务级(自然语言 + 结果) |
| 谁实现 | 工具作者 | 服务作者 |
| 典型问题 | 「怎么让模型拿到这份数据」 | 「怎么让另一个团队的 Agent 帮我干活」 |
一个 Agent 可以同时是 MCP 客户端(用工具)和 A2A 服务端(被委托)------不同方向的连接,可以长在同一个进程里。
二、它是什么
2.1 三件套
flowchart TB C"Agent Card 名片\
GET /.well-known/agent-card.json" --> S"skills:会哪几种活\
interfaces:去哪调\
securitySchemes:要什么认证" S --> M"Message / Part 信封\
POST /a2a(JSON-RPC)" M --> T"Task 工单\
长任务才用:查进度 / 取消 / 订阅"
| 部件 | 回答什么 | 关键字段 |
|---|---|---|
| Agent Card | 你是谁、会什么、在哪、要什么认证 | name、skills[]、supportedInterfaces[]、securitySchemes |
| Message / Part | 这次委托的内容 | role、parts[](文本/文件/结构化数据)、metadata |
| Task | 长任务的凭据 | id、status、artifacts[],支持查询/取消/订阅 |
一句话分辨:REST 传的是「参数」,A2A 传的是「任务」。任务由对方自己拆解------用几个工具、查不查库、要不要追问,都是它的事。
2.2 同步返回与任务模式
| 模式 | 什么时候用 | 表现 |
|---|---|---|
| 同步消息 | 秒级到分钟级任务 | 一次请求返回最终消息 |
| Task | 长任务、需要进度 | 先返回 task id,再轮询/订阅状态,最后取 artifact |
大多数业务委托用同步就够。任务模式是「活干得久」时的补充,不是必需品;一旦用了,就要承担状态存储与超时清理的复杂度。
本项目的订单/订餐委托都是同步:远端在 30--60 秒内返回「文本 + envelope」。这不是能力上限,而是刻意收窄 ------
同步链路更容易保证「一次请求只有一个结果」,不用引入轮询、去重、状态机三套额外机制。
2.3 它能做什么,不能做什么
| 能做 | 不能做 |
|---|---|
| 跨框架、跨厂商发现能力并派活 | 规定对方内部用什么模型、什么工具 |
| 用自然语言委托,降低接口耦合 | 保证结果一定正确(正确性在业务侧) |
| 声明认证要求,接入标准 Web 鉴权 | 替你执行鉴权(声明只是声明) |
| 长任务的进度、取消、产物交换 | 替代工作流引擎(没有编排语义) |
三、运行机制
3.1 一次调用
sequenceDiagram autonumber participant C as 调用方 participant D as 提供方 C->>D: GET /.well-known/agent-card.json D-->>C: skills / interfaces / securitySchemes C->>C: 选技能,按声明取凭据 C->>D: POST /a2a SendMessage(Authorization: Bearer ...) D->>D: 校验令牌 → 解析任务 → 跑自己的 Agent D-->>C: Message(文本 + 结构化结果) Note over C,D: 长任务:返回 task id → 轮询/订阅 → 取 artifact
报文的最小形状(JSON-RPC 2.0):
json
{"jsonrpc":"2.0","id":"1","method":"SendMessage","params":{
"message":{
"messageId":"m-1",
"role":"ROLE_USER",
"parts":[{"text":"帮我查一下订单 SO2026..."}]
}
}}
三个字段最容易写错:方法是 SendMessage(不是 message/send),角色是 ROLE_USER / ROLE_AGENT(枚举字符串),Part 的文本字段是 text。
还有两个实现层面的坑:
- well-known 路径只有一个 :本 SDK 挂的是
/.well-known/agent-card.json;老文章里的/.well-known/agent.json返回 404。 supportedInterfaces[0].Url是真实调用地址:名片里的地址必须和服务的监听地址一致;本项目曾因为配置里写 5300、实际监听 5210 而调不通。
3.2 身份:四条硬事实,决定它只能放在 HTTP 层
这是本项目花时间最多的一段。先说结论:A2A 的身份不能放在消息体里,也不能指望 SDK 替你传。
四条硬事实,来自反编译 SDK + 真实调用:
| # | 事实 | 后果 |
|---|---|---|
| 1 | A2A SDK 没有身份抽象 | 它不解析「谁在调用」,只负责协议帧 |
| 2 | 名片里的 securitySchemes / securityRequirements 只是声明,SDK 不执行 |
写了 OAuth 不等于拦了请求 |
| 3 | 服务端只读 params.metadata ;message.metadata 被丢弃 |
把身份放在 message 里会静默丢失 |
| 4 | 元数据到不了工具:AsyncLocal 在 Agent 执行边界会丢 |
装饰器里能读到,工具里读到 null |
第 4 条最隐蔽。真实的诊断日志长这样:
text
[diag] CallerScopeAgent options=set keys=[a2ui.principal] principal=True/13900000000
[diag] tool sees authenticated=False user=
同一个请求、同一个进程,装饰器读得到,工具读不到。不是 SDK 的 bug,而是「进程内隐式上下文」不适合承载「必须准」的身份。
本项目的解法是把身份落在请求级,而不是消息级:
flowchart LR H"HTTP 请求\
X-A2ui-Principal / Authorization" --> M"中间件\
解析并写入 HttpContext.Items" M --> A"CallerScopeAgent\
(可选:只做展示)" M --> T"工具\
ICallerAccessor 读取" T --> B"业务授权\
已认证?有权限?"
三条工程规则:
- 认证在宿主 :
ChatEndpoints是唯一解析身份的地方,解析结果压进请求上下文; - 授权在业务:远端工具自己判断「这个操作要不要登录」,宿主不替它决定;
- 声明在名片 :
SecurityRequirements有值 = 需要登录,宿主据此在委托前拦截------但它只是「提前告知」,不是安全边界。
3.3 超时不是失败
A2A 一次委托要跑远端的多轮模型 + 工具,冷启动实测 30--60 秒,下单那轮更长。
如果把 HTTP 超时按「失败」处理,会触发一个致命循环:
text
调用方 100s 超时 → 认为没下单 → 重试 → 远端其实已成功 → 又下一单
本项目真实事故:一份披萨被加购两次,金额从 8700 分变成 17400 分。
正确语义是超时 = 结果未知:
- 返回
⏱ A2A 委托超时:远端可能仍在执行,**结果未知**; - 写操作不要重试,先用订单号/草稿 id 查状态,确认没有生成再重试;
- 只读操作可以直接重试一次;
⏱/❌结果不进委托缓存------缓存住就等于「本次回复内永远失败」,模型连修正机会都没有。
配套的两个参数:
csharp
public int TimeoutSeconds { get; set; } = 180; // 业务委托
public int DiscoveryTimeoutSeconds { get; set; } = 5; // 能力发现
public int DiscoveryRetrySeconds { get; set; } = 30; // 发现失败负缓存
发现与委托必须分开:发现只是取一份 Agent Card,远端没启动时不该让每条消息等 180 秒。
本项目实测:远端未启动时,第一条消息 12.8 秒,第二条 2.0 秒(负缓存生效);旧逻辑每条都会重试发现。
3.4 幂等:重复委托的最后一道闸
超时语义解决「调用方不要盲目重试」,幂等解决「重试了也不出事」。远程的写操作至少要有一层:
- 订单 Agent :内存仓储 +
_gate互斥,同参数退款/建单只执行一次; - 订餐 Agent :
Place对草稿幂等------这个草稿已经生成过订单,就返回原订单号,而不是报错。
报错会诱导上游「重新下单」,而重来的第一步往往是再add_item,数量直接翻倍。
幂等键还有两个容易写错的细节(第 13 篇展开):
- 键必须带操作类型 :
place:{id}与pay:{id}不能共用一个命名空间,否则支付会命中下单结果; - 失败不写幂等表:失败是「这次没做成」,不是「这个动作已生效」;缓存失败会让重试永远拿到旧错误。
3.5 委托去重:同一轮回复只发一次
模型重复调用同一个工具是常态。本项目在委托工具外加了一层 DelegationCache:
text
key = skill + taskText 的哈希
命中 → 直接复用本轮结果,不再发 A2A 请求
它只缓存成功结果;⏱ / ❌ 一律不缓存。这一层不是「优化」,而是防止模型把一次失败放大成多次远端写操作。
四、最小实践
4.1 服务端:三步暴露一个 Agent
csharp
// ① 注册 Agent(key 用来区分同一进程里的多个 Agent)
builder.Services.AddKeyedSingleton<AIAgent>("order-agent",
(sp, _) => new CallerScopeAgent(sp.GetRequiredService<OrderAgent>().Agent));
// ② 挂 A2A 服务端:自动处理 JSON-RPC、Task 生命周期、会话路由
builder.AddA2AServer("order-agent");
// ③ 暴露端点 + 名片
app.UseCallerIdentity(); // 身份中间件(本项目自建)
app.MapA2AJsonRpc("order-agent", "/a2a");
app.MapWellKnownAgentCard(new AgentCard
{
Name = "OrderAgent",
Skills = [new AgentSkill { Id = "order", Tags = ["order"], /* ... */ }],
SupportedInterfaces = [new AgentInterface { Url = "http://localhost:5300/a2a" }],
});
名片里的 skills[].id 是路由的权威键,tags/examples 只是给模型看的触发词。
新增一个远程 Agent,宿主只需在 A2a:Agents 加一行地址,不用改任何工具类。
4.2 客户端:发现 → 选技能 → 委托
csharp
var http = httpFactory.CreateClient("a2a"); // 180s,且 UseProxy=false
var resolver = new A2ACardResolver(new Uri(baseUrl.TrimEnd('/') + "/"), http);
var card = await resolver.GetAgentCardAsync(ct);
var iface = card.SupportedInterfaces.First();
var client = new A2AClient(new Uri(iface.Url), http);
var response = await client.SendMessageAsync(new SendMessageRequest
{
Message = new Message
{
MessageId = Guid.NewGuid().ToString("N"),
Role = Role.User,
Parts = [Part.FromText(taskText)]
},
Metadata = new Dictionary<string, JsonElement>
{
[A2aPrincipal.MetadataKey] = JsonSerializer.SerializeToElement(CallerScope.Principal)
}
}, ct);
注意 Metadata 放在 SendMessageRequest(即 params.metadata),不是 Message.Metadata------放错位置不会报错,只会静默丢失。
4.3 验收:三件事必须都过
bash
# ① 名片可发现
curl -s --noproxy '*' http://localhost:5300/.well-known/agent-card.json | python -m json.tool
# ② 能派活(带身份)
curl -s --noproxy '*' -X POST http://localhost:5300/a2a \
-H 'Content-Type: application/json' \
-H 'X-A2ui-Principal: {"userId":"13900000000","authenticated":true}' \
-d '{"jsonrpc":"2.0","id":"1","method":"SendMessage","params":{"message":{"messageId":"m1","role":"ROLE_USER","parts":[{"text":"查订单 SO202505180001"}]}}}'
# ③ 去掉身份头必须被业务拒绝(本项目演示级实现返回的是业务提示,不是 401)
curl -s --noproxy '*' -X POST http://localhost:5300/a2a \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":"1","method":"SendMessage","params":{"message":{"messageId":"m1","role":"ROLE_USER","parts":[{"text":"取消订单 SO202505180001"}]}}}'
# 期望:AUTH_REQUIRED,而不是操作成功
第三条是唯一能证明「授权真的在工作」的方法。能成功的用例证明不了安全,被拒绝的用例才能。
如果接入的是标准 Bearer,验收还要多一条:401 重取令牌并重试一次,403 不重试(权限问题,重试无用)。
4.4 观察 trace
bash
curl -s --noproxy '*' "http://localhost:5210/api/trace?sessionId=$T" \
| python -m json.tool | grep -E 'A2A|返回|delegate_to_agent'
正常一次委托会出现三步:
text
调用工具 delegate_to_agent
A2A 委托 → DiningAgent
DiningAgent 返回:下单成功 + {"_type":"a2a.envelope", ...}
只有第一步、没有后两步,通常是:Card 地址不可达、技能 id 不匹配、或代理把请求吞了。
五、边界与取舍
| 取舍 | 说明 |
|---|---|
| 声明不等于执行 | securitySchemes 只是元数据,鉴权必须在 HTTP 层实现 |
tenant 不是凭据 |
租户是路由键,归属仍看令牌 claims;让调用方自己报租户等于没有隔离 |
| 身份走传输层,不走 Message | 自定义头可伪造、还要求调用方改代码;让模型转述「我是谁」则会被改写或漏掉 |
| 扩展名片要谨慎 | 公开名片 + 认证后才返回完整能力(extended card),适合能力本身敏感的场景 |
| 同步委托不适合高频写 | 每次都是「远端多轮模型 + 工具」;高频、低延迟场景应走 REST/消息队列 |
| A2A 不解决一致性问题 | 跨服务写入仍需幂等、对账、超时语义;协议只负责「把话带到」 |
一个常见的误判:把「A2A 调通了」当成「集成完成」。真正的完成标准是:
超时能区分结果未知、重试不会重复写、身份不能被伪造、失败能被 trace 定位 。
四件事缺任何一件,生产环境都会以「偶发重复下单」或「偶发越权」的形式还回来。
六、小结
- A2A 的前提是能力对调用方不透明:只声明会什么,不暴露怎么实现。
- 三件套各司其职:名片负责发现,消息负责委托,任务负责长活的进度与产物。
- 身份必须落在 HTTP 请求级:SDK 没有身份抽象,声明不会执行,
message.metadata会被丢弃,元数据到不了工具。 - 超时不是失败,是「结果未知」;写操作先查后重试,失败结果不进缓存。
- 鉴权的铁律:认证在 HTTP 边界、授权在业务层、名片写的要求必须真的执行。
在线体验:http://117.72.72.215:5210
先在左下角「⚙ 设置」里填自己的模型,再让它下一单试试------工具循环、步数预算、审批拦截都能在页面上看到。