前言在智能体的日常运行中除了被动响应用户的对话请求外很多时候还需要自动触发特定的任务执行。例如当用户进入智能体时自动展示欢迎信息或者当外部系统完成某个异步任务时向用户推送通知。触发器Trigger就是实现这种自动化能力的关键机制。本文将详细介绍鸿蒙智能体平台中触发器的两种类型——通用事件和Webhook事件帮助你掌握智能体的自动化任务编排能力。触发器概述什么是触发器触发器是智能体的一种事件驱动机制它允许智能体在接收到特定事件时自动执行预设的任务而无需等待用户主动输入。这类似于编程领域的观察者模式或被观察者模式——当事件发生时系统会自动回调已注册的处理逻辑。核心价值触发器让智能体从被动问答进化到主动服务极大地扩展了智能体的应用场景。触发器类型对比鸿蒙智能体平台目前支持两种类型的触发器特性通用事件Webhook事件触发方式用户进入智能体时自动触发外部系统通过HTTP请求触发适用模式LLM模式、A2A模式所有模式任务类型智能体提示、插件、工作流插件、工作流、A2A协议是否需要凭证否是Access Key Security Key典型场景进入欢迎语、自动数据查询异步任务完成通知、外部系统回调通用事件通用事件原理通用事件是最简单的触发器形式当用户以半屏态或全屏态进入智能体时系统会自动触发执行预先配置的任务。一个智能体内一个通用事件仅可关联一个触发器。上图展示了在小艺开放平台中配置通用事件触发器的界面开发者可以在【任务执行】中选择智能体提示、插件或工作流。任务执行类型通用事件支持三种任务执行类型1. 智能体提示触发时系统将预设的内容发送给智能体执行适合用于欢迎语、引导提示等场景{trigger:{type:common_event,task:{type:agent_prompt,content:欢迎来到智能体我是你的专属助手请问有什么可以帮助你的}}}2. 插件触发器任务执行类型为插件时触发时系统将自动调用插件执行# 触发器调用插件的配置示例trigger_config{event:common_event,task:{type:plugin,plugin_id:weather_query_plugin,parameters:{city:${system.city}},save_context:True# 是否保存会话上下文}}提示插件支持通过参数设置进行融合生成配置也支持使用模拟集进行调试。详情可参考相关资源中的链接。3. 工作流触发器任务执行类型为工作流时触发时系统将自动调用工作流执行# 触发器调用工作流的配置示例trigger_config{event:common_event,task:{type:workflow,workflow_id:daily_report_workflow,parameters:{user_id:${system.uid}},save_context:True}}注意由触发器触发工作流时因为没有用户主动输入工作流无法自动关联默认输入的USER_INPUT。因此触发器绑定的工作流需要在开始节点定制其他输入参数并在触发器中指定参数值。通用事件配置步骤配置通用事件触发器只需以下几步进入智能体编排页面找到触发器配置区域选择通用事件作为事件选项配置任务执行类型智能体提示/插件/工作流填写任务参数保存并发布智能体Webhook事件Webhook事件概述Webhook事件适用于异步事件场景。当内容生成完成或任务执行完成时开发者需要向华为开放的统一接口发送通知消息。发送成功后用户手机端将收到通知消息用户点击通知消息后进入智能体可以查看任务执行结果。应用场景图片生成完成通知、数据报告生成完成通知、异步任务处理结果推送等。通知消息类型Webhook通知消息分为两种类型类型说明text点击通知消息进入智能体后将text内容展示给用户datadata作为入参触发触发器的任务执行并将执行结果答复给用户注意若同时发送text和data类型消息只有text消息生效。Webhook事件触发器配置配置字段说明配置项说明Access Key从小艺开放平台获取的触发器事件WebHook分配的KeySecurity Key用于生成签名的安全密钥任务执行类型支持插件、工作流、A2A模式保存会话上下文是否将任务执行信息保存至上下文凭证创建在配置Webhook事件前需要先创建凭证进入小艺开放平台选择【工作空间】-【凭证】点击新建凭证设置Key名称后保存保存后将生成Key和安全密钥重要提醒安全密钥只在创建成功时可明文复制关闭窗口前请务必复制并妥善保管。创建的凭证通用可供本账号下所有智能体的Webhook事件使用。Webhook API详解接口端点POST https://hag.cloud.huawei.com/open-ability-agent/v1/agent-webhook Content-Type: application/json Accept: application/json请求头Header说明x-hag-trace-id请求标识使用随机数生成用于问题定位X-Access-Key从小艺开放平台获取的Access KeyX-Sign签名Base64(HMAC-SHA256(secretKey, ts))X-Ts当前时间戳毫秒签名生成示例importhmacimporthashlibimportbase64importtimedefgenerate_sign(secret_key:str,timestamp:strNone)-str: 生成Webhook请求签名 Args: secret_key: 安全密钥 timestamp: 时间戳毫秒为空则自动生成 Returns: Base64编码的签名 iftimestampisNone:timestampstr(int(time.time()*1000))messagetimestamp.encode(utf-8)secretsecret_key.encode(utf-8)signhmac.new(secret,message,hashlib.sha256).digest()returnbase64.b64encode(sign).decode(utf-8)# 使用示例secret_keyyour-security-key-heretsstr(int(time.time()*1000))signgenerate_sign(secret_key,ts)print(fTimestamp:{ts})print(fSignature:{sign})完整请求示例curl-XPOSThttps://hag.cloud.huawei.com/open-ability-agent/v1/agent-webhook\-HContent-Type: application/json\-HAccept: application/json\-Hx-hag-trace-id: a3f9b2c1-d9e4-4b8f-9a7c-2e1d5f3b8c0a\-HX-Access-Key: your-access-key\-HX-Sign: generated-signature\-HX-Ts: 1711612800000\-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: 生成一只可爱小猫 } } ] } ] } }发送通知消息后HTTP状态码为200表示请求成功。data数据说明1. 触发执行插件任务{kind:data,data:{cityName:南京}}触发后使用data中的参数执行插件。2. 触发执行工作流任务{kind:data,data:{cityName:南京}}触发后将data参数作为EVENT_INPUT.payload中执行工作流{payload:{cityName:南京},header:{name:CloudEvent,namespace:Common}}3. A2A模式下触发执行任务{kind:data,data:{cityName:南京}}触发后将data参数作为data.events按照A2A协议发送给Agent Server[{header:{name:Trigger,namespace:Common},payload:{dataMap:{cityName:南京},dialogueHistorySwitch:false,eventDescription:{{apiID}},eventName:{{apiID}},eventType:Webhook,triggerName:{{触发器名称}},triggerType:event}}]Java签名示例importjavax.crypto.Mac;importjavax.crypto.spec.SecretKeySpec;importjava.util.Base64;publicclassWebhookSigner{publicstaticStringgenerateSign(StringsecretKey,Stringtimestamp)throwsException{MacmacMac.getInstance(HmacSHA256);SecretKeySpecsecretKeySpecnewSecretKeySpec(secretKey.getBytes(UTF-8),HmacSHA256);mac.init(secretKeySpec);byte[]rawHmacmac.doFinal(timestamp.getBytes(UTF-8));returnBase64.getEncoder().encodeToString(rawHmac);}publicstaticvoidmain(String[]args)throwsException{StringsecretKeyyour-security-key;StringtimestampString.valueOf(System.currentTimeMillis());StringsigngenerateSign(secretKey,timestamp);System.out.println(Timestamp: timestamp);System.out.println(Signature: sign);}}触发器在不同模式下的差异不同的智能体编排模式下触发器的行为和能力有所差异特性LLM模式A2A模式工作流模式通用事件✅ 支持✅ 支持❌ 不支持Webhook事件✅ 支持✅ 支持✅ 支持智能体提示任务✅✅❌插件任务✅✅✅工作流任务✅✅✅配合选择器节点工作流模式的特殊说明工作流编排时可以配合选择器节点使用。当工作流开始节点的EVENT_INPUT.EventPayload包含特殊参数键值时走触发器触发任务流否则走对话逻辑流。触发器的最佳实践1. 选择合适的触发器类型# 场景一进入智能体时展示个性化欢迎trigger{event:common_event,task:{type:agent_prompt,content:你好我是你的健康管理助手今天想了解你的身体状况吗}}# 场景二外部系统通知用户trigger{event:webhook_event,task:{type:plugin,plugin_id:order_query_plugin,parameters:{orderId:${data.orderId}}}}# 场景三定时触发工作流trigger{event:webhook_event,task:{type:workflow,workflow_id:daily_summary_workflow,parameters:{userId:${system.uid}}}}2. 插件和工作流的版本管理触发器绑定的插件或工作流升级时暂不支持触发器自动更新需手动重新绑定插件或工作流。因此建议在升级前记录触发器绑定的插件/工作流版本升级后在触发器中重新选择最新版本在测试环境中先验证再更新生产环境3. 错误处理与重试# Webhook发送失败时的重试逻辑importtimeimportrequestsdefsend_webhook_with_retry(url,headers,payload,max_retries3):发送Webhook通知并支持重试forattemptinrange(max_retries):try:responserequests.post(url,headersheaders,jsonpayload)ifresponse.status_code200:print(fWebhook发送成功attempt{attempt1})returnTrueelse:print(fWebhook返回异常状态码:{response.status_code})exceptrequests.exceptions.RequestExceptionase:print(fWebhook发送失败attempt{attempt1}, error{e})ifattemptmax_retries-1:time.sleep(2**attempt)# 指数退避returnFalse常见问题FAQQ1智能体中同时配置了工作流和触发器如何实现对话逻辑和触发器功能并存答工作流编排时可以配合选择器节点使用。当工作流开始节点的EVENT_INPUT.EventPayload包含特殊参数键值时走触发器触发任务流否则走对话逻辑流。Q2Webhook发送后用户没有收到通知消息答请检查以下几点确认Access Key和Security Key是否正确配置确认签名生成算法是否正确检查通知消息的pushId是否正确确认用户设备的小艺APP版本在11.3.8.300及以上Q3一个触发器可以绑定多个任务吗答一个Webhook触发器可以绑定一个任务插件/工作流/A2A。如果需要执行多个任务可以通过工作流节点编排多个任务顺序执行。七、触发器配置检查清单在发布智能体前建议逐项确认触发器相关配置通用事件确认任务类型和参数是否正确Webhook 事件确认 Access Key 和 Security Key 是否妥善保存签名算法确认服务端签名逻辑与平台要求一致测试覆盖在真机和网页端分别验证触发效果建议将触发器配置纳入版本管理文档避免升级插件或工作流后遗漏重新绑定。总结本文详细介绍了鸿蒙智能体平台中的触发器机制通用事件用户进入智能体时自动触发适合欢迎语和初始数据加载Webhook事件外部系统通过HTTP API触发适合异步任务通知凭证管理Access Key和Security Key的创建和安全存储签名算法HMAC-SHA256签名生成的Python和Java示例数据格式text和data两种通知类型的使用场景最佳实践版本管理、错误重试、场景选择触发器是智能体从被动响应走向主动服务的关键能力合理使用能让智能体的用户体验大幅提升。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源华为开发者联盟-触发器文档通用事件配置指南Webhook事件配置指南插件参数设置插件绑卡插件模拟集使用工作流配置工作流界面使用鸿蒙Agent通信协议接入方案小艺开放平台