知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# 12 - Google A2A 协议详解 > 导读:本文从"我用 LangChain 写的 Agent,为什么没法直接调用同事用 AutoGen 写的 Agent"这个真实痛点出发,把 A2A(Agent-to-Agent,智能体间通信协议)的定位与由来、Agent Card(能力名片)、Task(任务生命周期)、Message/Part(消息结构)、Artifact(输出产物)、完整通信流程、JSON-RPC 方法集、安全机制与生态现状逐项讲透,最后给出把现有 Agent 改造为 A2A 服务时的工程实践与踩坑。适合正在做多 Agent 系统、需要跨框架或跨组织协作的后端与算法同学。 ## 一、先建立全局认知 ### Q:A2A 到底是什么?为什么需要这样一个协议? A:结论先行——A2A 是 Google 在 2025 年 4 月 Cloud Next 大会上发布的开放协议,目标只有一个:让不同框架、不同厂商构建的 AI Agent 之间能够互相发现、通信与协作。 为什么需要它?因为在 A2A 出现之前,Agent 生态是"巴别塔"。每个框架都有自己的 Agent 定义、通信方式与任务格式,跨框架协作需要为两两组合写适配器,成本呈平方级增长。  *图:框架互不通的现状与 A2A 统一协议目标* ```text 当前的问题: LangChain Agent ←✗→ AutoGen Agent ←✗→ CrewAI Agent ←✗→ 企业自研 Agent 每个框架有自己的 Agent 定义、通信方式、任务格式 不同厂商的 Agent 无法直接对话和协作 就像早期的即时通讯:QQ 不能和 MSN 聊天 A2A 的目标: LangChain Agent ←A2A→ AutoGen Agent ←A2A→ CrewAI Agent ←A2A→ 任何 Agent 统一的协议标准,任何遵循 A2A 的 Agent 都能互相发现、通信、协作 就像 HTTP 让所有浏览器都能访问所有网站 ``` 这里的关键类比是:A2A 之于 Agent,等于 HTTP 之于网页。HTTP 把"浏览器访问网站"这件事标准化了,任何浏览器都能访问任何网站,不需要为每一对"浏览器—网站"单独写适配。A2A 想把"Agent 委托任务给另一个 Agent"这件事也标准化。 ```text 时间线: 2025.04 Google Cloud Next 大会发布 A2A 协议 2025.06 捐赠给 Linux Foundation 目前 150+ 组织支持(AWS、Microsoft、Cisco、Salesforce 等) ``` 一个容易被追问的点是:A2A 为什么要捐给 Linux Foundation?答案是**中立性**。如果协议归单一厂商所有,其他云厂商会担心被"挟持",采用意愿会下降。捐赠给中立基金会是开放协议获得跨厂商信任的常见做法(Kubernetes、MCP 的治理思路类似),这也是它能在短时间内获得 AWS、Microsoft 等竞争对手支持的原因。需要说明的是,A2A 的具体规范细节(字段、方法名、必选/可选)会随版本演进,动手实现时应以**当版本官方规范**为准,本文描述的是协议发布初期的公开设计与典型形态。 ### Q:A2A 的技术底座是什么?为什么选这套组合? A:结论先行——A2A 的传输层用 HTTP,消息格式用 JSON-RPC 2.0,实时通信用 SSE(Server-Sent Events,服务端推送)。这三者都是成熟、通用、无厂商锁定的 Web 技术。 为什么这么选?可以从三个角度理解取舍: 1. **HTTP**:任何语言、任何网关、任何云都原生支持,天然能穿过企业防火墙,运维上不需要新增基础设施。相比自定义 TCP 协议,HTTP 让"Agent 服务"可以被当普通 Web 服务部署、限流、审计。 2. **JSON-RPC 2.0**:一个轻量的远程调用约定,请求体里用 `method` 表示"要做什么",用 `params` 传参数,用 `id` 关联请求与响应。它比 REST 更贴近"调用一个远程过程"的语义,比 gRPC 更轻、调试更直观(人类可读的 JSON)。 3. **SSE**:任务执行是耗时且可能多轮的,客户端需要看到"正在进行"的中间状态。SSE 基于纯 HTTP 长连接单向推送,比 WebSocket 更简单,且天然契合"服务端持续推事件给客户端"这一单向需求。 一句话概括取舍:**A2A 没有追求技术先进性,而是追求普适性与低接入门槛**,因为协议的价值随采用者数量增长。 ### Q:A2A 的生态现状如何?有哪些实现和工具可以用? A:结论先行——A2A 已获得 150+ 组织支持,并已在多个框架和语言上有落地实现。 ```text 支持 A2A 的组织(150+): 云厂商:Google Cloud、AWS、Microsoft Azure 企业:Cisco、Salesforce、SAP、Accenture AI 公司:LangChain、Cohere、Weights & Biases 开源社区:Linux Foundation 托管 已有的实现和工具: - Google ADK(Agent Development Kit)原生支持 A2A - LangGraph 社区适配器 - 多个语言的 SDK(Python、TypeScript、Java) ``` 为什么生态覆盖值得单独记?因为 A2A 的价值高度依赖"有多少 Agent 说这门语言"——**协议本身不产生价值,互操作才产生价值**。对工程师而言,判断"要不要投入"的现实指标就是:你要对接的那些 Agent 或框架,是否已经原生支持 A2A。如果对方没有实现,也可以用协议网关把现有服务包装成 A2A Agent 来过渡。 ### Q:A2A 的短期、中期与长期定位分别是什么? A:结论先行——短期是"框架原生支持 + Agent 注册中心",中期是"企业级 Agent 市场",长期是"Agent 互联网"。 ```text 短期(2025 下半年): - 更多框架原生支持 A2A - Agent 注册中心(类似 Docker Hub,但注册的是 Agent) - 标准化的 Agent Card 目录服务 中期(2026): - 企业级 Agent 市场(购买/订阅专业 Agent 服务) - 跨组织的 Agent 协作成为常态 - A2A + MCP 成为 Agent 生态的两大基础协议 长期愿景: - Agent 互联网:任何 Agent 都能发现和协作 - 类似 Web 的开放生态: HTTP 之于网页 = A2A 之于 Agent URL 之于网站 = Agent Card 之于 Agent ``` 需要提醒的是,这些是方向性判断,具体时间点和落地形态会随生态演进变化,不宜当作确定事实引用;面试中把它作为"趋势判断"来谈更稳妥。 ### Q:A2A 围绕哪几个核心概念构建? A:结论先行——A2A 协议围绕四个核心概念构建:Agent Card(能力名片)、Task(任务生命周期)、Message/Part(消息结构)、Artifact(输出产物)。理解这四者,就理解了 A2A 的骨架。  *图:A2A 的四个核心概念——Agent Card、Task、Message/Part、Artifact* ```text ┌─────────────────────────────────────────────────────────────┐ │ A2A 核心概念 │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Agent Card │ │ Task │ │ Message / │ │ │ │ (能力名片) │ │ (任务生命 │ │ Part │ │ │ │ │ │ 周期) │ │ (消息结构) │ │ │ │ 我是谁 │ │ │ │ │ │ │ │ 我能做什么 │ │ 创建→执行 │ │ 文本/文件 │ │ │ │ 怎么联系我 │ │ →完成/失败 │ │ /结构化数据 │ │ │ └─────────────┘ └─────────────┘ └──────┬──────┘ │ │ │ │ │ ┌──────▼──────┐ │ │ │ Artifact │ │ │ │ (输出产物) │ │ │ │ │ │ │ │ 文件/报告 │ │ │ │ /代码/图片 │ │ │ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` 四者的分工可以这样记: | 概念 | 回答的问题 | 类比 | |---|---|---| | Agent Card | 你是谁、你能做什么、怎么联系你 | 名片 / 岗位说明书 | | Task | 这次委托的工作现在到哪一步了 | 工单 | | Message / Part | 我和你说的话、附的文件、传的数据 | 信封与信纸 | | Artifact | 你交付给我的成果 | 交付物 / 验收产物 | 接下来的"理解核心机制"会逐一拆开这四者。  *图:A2A 协议核心概念* ### Q:A2A 和 MCP 是什么关系? A:结论先行——两者互补:MCP 管"Agent 怎么调用工具",A2A 管"Agent 怎么和其他 Agent 协作"。一个 Agent 完全可以同时是 MCP 的使用者和 A2A 的参与者。 ```text MCP:Agent ↔ 工具/数据 (垂直集成,向下) A2A:Agent ↔ Agent (水平协作,横向) 结论:不是二选一,而是各管一层,可叠加使用 ``` 为什么要把这个问题单独提出来?因为在面试与选型中,最常见的误解就是把两者当成竞品。只要记住"对象不同"这一条(工具没有自主性、Agent 有自主性),就能自然推出:需要调用外部能力用 MCP,需要把复杂任务委托给会"思考"的对方用 A2A。 ## 二、理解核心机制 ### Q:Agent Card 是什么?其他 Agent 怎么发现我? A:结论先行——Agent Card 是一份 JSON 文件,描述了一个 Agent 的身份、能力与通信方式;其他 Agent 通过读取它来发现并了解这个 Agent。它类似 OpenAPI 的 Swagger 文档,但描述的对象是"Agent"而不是"API"。 为什么需要它?因为 A2A 的双方是"两个都会自主决策的 Agent",Client 在委托任务前必须先回答三个问题:这个 Agent 支不支持我这类任务?它的能力边界在哪?我要怎么认证?Agent Card 就是这些问题的静态答案。 ```json { "name": "代码审查助手", "description": "专业的代码审查 Agent,支持 Python、Java、Go 语言的代码质量分析", "url": "https://code-review-agent.example.com", "version": "1.0.0", "capabilities": { "streaming": true, "pushNotifications": false, "stateTransitionHistory": true }, "skills": [ { "id": "code-review", "name": "代码审查", "description": "分析代码质量,检查潜在 bug、安全漏洞、性能问题", "tags": ["code", "review", "security", "quality"], "examples": [ "审查这段 Python 代码的安全性", "检查这个 Java 类的设计模式使用是否合理" ] }, { "id": "code-explain", "name": "代码解释", "description": "解释代码的功能和逻辑", "tags": ["code", "explain"], "examples": [ "解释这个递归函数的工作原理" ] } ], "defaultInputModes": ["text", "file"], "defaultOutputModes": ["text"], "authentication": { "schemes": ["OAuth2"], "credentials": "https://auth.example.com/.well-known/openid-configuration" } } ``` 关键字段逐个解读:  *图:Agent Card 的五个关键字段及含义* ```text Agent Card 的关键字段: name / description → 我是谁,我能做什么 url → 怎么联系我(HTTP 端点) capabilities → 我支持什么特性(流式、推送等) skills → 我的具体技能列表 authentication → 怎么验证身份 ``` 其中 `capabilities.streaming` 表示是否支持流式更新,`pushNotifications` 表示是否支持 Webhook 推送,`stateTransitionHistory` 表示能否查询状态变更历史;`defaultInputModes` / `defaultOutputModes` 声明默认支持的输入输出模态(如 text、file)。 发现机制也很直接: ```text 发现机制: Agent Card 通常托管在 /.well-known/agent.json 路径 Client Agent 通过 HTTP GET 获取 Agent Card 类似于 robots.txt 的约定 ``` `/.well-known/` 是 Web 世界约定俗成的"发现路径"(robots.txt、`.well-known/openid-configuration` 都在此列),好处是 Client 不需要额外配置就知道去哪拿这份名片。 ### Q:Agent Card 里的 capabilities 几个开关分别意味着什么? A:结论先行——`streaming` 表示是否支持流式更新,`pushNotifications` 表示是否支持 Webhook 推送,`stateTransitionHistory` 表示能否查询状态变更历史;它们是 Client 决定"用哪种方式拿结果"的依据。 ```text 三个能力开关: streaming: true → Client 可用 tasks/sendSubscribe 收 SSE 流 pushNotifications: false → 不支持 Webhook,只能轮询 tasks/get stateTransitionHistory: true → 可查询状态变更历史,便于审计与回放 ``` 为什么这几个开关重要?因为它们决定了 Client 的**等待策略**:支持 streaming 就能边跑边看;不支持就只能靠 `tasks/get` 轮询;支持 pushNotifications 则可以由服务端主动回调。如果 Agent Card 声明了某个能力、服务端实际并不提供,Client 会陷入"一直等不到事件"的困境——所以能力声明必须与实际实现一致,宁可少声明也不要虚报。同理,`skills` 不只是展示信息,服务端应把它当作**能力白名单**,拒绝未声明技能的请求。 ### Q:Task 的状态机长什么样?有哪些状态? A:结论先行——Task(任务)是 A2A 的核心工作单元,由 Client Agent 创建、Remote Agent 执行,它有唯一 ID 并遵循一个明确的状态机。  *图:A2A 的 Task 状态机* ```text Task 状态机: ┌──────────┐ │ submitted│ ← Client 创建任务 └────┬─────┘ │ ┌────▼─────┐ │ working │ ← Remote Agent 开始处理 └────┬─────┘ │ ├──────────────┐ │ │ ┌────▼─────┐ ┌────▼──────┐ │completed │ │ failed │ │ (成功) │ │ (失败) │ └──────────┘ └───────────┘ 额外状态: input-required → 需要 Client 提供更多信息 canceled → 任务被取消 ``` 每个状态的含义与工程含义: - `submitted`:任务已创建、尚未开始处理。此时 Client 拿到的是"回执"。 - `working`:Remote Agent 正在处理。这一步可能持续很久,是流式与推送存在的意义。 - `completed` / `failed`:终态。成功时通常会带 Artifact;失败时可能需要看状态里的 message。 - `input-required`:**中间态而非终态**,表示 Remote Agent 需要 Client 补充信息才能继续。这是 A2A 区别于"一问一答的工具调用"的关键特征。 - `canceled`:任务被取消。 ```text 每个 Task 有唯一 ID,支持: - 查询状态 - 取消任务 - 获取结果(Artifact) ``` 为什么要有状态机而不是"一次请求一次响应"?因为 A2A 委托的是**长任务**:一次代码审查可能几十秒甚至几分钟,期间可能要追问、可能要人工审批。有了显式的 Task 与状态,Client 才能查询进度、取消任务、在补充信息后**用同一个 Task 继续**,而不是每次重开一个无关任务。 ### Q:Task 有唯一 ID,这对工程实现意味着什么? A:结论先行——意味着"同一任务的多次交互必须能被关联",也意味着需要按 Task ID 设计幂等与去重。 ```text Task ID 的工程含义: 1. 补充信息(input-required 之后)用同一 ID 继续,而不是新建任务 2. 查询状态、取消任务都基于 ID 3. 网络重试时,同一 ID 的重复请求应被幂等处理 4. Artifact 归属到具体 ID,便于追溯"这份产物来自哪次委托" ``` 为什么强调幂等?因为 JSON-RPC 走 HTTP,Client 在超时后可能重发同一个 `tasks/send`。如果服务端不按 Task ID 去重,就可能为一个用户请求建出两个任务、跑两遍、产出两份 Artifact。这与 MCP 工具调用"无状态、每次独立"的模型不同——A2A 的 Task 是**有身份、需要幂等**的。 ### Q:Message 和 Part 怎么设计?为什么不是纯文本? A:结论先行——Message(消息)是 Agent 之间交换的信息单元,由 `role` 加上一个或多个 Part 组成;Part 可以是纯文本(TextPart)、文件(FilePart)或结构化数据(DataPart)。这样设计是为了让"一次消息"能同时承载文字说明和二进制附件。  *图:A2A Message 的 role、parts 组成* ```text Message 结构: Message ├── role: "user" | "agent" ← 谁发的 ├── parts: [ ← 消息内容(可以有多个部分) │ Part (TextPart) ← 纯文本 │ Part (FilePart) ← 文件(代码、图片等) │ Part (DataPart) ← 结构化数据(JSON) │ ] └── metadata: {...} ← 元数据 ``` 一个典型的"带文件的消息"示例: ```json { "role": "user", "parts": [ {"type": "text", "text": "请审查以下代码:"}, {"type": "file", "file": {"name": "main.py", "mimeType": "text/x-python", "bytes": "base64..."}} ] } ``` 为什么不是"纯文本一句话"?因为真实委托任务往往需要"说明 + 附件"一起传:只说"审查代码"却没有代码,Agent 就得反过来追问一次。把 Part 做成可多选的数组,一次消息就能把上下文给全,减少往返轮次。这也是 A2A 相对"纯 Prompt 拼接"更工程化的一点。 ### Q:Artifact 是什么?为什么它既要文本又要结构化数据? A:结论先行——Artifact 是 Task 执行后产生的输出产物,一个 Task 可以产生多个 Artifact,每个 Artifact 又能同时包含文本、文件与结构化数据。 ```text Artifact 示例: 代码审查任务的 Artifact: { "name": "review-report", "parts": [ { "type": "text", "text": "## 审查报告\n\n### 问题 1: SQL 注入风险\n..." }, { "type": "data", "data": { "issues_count": 3, "severity": {"high": 1, "medium": 2}, "score": 72 } } ] } 一个 Task 可以产生多个 Artifact Artifact 可以包含文本、文件、结构化数据等 ``` 为什么同一个结果要给两种形态?因为这两种形态服务于**不同的消费者**: - 文本(可读摘要)服务于**人**:用户与人工审核要看得懂。 - 结构化数据(DataPart)服务于**下游程序/Agent**:便于自动路由、比较、统计、重试。 面试中常被追问的一点是:两者必须**语义一致、引用同一任务版本**,否则会出现"报告说 3 个问题、结构化字段说 2 个"的自相矛盾。工程上建议让结构化数据作为"唯一事实源",文本摘要由它生成。 ## 三、通信流程与 JSON-RPC 接口 ### Q:一次完整的 A2A 通信流程是怎样的? A:结论先行——典型流程是:发现(GET Agent Card)→ 创建任务(tasks/send)→ 处理中(可用 SSE 流式)→ 可能的追问(input-required)→ 补充信息 → 完成并返回 Artifact。  *图:A2A 从能力发现到任务完成的 8 步交互* ```text Client Agent Remote Agent │ │ │ 1. GET /.well-known/agent.json │ │ ─────────────────────────────────────────────► │ │ │ │ 2. 返回 Agent Card(能力描述) │ │ ◄───────────────────────────────────────────── │ │ │ │ [Client 分析 Agent Card,确认能力匹配] │ │ │ │ 3. JSON-RPC: tasks/send(创建任务) │ │ ─────────────────────────────────────────────► │ │ { │ │ "method": "tasks/send", │ │ "params": { │ │ "id": "task-001", │ │ "message": { │ │ "role": "user", │ │ "parts": [{"type":"text","text":"请审查这段代码"}] │ } │ │ } │ │ } │ │ │ │ 4. 返回 Task 状态(working) │ │ ◄───────────────────────────────────────────── │ │ │ │ [可选] 5. SSE 流式更新 │ │ ◄─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ event: task-status │ │ data: {"status": "working"} │ │ │ │ [可选] 6. 需要更多信息 │ │ ◄───────────────────────────────────────────── │ │ status: "input-required" │ │ message: "请提供代码的编程语言" │ │ │ │ 7. 补充信息 │ │ ─────────────────────────────────────────────► │ │ message: "Python 3.11" │ │ │ │ 8. 任务完成,返回 Artifact │ │ ◄───────────────────────────────────────────── │ │ status: "completed" │ │ artifacts: [{审查报告}] │ │ │ ``` 关键点有三处:一是**先发现后委托**,Client 必须先读 Agent Card 再决定是否/如何调用;二是**任务有 ID**,第 7 步的补充信息不是新任务,而是挂在同一个 `task-001` 上继续;三是**流式是可选的**,支持 `streaming` 能力时体验更好,不支持则退化为轮询 `tasks/get`。  *图:A2A 通信时序流程* ### Q:A2A 提供了哪些 JSON-RPC 方法? A:结论先行——A2A 的方法集围绕 Task 的生命周期展开,核心是"发任务、查状态、取消任务、订阅更新、配置推送"。  *图:A2A 围绕 Task 生命周期的 JSON-RPC 方法* ```text ┌──────────────────────┬──────────────────────────────────────┐ │ 方法 │ 说明 │ ├──────────────────────┼──────────────────────────────────────┤ │ tasks/send │ 发送消息给 Agent,创建或继续任务 │ │ tasks/sendSubscribe │ 发送消息并订阅 SSE 流式更新 │ │ tasks/get │ 查询任务当前状态和结果 │ │ tasks/cancel │ 取消正在执行的任务 │ │ tasks/pushNotification│ 配置推送通知(Webhook) │ │ /set │ │ │ tasks/pushNotification│ 查询推送通知配置 │ │ /get │ │ │ tasks/resubscribe │ 重新订阅任务的 SSE 更新 │ └──────────────────────┴──────────────────────────────────────┘ ``` 注意 `tasks/send` 的语义是"**创建或继续**任务"——同一个 Task ID 再次 `send` 就等价于"补充信息、继续执行",这正好对应 `input-required` 后的处理动作。`tasks/sendSubscribe` 与 `tasks/resubscribe` 则分别负责"首次订阅"和"断线重连后重新订阅",说明协议在设计时就把**连接会断**这件事考虑进去了。 ### Q:为什么用 JSON-RPC,而不是 REST 或 GraphQL? A:结论先行——因为 A2A 的调用形态是"远程过程调用"而不是"资源增删改查",JSON-RPC 的 `method + params` 语义更贴合。 REST 以资源为中心(`GET /tasks/{id}`、`DELETE /tasks/{id}`),适合增删改查;但 A2A 的动作里包含"订阅流式"(sendSubscribe)、"重新订阅"(resubscribe)、"配置推送"这类**动作型**操作,用 REST 表达会很别扭(要么造很多子资源,要么用 POST 加动词)。GraphQL 偏重"按需取字段的查询",对"触发一个长任务"这种写操作并不擅长。JSON-RPC 用 `method` 直接表达动作、用 `params` 传结构化参数、用 `id` 关联请求响应,恰好匹配"调用一个远程过程"的需求。 ```text JSON-RPC 请求骨架: { "jsonrpc": "2.0", "id": "<请求关联 ID>", "method": "tasks/send", "params": { "...": "..." } } 四个字段的职责: jsonrpc → 协议版本 id → 请求与响应配对(Client 可并发发多个请求) method → 要执行的动作 params → 动作的参数 ``` ### Q:流式任务(SSE)具体怎么走?看代码更直观吗? A:结论先行——流式任务用 `tasks/sendSubscribe` 发起,服务端通过 SSE 持续推送 `task-status` 与 `task-artifact-update` 事件,直到终态。 创建流式任务: ```json // 请求:创建流式任务 { "jsonrpc": "2.0", "id": "req-003", "method": "tasks/sendSubscribe", "params": { "id": "task-stream-001", "message": { "role": "user", "parts": [ {"type": "text", "text": "逐步分析这段代码的性能瓶颈"} ] } } } ``` 对应的 SSE 响应流: ```text // SSE 响应流 event: task-status data: {"id":"task-stream-001","status":{"state":"working"}} event: task-artifact-update data: {"id":"task-stream-001","artifact":{"name":"analysis","parts":[{"type":"text","text":"正在分析函数调用链..."}],"append":true}} event: task-artifact-update data: {"id":"task-stream-001","artifact":{"name":"analysis","parts":[{"type":"text","text":"发现第 42 行的循环可以优化..."}],"append":true}} event: task-status data: {"id":"task-stream-001","status":{"state":"completed"}} ``` 关键点是 `"append": true`:Artifact 是**增量追加**的,而不是每次都返回全量。这样长报告的流式输出只传新增片段,带宽与前端渲染成本都更低。工程上要注意:断线后要用 `tasks/resubscribe` 重新订阅,并做好去重,避免重复渲染已收到的片段。 ### Q:非流式场景下,创建任务和查询状态的报文长什么样? A:结论先行——创建任务用 `tasks/send`,返回 accepted 状态;查询用 `tasks/get`,终态时在 `artifacts` 里拿到产物。 创建任务请求(含文件附件): ```json // 请求:创建代码审查任务 { "jsonrpc": "2.0", "id": "req-001", "method": "tasks/send", "params": { "id": "task-code-review-001", "message": { "role": "user", "parts": [ { "type": "text", "text": "请审查以下 Python 代码的安全性和代码质量" }, { "type": "file", "file": { "name": "app.py", "mimeType": "text/x-python", "bytes": "aW1wb3J0IG9zCg==" } } ] } } } ``` 响应(任务已接受,进入 working): ```json // 响应:任务已接受 { "jsonrpc": "2.0", "id": "req-001", "result": { "id": "task-code-review-001", "status": { "state": "working", "message": { "role": "agent", "parts": [ {"type": "text", "text": "正在分析代码,请稍候..."} ] } } } } ``` 查询状态: ```json // 请求:查询任务状态 { "jsonrpc": "2.0", "id": "req-002", "method": "tasks/get", "params": { "id": "task-code-review-001" } } ``` ```json // 响应:任务完成 { "jsonrpc": "2.0", "id": "req-002", "result": { "id": "task-code-review-001", "status": { "state": "completed" }, "artifacts": [ { "name": "review-report", "parts": [ { "type": "text", "text": "## 代码审查报告\n\n### 发现 2 个问题\n\n1. **高危**:第 15 行存在 SQL 注入风险...\n2. **中危**:第 23 行未处理异常..." }, { "type": "data", "data": { "total_issues": 2, "high": 1, "medium": 1, "low": 0, "quality_score": 78 } } ] } ] } } ``` 这里能清楚看到 `jsonrpc` / `id` / `method` / `params` 四个 JSON-RPC 字段的配合:`id` 用来把响应和请求对上(Client 可以并发发多个请求),`method` 决定动作,`params` 承载 Task。也要注意响应里的 `artifacts` 是数组——再次印证"一个任务可以有多个产物"。 ## 四、安全机制 ### Q:A2A 内置了哪些安全机制? A:结论先行——A2A 从身份认证、权限控制、传输安全、输入验证四个层面内建了安全设计,核心是 OAuth 2.0 / OpenID Connect 加 HTTPS。 ```text 1. 身份认证(Authentication) - 支持 OAuth 2.0 / OpenID Connect - Agent Card 中声明认证方式 - Client 在请求中携带 Bearer Token 请求示例: POST /a2a HTTP/1.1 Authorization: Bearer eyJhbGciOiJSUzI1NiIs... Content-Type: application/json 2. 权限控制(Authorization) - Agent Card 的 skills 定义了能力边界 - Client 只能请求 Agent 声明支持的技能 - 服务端可以基于 Token 中的 scope 做细粒度权限控制 3. 传输安全 - 强制 HTTPS(TLS 加密) - 防止中间人攻击和数据窃听 4. 输入验证 - JSON-RPC 格式校验 - 参数类型和范围检查 - 防止恶意 Payload ``` 安全架构示意:  *图:A2A 通信的鉴权方式:HTTPS + OAuth2* ```text ┌──────────┐ HTTPS + OAuth2 ┌──────────┐ │ Client │ ───────────────► │ Remote │ │ Agent │ │ Agent │ │ │ Bearer Token │ │ │ │ in Header │ 验证 Token│ │ │ │ 检查权限 │ └──────────┘ └──────────┘ ``` 为什么 A2A 的安全比 MCP 更"重"?因为 MCP 大多是本地进程调用,安全主要靠**进程隔离**;而 A2A 是**跨网络、跨组织**的远程服务,必须依赖标准的 Web 安全机制(TLS + OAuth2)来防止中间人窃听和越权调用。另外,Agent Card 里的 `skills` 本身就是一份"能力白名单",服务端应据此拒绝未声明的技能请求——这属于最小权限原则的落地。 工程上要特别注意:**认证(Authentication)和授权(Authorization)是两件事**。认证回答"你是谁"(校验 Bearer Token 是否有效),授权回答"你能做什么"(校验该 Token 的 scope 是否覆盖所请求的 skill)。只做前者不做后者,等于"任何登录用户都能调用全部技能",这在多租户场景下是严重越权。此外,传输层强制 HTTPS 是底线而非可选项——A2A 是跨网络调用,明文 HTTP 会直接把 Token 和任务内容暴露给中间人。需要提醒的是,具体认证方案的字段与流程需以当版本规范为准。 ## 五、工程实践与踩坑 ### Q:把现有 Agent 暴露为 A2A 服务,需要做哪些改造? A:结论先行——核心是补齐三件事:实现 Agent Card 与 A2A 的 HTTP/JSON-RPC 端点、把请求映射为内部 Agent 的初始状态并持久化 Task/检查点/Artifact、对外隐藏内部状态细节。 具体清单: ```text 改造清单: 1. 暴露发现入口 GET /.well-known/agent.json → 返回 Agent Card(name/url/skills/capabilities/authentication) 2. 实现 A2A 端点 tasks/send、tasks/get、tasks/cancel(可选 sendSubscribe / pushNotification) 3. 请求映射 把 A2A message.parts 转成内部 Agent 的初始 state / 输入 4. 持久化 Task 状态、Checkpoint(断点)、Artifact 都要能跨请求存活 5. 生命周期对齐 内部状态机 → 映射到 submitted/working/input-required/completed/failed/canceled 6. 安全 校验 Bearer Token、按 skills/scope 做权限控制、强制 HTTPS 7. 可选流式 把内部事件转成 SSE 的 task-status / task-artifact-update ``` 最容易被忽略的是第 4、5 两点:**A2A 的 Task 天然要求"跨请求存活"**,如果你内部的 Agent 是无状态的(每次请求重跑来一遍),就无法支持 `input-required` 之后的"继续"语义。所以要么引入 Checkpoint,要么把 Task 状态存到外部存储。 ### Q:Remote Agent 返回 `input-required` 时,Client 应该怎么处理? A:结论先行——把缺失信息转成用户能理解的追问,校验补充后**用同一个 Task 继续**,而不是新建一个无关任务;如果用户无法提供,应允许取消或返回部分结果,并记录原因。 处理流程: ```text 1. 收到 status = input-required 2. 读出 status.message(例如"请提供代码的编程语言") 3. 转成对用户的追问(保留原始 Task ID) 4. 用户补充 → 用 tasks/send(同一个 Task ID)继续 5. 用户拒绝/无法提供 → tasks/cancel 或请求返回部分结果,并留痕原因 ``` 为什么不能新建任务?因为新任务会丢掉已完成的中间结果(比如已经解析好的依赖关系),既浪费成本,也可能让结果前后不一致。 ### Q:A2A 落地时最容易踩的坑有哪些? A:结论先行——最常踩的是"把长任务当同步接口写""Artifact 双形态不一致""忽略 input-required 与取消语义""鉴权只做了认证没做授权"这几类。 ```text 踩坑清单: 1. 把异步任务写成同步阻塞 代码审查动辄几十秒,直接用 HTTP 同步等待会超时; 应走 working + tasks/get 轮询 或 sendSubscribe 流式。 2. Artifact 文本与结构化数据不一致 两者必须引用同一任务版本,建议结构化数据为唯一事实源。 3. input-required 被当成错误 它是中间态,不是失败;把它当异常会导致"任务其实没结束却报错"。 4. 取消语义没落实 tasks/cancel 要真的能打断内部执行,而不是只改状态标记。 5. 只认证不授权 校验了 Token 却不对照 skills/scope,等于任何合法用户都能调所有技能。 6. Agent Card 与实际能力不符 声明了 streaming 却不返回 SSE,Client 会一直等。 能力声明要如实填写,避免"名片吹牛"。 7. 断线重连没做去重 resubscribe 后可能重发已收到的事件,前端需按事件/片段去重。 ``` ## 小结 - A2A 是 Google 发布、后捐赠给 Linux Foundation 的 Agent 间通信开放协议,用于解决跨框架、跨厂商 Agent 无法互通的问题。 - 四个核心概念:Agent Card(能力发现)、Task(任务管理)、Message/Part(消息结构)、Artifact(输出产物)。 - 技术栈为 HTTP + JSON-RPC 2.0 + SSE,主打普适与低门槛;方法集围绕 Task 生命周期展开(send/get/cancel/sendSubscribe/pushNotification/resubscribe)。 - 安全上内建 OAuth 2.0 / OpenID Connect 与强制 HTTPS,Agent Card 的 skills 即能力白名单。 - 落地关键是"任务跨请求存活":内部状态机要能映射到 A2A 状态,并把 Task、Checkpoint、Artifact 持久化。 - 与 MCP 互补:MCP 管工具调用,A2A 管 Agent 协作。 把这份协议当成"Agent 世界的 HTTP"来理解,会更容易记住它的位置:它不解决"Agent 怎么变聪明",只解决"聪明的 Agent 怎么互相找到、互相委托"。 ## 思考题 1. A2A 的 Agent Card 和 OpenAPI 的 Swagger 文档有什么异同? - 参考思路:两者都用于能力发现与集成说明;Swagger 精确描述 HTTP 接口、字段与操作,Agent Card 描述 Agent 的技能、输入输出模式、能力与认证信息,且技能描述更语义化、更适合开放的任务委托。 2. 如果你要把现有的 LangGraph Agent 暴露为 A2A 服务,需要做哪些改造? - 参考思路:实现 Agent Card 与 A2A 的 HTTP/JSON-RPC 端点,把请求映射为 LangGraph 初始状态,并持久化 Task、检查点与 Artifact;支持状态查询、取消、认证、超时与可选流式事件,同时隐藏内部状态细节。 3. Remote Agent 返回 `input-required` 时,Client 应如何处理? - 参考思路:把缺失信息转成可理解的追问,校验用户补充后用**同一 Task** 继续,而不是重新创建无关任务;用户无法提供时允许取消或返回部分结果并记录原因。 4. 为什么 Artifact 应同时包含可读摘要和结构化结果? - 参考思路:可读摘要便于用户与人工审核,结构化数据便于下游 Agent 自动路由、比较、统计与重试;两者应引用同一任务版本,避免语义不一致。
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入