本文基于 HarmonyOS 7API 26官方《通过 AgentAbilityExtension 实现智能体间 A2A 协议通信》开发指导与 Agent Framework Kit 相关接口参考整理。文中代码示例为说明问题自写接口名均出自官方文档并标注出处方法签名与配置细节以官方 SDK 为准未核实到底层调用细节的部分以示意性伪代码呈现并标注文中不含实测数据场景为按官方能力描述做的推演运行表现以真机实测为准7.0 相关能力需升级至 HarmonyOS 7 并以实际支持机型为准。引子一句赶飞机两个 App 自己谈成了兄弟们好我是V哥。先描述一个按官方能力推演的场景用户对小艺说明早七点半赶飞机帮我安排。系统拆解意图找到行程应用登记的日程智能体日程智能体算出七点十分出门然后把需要一辆车这个子意图交回系统系统撮合到打车应用登记的打车智能体两边按 A2A 协议把时间、地点、车型谈拢用户确认后订单落地行程卡片自动更新运行表现以真机实测为准。全程用户没打开任何一个 App。上一期V哥写过 Skill 化——应用把功能递进系统的意图分发池这一期往上走一层智能体和智能体之间自己谈。这就是 HarmonyOS 7API 26新增的 Agent A2A 能力官方发布说明。官方在发布说明里举的例子是健身 Agent训练前中后的记录、指导、回顾、问答全链路健身管理。V哥把日程 打车这个组合拆成三件事讲清楚A2A 到底协作了什么、智能体怎么把自己挂进系统、一单是怎么按状态机谈成的。一、A2A 不是接口互调是意图协商先纠正一个最常见的误解。很多同学一听智能体之间通信脑子里浮现的是 A 应用 import B 应用的 SDK然后调 B 的方法。那叫接口互调不叫 A2A。接口互调的前提是调用方认识对方知道对方是谁、方法签名是什么、出错返回什么。而 A2A 的前提恰恰相反——双方互不相识。官方对这套机制的表述是通过 AgentAbilityExtension 实现智能体间 A2A 协议通信A2AAgent to Agent协议用于智能体之间的通信。A2A 服务端负责接收客户端请求、触发智能体执行任务、更新任务状态和返回执行结果。V哥从官方的基本概念里读出的关键是几个名词撑起的协商结构概念官方定义在一单生意里的角色Agent CardJSON 元数据文档描述智能体的身份、能力、端点地址、技能和认证要求生意场上的名片先递名片再谈事Task有唯一标识和明确定义生命周期的有状态工作单元这单生意本身全程可跟踪Message客户端与智能体之间一次通信的单元带 user / agent 角色谈判桌上说的每一句话Artifact任务过程中生成的有形交付物有唯一的产物 ID 和名称成单后的交付订单、票据、结果TaskState已提交、工作中、需要用户输入、已完成、已取消、已失败、已拒绝、需要认证谈判进度条注意认证要求这三个字。接口互调的世界里权限是编译期定死的A2A 的世界里智能体在名片上写清楚找它办事需要什么资质客户端解析 Agent Card 才知道如何安全有效地交互。发现、认证、协商、交付四个环节都长在协议里而不是长在某一次硬编码里——这是V哥判断A2A 不是接口互调的依据。还有一条官方边界划在前头实现 A2A 协议通信从 API 26.0.0 开始支持AgentExtensionAbility 首批接口从 API 24 起就有仅支持 Stage 模型且不支持在 har 包中使用接口参考。7.0 相关能力需升级至 HarmonyOS 7 并以实际支持机型为准。二、把智能体挂进系统Agent Card 与 A2A 服务端上一期 Skill 化的活儿是写契约这一期的活儿是写名片 写服务端。官方给的开发路径很清晰服务端继承 AgentExtensionAbility 获得跨 App 进程通信能力再通过 Agent Framework Kit 创建支持 A2A 协议的 Server 实例。V哥的打车智能体骨架这么写接口名出自官方开发指导方法签名以官方 SDK 为准// RideAgentExtAbility.ets —— 打车智能体的 A2A 服务端骨架import{hilog}fromkit.PerformanceAnalysisKit;import{common,Want,AgentExtensionAbility}fromkit.AbilityKit;import{RequestContext,createA2AServer,Server,TaskState,Role}fromkit.AgentFrameworkKit;constTAGRideA2AServerexportdefaultclassRideAgentExtAbilityextendsAgentExtensionAbility{// 服务端实例负责处理智能体通信和任务生命周期管理privateserver:Server|nullnull;// 核心业务逻辑A2A Server 收到客户端请求后触发privateagentOnData(method:string,context:RequestContext){// V哥先做防御从结构化上下文里取 AgentID取不到直接拒绝constagentId:stringcontext.getAgentId()??;if(!agentId){hilog.error(0x0000,TAG,Agent ID not found in request context);return;}consttaskId:stringcontext.getTaskId()??;switch(method){caseExecute:// ① 先报开工把任务推进到工作中this.server?.updateStatus(taskId,{state:TaskState.WORKING,message:{messageId:msg1,role:Role.AGENT,parts:[{mediaType:text/plain,text:正在为你锁定车辆...}]}});// ② 业务跑完把交付物订单结果作为产物挂到任务上this.server?.addArtifact(taskId,{artifactId:ride-order,parts:[{mediaType:application/json,text:{orderNo:...,eta:6min}}]});// ③ 最后通知任务完成整单闭环this.server?.updateStatus(taskId,{state:TaskState.COMPLETED,message:{messageId:msg3,role:Role.AGENT,parts:[{mediaType:text/plain,text:车辆已预订成功}]}});break;caseCancel:// 用户取消收尾逻辑写在这里别让任务悬着hilog.info(0x0000,TAG,Cancel called);break;default:break;}}// 实例创建完成首次收到请求时创建 A2A ServerasynconCreate(want:Want){try{constcardthis.context.agentCard;// 智能体名片来自组件上下文this.servercreateA2AServer(card,this.agentOnData);}catch(error){hilog.error(0x0000,TAG,Failed to create server:${error});}}// 客户端建连开门营业启动服务端onConnect(want:Want,proxy:common.AgentHostProxy){this.server?.start();}// 收到请求体转交 server.onMessage回包走 proxy.sendDataasynconData(proxy:common.AgentHostProxy,data:string){this.server?.onMessage(data,(response:string){proxy.sendData(response);});}// 断连与销毁打烊回收资源onDisconnect(want:Want,proxy:common.AgentHostProxy){this.server?.stop();}onDestroy(){this.server?.stop();}}V哥把官方要求的生命周期方法全部列出来了因为这套骨架的时序本身就是协议create建名片→ start开门营业→ onMessage接单→ stop打烊。onCreate里那句this.context.agentCard值得多看一眼——智能体的名片不是在代码里现场拼的它来自组件上下文是随应用声明与配置登记好的Agent Card 的具体配置方式以官方 SDK 文档为准。对照上一期会发现一个同构关系SKILL.md 是 Skill 在意图分发池里的简历Agent Card 就是智能体在协作网络里的简历。区别在于智能体的简历多了两项硬信息——端点地址和认证要求。功能被调可以匿名智能体协作必须验明正身。三、一单是怎么谈成的状态机走完才算数把引子里那个场景的协作链路画出来链路里V哥最想展开的是意图协商这一段因为它和接口互调的差别全在这里。日程智能体发起打车需求后双方不是一次调用定生死而是在 Task 的状态机里推进示意性伪代码描述协商语义TaskState 各枚举字段以官方 SDK 为准 Task 已提交 └─ 打车 Agent工作中WORKING正在匹配车辆 └─ 打车 Agent需要用户输入跨 App 动作用户拍板确认车型与价格 └─ 用户确认 └─ 打车 Agent工作中锁定车辆 └─ 已完成COMPLETED Artifact订单交付两个值得停下来想的点。第一需要用户输入是写进协议的状态不是你自定义的弹窗。官方列出的任务状态里有这么一项说明鸿蒙的 A2A 在协议层面就承认智能体协作走到有副作用的动作时必须停下来让人拍板。V哥的判断是——查天气、算出发时间这类只读动作可以自动流转而下单、扣款这种动作就该老老实实停在需要用户输入把确认权还给用户。协议给了你踩刹车的位置别把油门焊死。第二Artifact 和 Message 是两种东西。谈判过程中说的话是 Message——指令、上下文、状态更新最终交付的是 Artifact——有唯一 ID 和名称的交付物。把订单结果当聊天消息发出去下游就没法可靠地引用它这在多轮、多智能体的协作里是致命的。还有一类特殊请求单独提一下官方定义了 PerceptionSuggest 类型的请求用于小艺感知用户当前所在 App、向智能体请求推荐内容AgentChips 场景交互流程有单独文档。也就是说你的智能体不只是被别的智能体调还能在小艺的推荐位上主动露脸。四、V哥的三条判断① 撮合靠系统被撮合的资格靠自己。日程智能体不需要认识打车智能体——它把子意图交给系统系统按 Agent Card 撮合。官方把这一范式概括为意图即服务小艺作为系统级智能体承担意图理解与服务分发官方发布说明。撮合质量取决于系统而轮不轮得到你进场取决于名片上的能力描述写得清不清——写得含糊协商还没开场你就出局了。② 端 A2A 与云 A2A 是双轨不是二选一。官方口径里端侧保障低时延本地响应、隐私数据不出端云侧支撑复杂任务的深度推理。日程、行程这类敏感数据走端侧跨城比价、长程规划这类重推理走云侧按任务属性分轨别一刀切。③ 开发者的活儿从写页面变成了写能力。这期和上一期合起来看脉络很清楚Skill 化让功能被系统调用A2A 让智能体彼此协商界面退居最后一步能力登记成了第一等公民。V哥的原话以前你的应用是一座楼用户找门牌号现在你的应用是一个谈判代表系统按名片找它谈事。代表的水平体现在名片和谈判记录Agent Card 与任务状态机上不体现在装修上。五、收尾协作网络的价值随节点超线性增长A2A 的红利有个特点单看你自己的智能体价值有限网络里接入的智能体越多每一次协商的可能组合就越多。日程智能体今天跟打车谈明天可能跟机票、酒店、会议助手谈——而你的接入成本就是一张名片加一个服务端骨架。7.0 刚发布协作网络里的节点还不多。上一期V哥说 Skill 化是新门票这一期补一句A2A 是你在智能体协作网络里的席位席位放出来的时候坐上去的人最少。参考与出处本文的协议概念、接口名与能力描述来自以下官方文档与发布说明通过 AgentAbilityExtension 实现智能体间 A2A 协议通信AI / Agent Framework Kitohos.app.agent.AgentExtensionAbility 接口参考Ability KitA2A Server 模块 API 文档小艺 AgentChips 交互流程HarmonyOS 7API 26面向 App 与 Agent 开放 Skill、Agent 及 AI 开放能力官方新闻HarmonyOS 新能力一览7 / API 26最后一句图标时代比的是谁的门面亮A2A 时代比的是谁的名片硬——把 Agent Card 当名片写把任务状态机当谈判记录记下一个被系统拉去谈事的就是你的智能体。