鸿蒙智能体开发实战A2A 模式消息规范前言在鸿蒙 Agent 通信协议A2A 模式中消息规范是确保智能体与客户端正确通信的关键。本文严格遵循华为官方定义的 A2A 协议规范详细介绍消息格式、数据结构和状态流转。本文基于华为鸿蒙官方 A2A 协议规范编写确保与鸿蒙设备端兼容性。协议总体架构鸿蒙 A2A 协议采用JSON-RPC 2.0作为基础通信协议通过SSEServer-Sent Events实现流式输出。核心端点所有消息统一通过/agent/message端点处理POST /agent/message Headers: Content-Type: application/json agent-session-id: session-id (initialize 方法除外)A2A 基础配置与输出设置完成协议理解后在小艺开放平台上创建 A2A 智能体时需要正确配置基础信息和输出设置。基础配置入口A2A 基础配置是 A2A 模式必填节点入口如下图所示基础配置详情配置页面包含 API URL、会话维持方式、认证信息、方法声明等核心参数输出设置A2A 输出设置用于绑定响应卡片绑定卡片添加输出后可绑定具体卡片请求数据结构定义通用请求格式{jsonrpc:2.0,id:{{全局唯一消息序列号字符串}},method:{{方法名}},params:{id:{{请求任务唯一 ID}},sessionId:{{客户端会话 ID}},agentLoginSessionId:{{登录身份凭证 ID}},message:{role:user,parts:[...]}}}Message Parts 类型说明客户端发送消息时内容放在parts数组中支持以下类型kind说明字段结构text文本内容{ kind: text, text: 内容 }file文件/图片{ kind: file, file: {...} }data结构化数据{ kind: data, data: {...} }text 类型用户输入的文本内容{kind:text,text:用户输入 Query 或子任务 Query}file 类型发送文件或图片{kind:file,file:{name:文件名,mimeType:MIME 类型,bytes:文件的字节码与 uri 互斥,uri:文件的 URI 地址与 bytes 互斥}}data 类型结构化数据用于存放用户参数、端侧事件等{kind:data,data:{events:[...],// 端侧事件userInputInfo:{...},// 用户输入信息variables:{...}// 客户端变量}}响应数据结构定义响应总体概览服务器返回的响应使用 JSON-RPC 2.0 格式{jsonrpc:2.0,id:{{从请求中取出的消息序列号}},result:{// 结果对象TaskStatusUpdateEvent 或 TaskArtifactUpdateEvent},error:{code:0,message:success}}两种核心事件类型服务器给客户端返回时使用两种事件类型事件类型kind 值用途TaskStatusUpdateEventstatus-update推送任务中间状态TaskArtifactUpdateEventartifact-update推送任务中间处理结果带内容输出TaskStatusUpdateEvent - 状态更新事件结构定义{jsonrpc:2.0,id:{{消息序列号}},result:{taskId:{{任务 ID与请求中的 id 一致}},kind:status-update,final:false,status:{message:{role:agent,parts:[{kind:text,text:{{状态描述文本}}}]},state:{{任务状态}}}},error:{code:0,message:success}}任务状态state枚举值状态值说明使用场景submitted已提交任务刚被接收时working处理中正在执行任务input-required需要输入需要用户提供更多信息completed已完成任务成功完成canceled已取消用户取消任务failed失败任务执行失败unknown未知未知状态状态更新示例submitted 状态{jsonrpc:2.0,id:msg-001,result:{taskId:task-001,kind:status-update,final:false,status:{message:{role:agent,parts:[{kind:text,text:正在理解您的需求...}]},state:submitted}},error:{code:0,message:success}}working 状态{jsonrpc:2.0,id:msg-001,result:{taskId:task-001,kind:status-update,final:false,status:{message:{role:agent,parts:[{kind:text,text:正在思考中...}]},state:working}},error:{code:0,message:success}}TaskArtifactUpdateEvent - 内容更新事件结构定义{jsonrpc:2.0,id:{{消息序列号}},result:{taskId:{{任务 ID}},kind:artifact-update,append:false,lastChunk:true,final:false,artifact:{artifactId:{{本条 Artifact 的唯一 ID}},parts:[...]}},error:{code:0,message:success}}Artifact Parts 类型说明kind说明字段结构reasoningText深度思考内容{ kind: reasoningText, reasoningText: 内容 }text正文内容{ kind: text, text: 内容 }data结构化数据{ kind: data, data: {...} }reasoningText 类型用于展示深度思考过程、优化后的提示词等{kind:reasoningText,reasoningText:优化后的提示词\n详细内容...}text 类型用于展示正文内容支持 Markdown 格式{kind:text,text:这是智能体的回复内容...}data 类型用于展示卡片、端侧指令、推荐问题等结构化数据{kind:data,data:{cardsInfo:[{cardName:custom_card,cardData:{...},displayType:DisplayFaCard}]}}关键字段说明字段类型默认值说明appendbooleanfalse是否追加到前序片段lastChunkbooleantrue是否是流式输出的最后一个片段finalbooleanfalseSSE 流是否结束true会断开通道注意一次会话请求final 为 true 结束允许若干流式输出。每次流式输出以lastChunk为true结束。任务结束必须设置final为true。完整流式交互示例场景智能助手对话步骤 1客户端发起请求POST/agent/messageHeaders:Content-Type:application/json agent-session-id:8f01f3d172cd4396a0e535ae8aec6687{jsonrpc:2.0,id:msg-001,method:message/stream,params:{id:task-001,sessionId:session-001,message:{role:user,parts:[{kind:text,text:你好请介绍一下你自己}]}}}步骤 2服务器返回 submitted 状态{jsonrpc:2.0,id:msg-001,result:{taskId:task-001,kind:status-update,final:false,status:{message:{role:agent,parts:[{kind:text,text:正在理解您的需求...}]},state:submitted}},error:{code:0,message:success}}步骤 3服务器返回 working 状态{jsonrpc:2.0,id:msg-001,result:{taskId:task-001,kind:status-update,final:false,status:{message:{role:agent,parts:[{kind:text,text:正在思考中...}]},state:working}},error:{code:0,message:success}}步骤 4服务器返回思考内容reasoningText{jsonrpc:2.0,id:msg-001,result:{taskId:task-001,kind:artifact-update,append:false,lastChunk:true,final:false,artifact:{artifactId:task-001-thinking,parts:[{kind:reasoningText,reasoningText:用户想要了解我的基本信息和功能...}]}},error:{code:0,message:success}}步骤 5服务器流式返回正文内容text第一个片段{jsonrpc:2.0,id:msg-001,result:{taskId:task-001,kind:artifact-update,append:false,lastChunk:false,final:false,artifact:{artifactId:task-001-response,parts:[{kind:text,text:你好我是智能助手}]}},error:{code:0,message:success}}第二个片段追加{jsonrpc:2.0,id:msg-001,result:{taskId:task-001,kind:artifact-update,append:true,lastChunk:false,final:false,artifact:{artifactId:task-001-response,parts:[{kind:text,text:可以帮你解答问题、完成任务。}]}},error:{code:0,message:success}}最后一个片段{jsonrpc:2.0,id:msg-001,result:{taskId:task-001,kind:artifact-update,append:true,lastChunk:true,final:false,artifact:{artifactId:task-001-response,parts:[{kind:text,text:有什么可以帮你的吗}]}},error:{code:0,message:success}}步骤 6服务器返回完成状态{jsonrpc:2.0,id:msg-001,result:{taskId:task-001,kind:status-update,final:true,status:{message:{role:agent,parts:[{kind:text,text:任务完成}]},state:completed}},error:{code:0,message:success}}错误响应格式JSON-RPC 错误结构{jsonrpc:2.0,id:{{消息序列号}},result:{taskId:{{任务 ID}},kind:status-update,final:true,status:{state:failed}},error:{code:{{错误码}},message:{{错误描述}}}}常见错误码错误码说明0成功400请求参数错误401认证失败Session ID 无效-32601方法不存在500服务器内部错误99911114内容不合规99911113流控限制六、端A2A协议规范除了云端A2A协议鸿蒙还支持端侧A2A协议用于小艺Client Agent与应用内Agent的直接通信。6.1 核心概念端A2A协议定义了四个层次的概念模型Context会话 │ 由Agent管理会话并分配contextId相同的contextId标识同一个会话 │ └── Task任务× N │ 一件事从发起到完成的全过程期间可包含多次消息往返 │ └── Artifact产出物× N │ Task的产出单元同一Artifact内的内容组合呈现 │ └── Part × N Artifact的组成分片承载具体内容文本、卡片、指令等6.2 Context会话管理Context是会话的逻辑容器通过contextId唯一标识首次请求不携带contextIdAgent在首帧响应中生成并返回只要contextId不变会话即持续有效会话失效场景Agent主动失效返回错误码99911222或小艺主动重置6.3 Task任务生命周期Task是一件事从发起到完成的完整处理单元有独立的生命周期阶段状态说明创建submitted任务刚被接收处理working正在执行任务完成completed任务成功完成取消canceled用户取消任务失败failed任务执行失败提示Task的taskId由Agent在首帧响应中分配任务终止后不可重启。6.4 设备上下文参数Agent Server端可以获取设备的上下文信息需要在平台变量配置中开启对应的系统变量参数类型说明app_verstring小艺APP的版本号foreground_appsstring前台应用列表device_languagestring设备语言设置device_idstring设备标识符设备上下文数据通过请求中的data.variables.systemVariables字段传递{kind:data,data:{variables:{systemVariables:[{app_ver:11.3.8.300,foreground_apps:com.example.app}]}}}七、消息规范最佳实践7.1 必须使用正确的 kind 值状态更新必须使用kind: status-update内容输出必须使用kind: artifact-update7.2 正确设置流式控制字段一次完整交互流程 status-update (submitted) → status-update (working) → artifact-update (append: false, lastChunk: false) → artifact-update (append: true, lastChunk: false) → artifact-update (append: true, lastChunk: true) → status-update (final: true, state: completed)7.3 及时返回 submitted 状态收到请求后应立即返回submitted状态让客户端知道请求已接收。7.4 合理使用 reasoningText将思考过程、中间推理结果放在reasoningText中与正文text分开。7.5 final 字段谨慎使用final: true会断开 SSE 连接只有在任务真正结束时才设置为true。小结本文严格按照华为鸿蒙官方 A2A 协议规范介绍了请求数据结构text、file、data 三种 Part 类型响应数据结构TaskStatusUpdateEvent 和 TaskArtifactUpdateEvent任务状态枚举submitted、working、completed 等 7 种状态流式控制字段append、lastChunk、final 的正确使用完整交互示例从请求到响应的完整 SSE 流遵循这些规范可以确保你的智能体应用与鸿蒙设备端完美兼容。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源鸿蒙Agent通信协议技术规范总览 - 华为开发者联盟鸿蒙Agent通信协议消息指令定义 - 华为开发者联盟鸿蒙Agent通信协议消息参数说明 - 华为开发者联盟端侧插件工具指令说明 - 华为开发者联盟设备上下文参数指令说明 - 华为开发者联盟底部快捷指令说明 - 华为开发者联盟SSE (Server-Sent Events) 规范JSON-RPC 2.0 规范参考资源鸿蒙 Agent 通信协议技术规范总览 - 华为开发者联盟鸿蒙 Agent 通信协议消息指令定义 - 华为开发者联盟SSE 规范