前言当智能体执行耗时较长的任务时如AI绘图、视频生成、批量数据处理用户可能暂时离开智能体。当任务执行成功后如何及时通知用户消息推送功能正是为解决这一场景而设计的。鸿蒙智能体平台提供了Webhook消息推送机制允许智能体在后台任务完成后通过推送通知的方式告知用户。本文将详细介绍消息推送的配置方法和API规范。消息推送是提升用户体验的关键功能——不需要用户一直等待任务完成后自动通知实现即走即用的流畅体验。一、消息推送概述1.1 什么是消息推送消息推送是指智能体在后台任务执行完成后主动向用户发送通知消息的机制。这与即时通信中的消息推送类似但更加智能化。推送场景示例AI绘图用户请求生成一张图片智能体处理完成后推送结果视频生成长视频渲染完成后通知用户查看数据分析大量数据处理完成后推送分析报告定时任务定时执行的批量任务完成后通知1.2 推送类型鸿蒙消息推送支持两种类型的通知消息推送类型说明效果text纯文本通知点击后进入智能体展示文本内容data结构化数据通知点击后触发触发器的任务执行展示执行结果注意如果同时发送 text 和 data 类型消息只有 text 消息生效。1.3 推送流程完整的消息推送流程如下步骤1: 用户发起耗时任务如帮我画一幅山水画 步骤2: 智能体开始处理用户可离开 步骤3: 任务完成后智能体服务器调用Webhook API 步骤4: 华为推送服务将通知发送到用户设备 步骤5: 用户收到推送通知 步骤6: 用户点击通知进入智能体查看结果二、配置推送功能2.1 添加推送变量首先需要在智能体的变量配置中添加push_id变量进入智能体编排页面找到「变量」配置区域添加系统变量push_id保存配置push_id变量说明属性说明变量名push_id类型系统变量只读用途代表通过Webhook推送通知时使用的唯一ID获取方式请求中的系统变量自动生成2.2 Webhook凭证配置消息推送使用Webhook事件的凭证进行鉴权进入小艺开放平台 → 「工作空间」→「凭证」点击「新建凭证」设置Key名称并保存保存生成的KeyAccess Key和安全密钥Security Key注意安全密钥只在创建成功时可复制关闭窗口前请务必妥善保管。该凭证通用可供该账号下所有智能体的Webhook使用。三、Webhook推送API详解3.1 API端点POST https://hag.cloud.huawei.com/open-ability-agent/v1/agent-webhook3.2 请求头格式Content-Type: application/json Accept: application/json x-hag-trace-id: {{请求标识使用随机数生成用于问题定位}} X-Access-Key: {{从小艺开放平台获取的Access Key}} X-Sign: {{HMAC-SHA256签名}} X-Ts: {{时间戳毫秒数}}请求头字段说明字段类型说明是否必填x-hag-trace-idstring随机生成的请求标识用于问题定位是X-Access-Keystring凭证的Access Key是X-SignstringHMAC-SHA256签名是X-Tsstring当前时间戳毫秒是3.3 签名计算签名算法使用HMAC-SHA256具体实现如下importhashlibimporthmacimportbase64importtimedefgenerate_sign(secret_key:str,timestamp:strNone)-str:生成X-Sign签名 Args: secret_key: 从小艺开放平台获取的安全密钥 timestamp: 时间戳毫秒为空则自动生成 Returns: base64编码的签名结果 iftimestampisNone:timestampstr(int(time.time()*1000))# 使用HMAC-SHA256算法messagetimestamp.encode(utf-8)secretsecret_key.encode(utf-8)signhmac.new(secret,message,hashlib.sha256).digest()# Base64编码returnbase64.b64encode(sign).decode(utf-8)defverify_sign(secret_key:str,timestamp:str,sign:str,timeout:int900)-bool:验证签名 Args: secret_key: 安全密钥 timestamp: 请求中的时间戳 sign: 请求中的签名 timeout: 签名超时时间秒默认15分钟 Returns: 签名是否有效 # 验证时间戳是否在有效期内防重放攻击nowint(time.time()*1000)ifabs(now-int(timestamp))timeout*1000:returnFalse# 重新计算签名并比对expected_signgenerate_sign(secret_key,timestamp)returnsignexpected_signJava示例importjavax.crypto.Mac;importjavax.crypto.spec.SecretKeySpec;importjava.nio.charset.StandardCharsets;importjava.util.Base64;publicclassSignUtil{publicstaticStringgenerateSign(Stringsecret,Stringts)throwsException{MacmacMac.getInstance(HmacSHA256);SecretKeySpeckeySpecnewSecretKeySpec(secret.getBytes(StandardCharsets.UTF_8),HmacSHA256);mac.init(keySpec);byte[]byteHMACmac.doFinal(ts.getBytes(StandardCharsets.UTF_8));returnBase64.getEncoder().encodeToString(byteHMAC);}}签名验证示例# 验证参数secret2e3b71f5def64d95a727314f028bf5aats1547630863716# 计算签名signgenerate_sign(secret,ts)print(f签名结果:{sign})# 预期输出: 6lFqepUu79KSxVCsrXyB/aLVFIdutsTLLx1cZjxDE4I提示服务端应校验ts与当前时间差值的绝对值不超过15分钟用于防重放攻击。3.4 请求体格式{jsonrpc:2.0,id:{{全局唯一消息序列号}},result:{id:{{使用请求中的该字段返回}},apiId:{{API ID}},pushId:{{系统变量push_id的值}},agentLoginSessionId:{{用户授权身份ID}},pushText:{{通知展示内容}},kind:task,artifacts:[{artifactId:{{Artifact唯一ID}},parts:[{kind:text,text:{{响应文本内容}}},{kind:data,data:{{结构化数据}}}]}],status:{state:{{任务状态completed/canceled/failed}}}},error:{code:0,message:success}}3.5 请求体字段说明字段类型说明idstring全局唯一消息序列号result.idstring任务ID与发起请求时一致result.apiIdstring创建API时生成的API IDresult.pushIdstringpush_id系统变量的值result.pushTextstring通知展示内容会显示在推送通知中result.artifacts[].parts[].kindstring内容类型text/data3.6 完整请求示例curlhttps://hag.cloud.huawei.com/open-ability-agent/v1/agent-webhook\-HContent-Type: application/json\-HAccept: application/json\-Hx-hag-trace-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890\-HX-Access-Key: your-access-key\-HX-Sign: generated-base64-signature\-HX-Ts: 1712345678000\-d{ jsonrpc: 2.0, id: a3f9b2c1-d9e4-4b8f-9a7c-2e1d5f3b8c0a, result: { id: 7c1d3e5f-9a2b-4c8d-6e3f-1a9b4c2d8e6f, apiId: webhook794ed095874f4c68888, pushId: d2e4f1c8-9b3a-4d7e-8f2c-6a1b5e9f3d4c, agentLoginSessionId: MDEr1a7L0wxJpyjiaur43RicGHm9FVbJSB, pushText: 您的照片已完成请查看, kind: task, artifacts: [ { artifactId: b5c8d1a3-f9e2-4b7c-8d6a-1f9e3b5c7d8a, parts: [ { kind: data, data: { prompt: 生成一只可爱小猫, imageUrl: https://example.com/cat.png } } ] } ], status: { state: completed } }, error: { code: 0, message: success } }3.7 响应格式{id:43667960-d455-4453-b0cf-1bae4955270d,resultId:c295ea44-7543-4f78-b524-7a38915ad6e4,result:{code:0,message:success}}四、推送效果展示4.1 小艺在后台时的推送当小艺APP处于后台时用户会收到系统推送通知通知效果说明通知栏显示推送标题和内容即pushText点击通知进入智能体展示任务结果支持多条推送的堆叠展示4.2 小艺在前台时的推送当小艺APP处于前台时推送消息显示在消息列表中前台展示说明消息列表中显示推送通知点击后进入对应的智能体对话展示完整的任务执行结果五、 Data数据类型推送5.1 触发插件任务使用data类型推送可以触发智能体执行插件任务{kind:data,data:{cityName:南京}}触发后插件使用data中的参数执行任务。5.2 触发工作流任务data类型推送也可以触发工作流执行{kind:data,data:{cityName:南京}}触发后参数作为EVENT_INPUT.payload传递给工作流{payload:{cityName:南京},header:{name:CloudEvent,namespace:Common}}5.3 A2A模式下的推送在A2A模式下推送的data参数通过data.events发送给Agent Server[{header:{name:Trigger,namespace:Common},payload:{dataMap:{cityName:南京},dialogueHistorySwitch:false,eventDescription:{{apiID}},eventName:{{apiID}},eventType:Webhook,triggerName:{{触发器名称}},triggerType:event}}]六、最佳实践6.1 推送策略建议合理设置pushText简明扼要说明任务结果如图片已生成完成避免频繁推送短时间内多次推送可能被系统聚合区分重要级别重要任务推送次要任务在下次打开时展示附带上文信息让用户看到通知就知道是哪个任务的结果6.2 错误处理# 推送错误处理和重试逻辑importtimeimportrequestsdefsend_push_notification(push_data:dict,max_retries:int3):发送推送通知支持重试urlhttps://hag.cloud.huawei.com/open-ability-agent/v1/agent-webhookheaders{Content-Type:application/json,x-hag-trace-id:generate_trace_id(),X-Access-Key:ACCESS_KEY,X-Sign:generate_sign(SECRET_KEY),X-Ts:str(int(time.time()*1000))}forattemptinrange(max_retries):try:responserequests.post(url,jsonpush_data,headersheaders,timeout10)ifresponse.status_code200:returnresponse.json()elifresponse.status_code429:# 限流等待后重试time.sleep(2**attempt)continueelse:# 其他错误记录日志log_error(fPush failed:{response.status_code}-{response.text})returnNoneexceptrequests.RequestExceptionase:log_error(fPush request error:{e})time.sleep(2**attempt)returnNone6.3 常见问题问题原因解决方案推送未收到push_id未配置检查变量中是否添加了push_id签名验证失败secret_key错误检查凭证配置是否正确推送内容为空pushText为null确保设置了pushText字段接口超时网络问题检查网络连接增加超时时间HTTP 401鉴权失败检查Access Key是否正确HTTP 429请求过于频繁增加重试间隔总结本文详细介绍了鸿蒙智能体消息推送功能的开发和配置推送概述推送的场景、类型和完整流程配置准备push_id变量配置和Webhook凭证创建API详解推送接口的请求格式、签名算法和响应处理效果展示前后台不同状态下的推送效果Data推送插件/工作流/A2A模式的data类型推送最佳实践推送策略、错误处理和常见问题排查消息推送是提升智能体用户体验的重要功能合理使用可以让用户获得即走即用的流畅体验。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源PUSH通知 - 华为开发者联盟Webhook事件 - 华为开发者联盟鸿蒙Agent通信协议 - 华为开发者联盟HMAC-SHA256算法说明Python hashlib文档小艺开放平台 - 凭证管理华为Push Kit文档title: 鸿蒙智能体开发实战13.消息推送date: 2026-04-13 08:00:00tags: [鸿蒙智能体开发实战, 消息推送, AI]背景当智能体运行较长时间的任务时用户可能短暂离开智能体当任务执行成功后可以通过消息推送的方式告知用户任务执行成功。配置首先我们需要在智能体编排中的变量中添加 push_id请求格式说明curlhttps://hag.cloud.huawei.com/open-ability-agent/v1/agent-webhook\-HContent Type: application/json\-HAccept: application/json\-Hx-hag-trace-id: {{客户端使用随机数生成。}}\-HX-Access-Key: {{从小艺开放平台获取的触发器事件WebHook分配的appKey}}\-HX-Sign: {{从小艺开放平台获取的触发器事件WebHook分配的secretKey生成的签名参数签名Base64HMAC-SHA256secretKey ts。 其中secretKey 为开发者在小艺开放平台上配置的接入密钥secretKey}}\-HX-Ts: {{时间戳用于加密和缓存穿透。 格式为当前计算机时间和GMT时间格林威治时间1970年1月1号0时0分0秒所差的毫秒数。 例如2018/1/1 08:00:00.000 的时间戳为1514764800000}}\-d {jsonrpc:2.0,id:{{与agent-server通信的全局唯一消息序列号给agent-server答复请求结果时需取出返回}},result:{id:{{使用请求中的该字段返回一次流式交互中从发起本次请求到本次请求完成处理之间保持不变}},apiId:{{创建api时生成的API IDCP请求时带上}},pushId:{{请求时使用平台系统变量push_id代表通过webhook推送通知时使用的唯一ID。}},agentLoginSessionId:{{账号授权时三方智能体服务器提供的用户授权身份ID。}},pushText:{{Push通知的展示内容按Push服务规格提供}},kind:{{事件类型值为task}},artifacts:[{artifactId:{{本条Artifact的唯一ID用于CP请求消息的去重}},parts:[{kind:text,text:{{agent-server处理的响应如果是markdown流式输出也在此处存放}}},{kind:data,data:{{结构化数据以JSONObject形式存放承载用户结果过程数据及A2A的扩展字段}}}]}],status:{state:{{任务状态取值为[completed|canceled|failed]其中之一}}}},error:{code:{{JSONRPCError错误码整形类型}},message:{{JSONRPCError错误描述}}}}请求示例curlhttps://hag.cloud.huawei.com/open-ability-agent/v1/agent-webhook\-HContent Type: application/json\-HAccept: application/json\-Hx-hag-trace-id: {{请求标识使用随机数生成用于问题定位。}}\-HX-Access-Key: {{从小艺开放平台获取的触发器事件WebHook分配的Access Key。}}\-HX-Sign: {{从小艺开放平台获取的触发器事件WebHook分配的Security Key生成的签名参数签名Base64HMAC-SHA256secretKey ts 其中secretKey 为开发者在小艺开放平台上配置的接入密钥Security Key。}}\-HX-Ts: {{时间戳用于加密和缓存穿透。 格式为当前计算机时间和GMT时间格林威治时间1970年1月1号0时0分0秒所差的毫秒数。 例如2018/1/1 08:00:00.000 的时间戳为1514764800000}}’\ -d {jsonrpc:2.0,id:a3f9b2c1-d9e4-4b8f-9a7c-2e1d5f3b8c0a,result:{id:7c1d3e5f-9a2b-4c8d-6e3f-1a9b4c2d8e6f,apiId:webhook794ed095874f4c68888,pushId:d2e4f1c8-9b3a-4d7e-8f2c-6a1b5e9f3d4c,agentLoginSessionId:MDEr1a7L0wxJpyjiaur43RicGHm9FVbJSB,pushText:您的照片已完成请查看,kind:task,artifacts:[{artifactId:b5c8d1a3-f9e2-4b7c-8d6a-1f9e3b5c7d8a,parts:[{kind:data,data:{prompt:生成一只可爱小猫}}]}]}}效果当小艺至于后台时会收到推送消息如下图当小艺处于前台时会显示在消息列表中如下图参考资料PUSH通知Webhook事件