A2A:跨服务协作与认证授权

03 · A2A:跨服务协作与认证授权

读完你会知道:

  1. A2A 为什么出现,它和 REST、MCP 的本质区别;
  2. 名片 / 信封 / 工单三件套分别解决什么问题;
  3. 一次真实调用长什么样,从零写一个 A2A 服务要几步;
  4. 身份到底该放在哪:SDK 的四条硬事实,以及为什么元数据到不了工具;
  5. 超时与幂等:为什么「超时不是失败」,以及重复下单是怎么发生的。
    三句话版本
  • 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"业务授权\
已认证?有权限?"

三条工程规则:

  1. 认证在宿主 :ChatEndpoints 是唯一解析身份的地方,解析结果压进请求上下文;
  2. 授权在业务:远端工具自己判断「这个操作要不要登录」,宿主不替它决定;
  3. 声明在名片 :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

先在左下角「⚙ 设置」里填自己的模型,再让它下一单试试------工具循环、步数预算、审批拦截都能在页面上看到。

相关推荐
J船长41 分钟前
Agent开发 11|安全与可靠性:怎样验证执行边界?
agent
J船长41 分钟前
Agent开发 08|LLM Eval:怎么验证 Agent 的效果?
agent
J船长42 分钟前
Agent开发·阶段总结(三)|从模型调用到上线评审,串起 Agent 的运行与保障机制
agent
J船长1 小时前
Agent开发 07|RAG:如何找到并用好企业知识?
agent
J船长1 小时前
Agent开发 12|系统设计:怎样评审 Agent 的上线准备?
agent
J船长1 小时前
Agent开发 10|可观测性:怎样追踪一次任务并定位故障?
agent
J船长1 小时前
Agent开发 06|状态与恢复:任务中断后如何继续?
agent
J船长1 小时前
Agent开发 09|Model Gateway:怎么选模型、做降级、算成本?
agent
J船长1 小时前
Agent开发·阶段总结(二)|从上下文到评测,串起 Agent 的信息与质量管理
agent