鸿蒙智能体开发实战：46.端A2A协议 - 智能体与鸿蒙应用直连

## 前言A2AAgent-to-Agent协议是鸿蒙智能体平台中用于智能体之间直接通信的标准化协议。它允许HarmonyOS设备上的每个应用都可以实现自己的应用内AgentApp Agent与小艺的Client Agent通过标准协议进行对话实现跨应用的智能协作。本文是「鸿蒙智能体开发实战」系列的第四十六篇系统讲解端A2A协议的技术规范、核心组件和开发实现帮助开发者为自己的HarmonyOS应用接入智能体能力。前置条件熟悉HarmonyOS Ability扩展开发。本文档参考鸿蒙端A2A对接规范V0.6。一、A2A协议概述1.1 什么是端A2A端A2AEnd-side Agent-to-Agent是华为鸿蒙系统中小艺Client Agent与应用内Agent之间的通信协议。与传统的端插件不同A2A协议赋予应用内Agent主动感知上下文、处理复杂任务、呈现自定义UI的能力将智能交互从工具调用升级为智能体协作。上图展示了端A2A协议的总体架构小艺Client Agent通过A2A协议与各App内的Agent建立连接实现跨应用的智能协作。1.2 A2A vs 端插件特性端A2A协议端插件通信模式双向、持续会话单向、一次调用上下文管理支持会话级Context无上下文任务生命周期Task管理支持长时任务单次请求-响应UI能力自定义卡片无交互复杂度高多轮对话、状态流转低工具调用实现复杂度较高较低选择建议如果应用只需要暴露简单功能给智能体调用使用端插件即可如果应用需要实现有状态的智能对话或需要主动推送信息和呈现自定义UI则选择端A2A协议。二、核心概念与层次模型2.1 四层抽象模型端A2A协议定义了从粗到细的四层抽象模型Context会话 └── Task任务× N └── Artifact产出物× N └── Part分片× N层次说明生命周期Context会话的逻辑容器由Agent分配contextId持续有效直到失效Task任务的完整处理单元由Agent分配taskId从发起到终止ArtifactTask的产出单元同组内容组合呈现随Task生命周期PartArtifact的组成分片如文本、卡片随Artifact生命周期2.2 Context - 会话管理Context是会话的逻辑容器将一段交互过程中的相关Task归组在一起{method:tasks/send,params:{task:{query:帮我订一张下周三从北京到上海的机票}}}{method:tasks/send,result:{contextId:ctx_abc123,taskId:task_001,artifactId:art_001,parts:[{type:text,text:好的我来帮您查询下周三北京到上海的航班信息。}]}}会话失效场景Agent主动失效返回错误码99911222小艺收到后不携带contextId重放请求小艺主动重置小艺不携带contextId发起新请求2.3 Task - 任务生命周期Task状态流转CREATED → PROCESSING → COMPLETED ↓ ↓ └── CANCELED ┘状态说明CREATED任务已创建等待处理PROCESSING任务正在处理中可发送中间状态更新COMPLETED任务处理完成CANCELED任务被取消2.4 Artifact与Part// 第一次响应思考过程{taskId:task_001,artifactId:art_001,partId:part_001,type:text,content:正在查询北京到上海的航班信息...}// 第二次响应最终结果{taskId:task_001,artifactId:art_002,parts:[{type:text,content:已为您找到以下航班},{type:card,content:{cardType:flight_list,flights:[{airline:国航CA1234,time:08:00-10:30,price:¥980},{airline:东航MU5678,time:10:30-13:00,price:¥860}]}}]}三、AgentExtensionAbilityAgentExtensionAbility是接入端A2A协议的必需核心组件。在DevEco Studio中通过New → Extension Ability → Agent创建IDE会自动生成三个文件。3.1 文件结构entry/src/main/ ├── module.json5 # 注册AgentExtensionAbility ├── resources/agent_config/ │ └── agent_config.json # AgentCard配置 └── ets/AgentExtAbility/ └── AgentExtensionAbility.ets # A2A通信实现3.2 配置AgentCardagent_config.json是Agent向小艺声明自身能力的核心配置{agentCards:[{agentId:flight-agent,name:机票助手,description:提供航班搜索与预订服务支持多城市、多日期查询,iconUrl:https://example.com/icon.png,version:1.2.0,capabilities:{streaming:true,pushNotifications:true,stateTransitionHistory:false},defaultInputModes:[text/plain,application/json],defaultOutputModes:[text/plain,application/json],skills:[{id:flight-search,name:航班搜索,description:根据出发地、目的地、日期搜索最优航班,tags:[flight,search],examples:[帮我查下周三从北京到上海的上午航班]}]}]}字段说明必需agentId唯一标识Agent的ID是nameAgent显示名称是descriptionAgent功能描述是capabilities能力声明流式、推送等否skills技能列表推荐3.3 注册配置{module:{extensionAbilities:[{name:AgentExtensionAbility,srcEntry:./ets/AgentExtAbility/AgentExtensionAbility.ets,description:机票助手Agent,type:agent,exported:true,metadata:[{name:ohos.agent.agent_config,resource:$profile:agent_config}]}]}}四、关键方法与生命周期4.1 方法总览exportdefaultclassMyAgentExtensionAbilityextendsAgentExtensionAbility{// 1. Ability被拉起时触发onCreate(want:Want):void{}// 2. 与小艺建立连接时触发onConnect(want:Want,proxy:AgentHostProxy):void{}// 3. 密钥协商可选onAuth(proxy:AgentHostProxy,data:string):void{}// 4. 小艺发送消息时触发onData(proxy:AgentHostProxy,data:string):void{}// 5. 连接断开时触发onDisconnect(want:Want,proxy:AgentHostProxy):void{}// 6. Ability销毁时触发onDestroy():void{}}4.2 onCreate - 初始化onCreate(want:Want):void{console.info(Agent Extension Ability created);constsessionContextwant.parameters?.[ability.want.params.context];this.initResources();this.loadUserPreferences();}4.3 onConnect - 建立连接privateagentProxy:AgentHostProxy|nullnull;onConnect(want:Want,proxy:AgentHostProxy):void{console.info(Agent connected to Xiaoyi);this.agentProxyproxy;// 必须保存proxythis.sendWelcomeMessage();}重要proxy对象必须在此处保存后续的sendData、authorize等操作都通过它发起。4.4 onAuth - 密钥协商onAuth(proxy:AgentHostProxy,data:string):void{constauthDataJSON.parse(data);constnegotiatedResultthis.performKeyAgreement(authData);proxy.authorize(JSON.stringify(negotiatedResult));}privateperformKeyAgreement(data:any):object{return{status:success,sessionKey:generated-session-key};}4.5 onData - 核心消息处理方法onData(proxy:AgentHostProxy,data:string):void{constmessageJSON.parse(data);switch(message.method){casetasks/send:this.handleTaskSend(proxy,message.params);break;casetasks/cancel:this.handleTaskCancel(proxy,message.params);break;casecontext/clear:this.handleContextClear(proxy,message.params);break;}}privatehandleTaskSend(proxy:AgentHostProxy,params:any):void{const{taskId,query}params.task;// 首帧确认收到proxy.sendData(JSON.stringify({method:tasks/send,result:{contextId:this.currentContextId,taskId:taskId,artifactId:art_${Date.now()},parts:[{type:text,text:正在处理您的请求...}]}}));// 异步处理任务this.processTask(query).then(result{// 返回最终结果proxy.sendData(JSON.stringify({method:tasks/send,result:{contextId:this.currentContextId,taskId:taskId,artifactId:art_${Date.now()1},parts:[{type:text,text:result.summary},{type:card,content:result.cardData}],state:completed}}));});}4.6 onDisconnect与onDestroyonDisconnect(want:Want,proxy:AgentHostProxy):void{console.info(Agent disconnected);this.currentContextIdnull;this.activeTasks.clear();this.agentProxynull;}onDestroy():void{console.info(Agent Extension Ability destroyed);this.releaseResources();}4.7 proxy核心方法方法说明调用时机sendData向小艺发送处理结果onData中调用authorize向小艺回传密钥协商结果onAuth中调用// 发送Task状态更新proxy.sendData(JSON.stringify({method:tasks/statusUpdate,params:{taskId:task_001,state:processing,progress:0.5,message:正在查询航班数据...}}));// 回传认证结果proxy.authorize(JSON.stringify({status:approved,errorMessage:null}));五、AgentUIExtensionAbility5.1 创建UI Extension如果Agent需要以自定义卡片形式呈现内容可以实现AgentUIExtensionAbility可选{extensionAbilities:[{name:AgentUIExtensionAbility,srcEntry:./ets/AgentUIExtAbility/AgentUIExtAbility.ets,description:机票卡片UI,type:agentUI,exported:true}]}5.2 实现UI卡片import{UIExtensionAbility,UIExtensionContentSession}fromkit.AbilityKit;exportdefaultclassAgentUIExtAbilityextendsUIExtensionAbility{onSessionCreate(want:Want,session:UIExtensionContentSession):void{constpayloadwant.parameters?.[ability.want.params.payload]asstring;constcardDataJSON.parse(payload||{});session.loadContent(pages/FlightCardPage,{context:this.context,params:{flights:cardData.flights||[],title:cardData.title||航班信息}});}}5.3 A2A协议返回UI卡片{method:tasks/send,result:{contextId:ctx_abc123,taskId:task_001,parts:[{type:text,text:为您找到以下航班},{type:uiExtensionCard,payload:{title:北京→上海 航班列表,flights:[{airline:国航CA1234,time:08:00-10:30,price:¥980},{airline:东航MU5678,time:10:30-13:00,price:¥860}]}}],state:completed}}注意A2A约定传参通过ability.want.params.payload的参数进行传递。卡片的具体实现与标准UIExtensionAbility一致。六、完整通信时序6.1 标准对话流程小艺Client Agent App Agent │ │ │ 1. 建立连接 │ │───────────────────── │ │ │ │ 2. tasks/send │ │───────────────────── │ │ │ │ 3. 首帧响应 │ │───────────────────── │ │ │ │ 4. 中间状态更新 │ │───────────────────── │ │ │ │ 5. 最终结果(含卡片) │ │───────────────────── │ │ │ │ 6. 新Task... │ │ │ │ 7. 断开连接 │6.2 密钥协商流程小艺Client Agent App Agent │ │ │ 1. 密钥协商请求 │ │───────────────────── │ │ │ │ 2. onAuth触发 │ │ │ │ 3. authorize回传 │ │───────────────────── │ │ │ │ 4. 继续A2A通信 │七、实战技巧7.1 会话管理privateactiveContexts:Mapstring,ContextStatenewMap();interfaceContextState{contextId:string;userId:string;createdAt:number;lastActiveAt:number;activeTasks:Setstring;}privatecreateContext(agentId:string):string{constcontextIdctx_${agentId}_${Date.now()};this.activeContexts.set(contextId,{contextId,userId:,createdAt:Date.now(),lastActiveAt:Date.now(),activeTasks:newSet()});returncontextId;}7.2 流式输出优化asyncfunction*streamResponse(proxy:AgentHostProxy,taskId:string){constchunks[正在,查询,北京,到,上海,的,航班];for(constchunkofchunks){proxy.sendData(JSON.stringify({method:tasks/send,result:{taskId,artifactId:art_stream_${Date.now()},parts:[{type:text,text:chunk}]}}));awaitnewPromise(resolvesetTimeout(resolve,100));yieldchunk;}}八、FAQ与排查指南8.1 常见问题问题可能原因解决方案Agent无法连接配置文件错误检查agent_config.json格式和module.json5配置onData收不到消息连接已断开检查onConnect中的proxy保存逻辑卡片显示异常payload传递失败确认使用ability.want.params.payload传参会话失效contextId过期检查Agent主动失效逻辑中的错误码999112228.2 开发调试建议使用日志追踪在每个生命周期方法中添加console.info日志验证AgentCard配置确保skills的描述准确帮助小艺正确路由优先实现基础流程先实现标准对话流程再添加密钥协商等可选功能真机验证端A2A需要真机环境测试模拟器可能无法完整验证总结本文详细介绍了鸿蒙端A2A协议的核心概念、组件实现和通信流程。端A2A协议是鸿蒙智能体生态从工具调用迈向智能体协作的关键基础设施。通过实现AgentExtensionAbility开发者可以让自己的HarmonyOS应用拥有自主对话、任务管理、自定义UI等智能体能力实现与小艺Client Agent的深度协作。关键要点A2A协议的四层抽象模型Context/Task/Artifact/Part提供了灵活的会话管理能力AgentExtensionAbility是必需的核心组件管理全生命周期通信AgentUIExtensionAbility提供自定义卡片的呈现能力合理使用流式输出和状态更新可以显著提升用户体验如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源端A2A协议技术规范链接端A2A协议消息指令定义链接云A2A协议技术规范链接云A2A协议消息指令定义链接AgentExtensionAbility样例代码链接A2A基础配置文档链接鸿蒙智能体开发实战系列链接HarmonyOS ExtensionAbility开发链接