一、开发背景两类Agent开发方案选型对比鸿蒙7 API26 提供两套智能体开发体系本文聚焦无网络、无需上架小艺平台、纯本地运行的自建智能体方案AgentExtensionAbility方案AgentFrameworkKit云端快速接入AgentExtensionAbility本地自建网络依赖需要联网调用云端大模型完全离线本地逻辑执行无网络依赖上架要求必须在小艺开放平台申请agentId、审核上架无需平台上架本地私有部署唤起方式仅应用内弹窗唤起应用内调用 系统全局语音小艺唤起跨应用互通不支持A2A跨应用调用支持其他应用连接调用自有技能适用场景客服、知识库问答、云端对话自助终端本地工具、离线计算、设备管控、政企内部技能本地Agent核心优势隐私安全、离线可用、可被系统全局语音唤起、支持第三方应用调用适合政务自助机、门店商用Kiosk、本地工具类应用。二、完整工程前置配置2.1 kit标准导入依赖import{AgentExtensionAbility,common,Want,wantAgent}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{BusinessError}fromkit.BasicServicesKit;constTAGLocalAgentService;constDOMAIN0x0011;2.2 module.json5 注册Agent扩展能力核心配置{ module: { name: entry, type: har, deviceTypes: [tablet, phone], extensionAbilities: [ { name: AgentExtAbility, srcEntry: ./ets/agentext/AgentExtAbility.ets, type: agent, exported: true, description: 本地离线工具智能体, metadata: [ { name: agent_config, value: $profile:agent_config.json } ] } ] } }2.3 新建配置文件resources/base/profile/agent_config.json用于定义智能体ID、名称、技能列表、示例话术系统识别可用技能{agentCards:[{agentId:local_offline_tool_001,name:本地离线工具助手,description:提供四则运算、备忘录查询、系统亮度调节本地离线技能,version:1.0.0,capabilities:{streaming:true},skills:[{id:skill_calc,name:数字四则运算,description:计算加减乘除数学表达式,examples:[123乘以45等于多少,88加12再除以5]},{id:skill_note,name:本地备忘录查询,description:读取应用本地存储的备忘录内容,examples:[查看我的备忘录,第一条备忘录是什么]},{id:skill_brightness,name:屏幕亮度调节,description:调整屏幕亮度高低,examples:[把屏幕调亮一点,降低屏幕亮度]}]}]}2.4 权限补充亮度调节配套requestPermissions: [ { name: ohos.permission.CHANGE_BRIGHTNESS, reason: $string:brightness_reason, usedScene: { abilities: [EntryAbility], when: inuse } } ]三、服务端AgentExtensionAbility 完整技能逻辑实现文件路径ets/agentext/AgentExtAbility.ets核心生命周期onCreate智能体服务启动初始化onAuth连接鉴权控制哪些应用可以调用本智能体onData接收客户端指令分发对应技能执行onDestroy服务销毁释放资源。import{AgentExtensionAbility,common,Want}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{brightness}fromkit.BasicServicesKit;exportdefaultclassAgentExtAbilityextendsAgentExtensionAbility{// 模拟本地备忘录持久数据privatemockNoteList:string[][9:00 开发鸿蒙Agent智能体,14:00 完成商用Kiosk终端测试,18:00 提交新特性征文];onCreate():void{hilog.info(DOMAIN,TAG,本地离线智能体服务已启动);}/** 客户端连接鉴权管控调用方白名单 */onAuth(proxy:common.AgentHostProxy):void{// 获取发起调用的应用包名constcallerBundleproxy.getCallerBundleName();// 白名单允许自身应用 指定第三方应用调用constallowList[com.example.agentdemo,com.example.merchant];if(allowList.includes(callerBundle)){proxy.authorize(success);hilog.info(DOMAIN,TAG,应用${callerBundle}授权成功);}else{proxy.authorize(deny);hilog.warn(DOMAIN,TAG,应用${callerBundle}无权限访问智能体);}}/** 接收用户指令分发技能处理 */onData(proxy:common.AgentHostProxy,inputText:string):void{hilog.info(DOMAIN,TAG,收到用户指令${inputText});constreplythis.dispatchSkill(inputText);// 将执行结果回传给客户端页面proxy.sendData(reply);}/** 技能分发中心匹配指令执行对应本地逻辑 */privatedispatchSkill(input:string):string{// 技能1四则运算if(/[\d\\-\*\/]/.test(input)){returnthis.handleCalcSkill(input);}// 技能2备忘录查询if(input.includes(备忘录)){returnthis.handleNoteSkill();}// 技能3亮度调节if(input.includes(调亮)||input.includes(调暗)||input.includes(亮度)){returnthis.handleBrightnessSkill(input);}// 无匹配技能兜底回复return暂未识别该指令支持四则运算、备忘录查询、屏幕亮度调节;}/** 技能1四则运算 */privatehandleCalcSkill(input:string):string{try{// 过滤非法字符仅保留数字与运算符constexprinput.replace(/[^0-9\\-\*\/\.]/g,);if(!expr)return未识别有效算式;constreseval(expr);return计算完成${expr}${res};}catch{return算式解析失败请输入合法数字运算指令;}}/** 技能2备忘录查询 */privatehandleNoteSkill():string{return你的备忘录共${this.mockNoteList.length}条\n${this.mockNoteList.join(\n)};}/** 技能3屏幕亮度调节 */privateasynchandleBrightnessSkill(input:string):string{letcurrentawaitbrightness.getBrightness();if(input.includes(调亮)){currentMath.min(255,current60);}elseif(input.includes(调暗)){currentMath.max(0,current-60);}awaitbrightness.setBrightness(current);return屏幕亮度已调整当前亮度值${current};}onDestroy():void{hilog.info(DOMAIN,TAG,本地智能体服务销毁释放资源);}}四、客户端页面连接本地Agent、发送指令交互页面实现连接智能体、输入指令、展示返回结果ArkUI V2标准写法import{ComponentV2,Local}fromkit.ArkUI;import{wantAgent,common,Want}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{BusinessError}fromkit.BasicServicesKit;constTAGAgentClientPage;EntryComponentV2struct LocalAgentClient{LocalinputCmd:string;LocalreplyResult:string未连接智能体;privateagentProxy:common.AgentHostProxy|nullnull;// 智能体Ability匹配信息privateagentWant:Want{bundleName:com.example.agentdemo,abilityName:AgentExtAbility};aboutToDisappear(){// 页面销毁断开连接防止句柄泄漏this.disconnectAgent();}/** 建立与本地智能体服务的连接 */asyncconnectAgent(){try{this.agentProxyawaitwantAgent.connectAgent(this.agentWant,{onConnect:(proxy){this.replyResult智能体连接成功请输入指令;// 监听智能体返回的技能结果proxy.on(data,(msg:string){this.replyResult智能体回复\n${msg};});},onDisconnect:(){this.agentProxynull;this.replyResult智能体连接已断开;}});}catch(err){consteerrasBusinessError;this.replyResult连接失败${e.code}${e.message};hilog.error(0x0011,TAG,连接Agent异常${JSON.stringify(err)});}}/** 发送指令给本地智能体执行技能 */sendCommand(){if(!this.agentProxy||!this.inputCmd.trim())return;this.agentProxy.sendData(this.inputCmd);this.inputCmd;}/** 断开智能体连接 */disconnectAgent(){if(this.agentProxy){wantAgent.disconnectAgent(this.agentProxy);this.agentProxynull;}}build(){Column({space:20}){Text(本地离线智能体 AgentExtensionAbility 演示).fontSize(22).fontWeight(FontWeight.Bold).width(90%).margin({top:20});Text(this.replyResult).width(90%).padding(16).backgroundColor(#F0F7FF).borderRadius(12).fontSize(14).whiteSpace(WhiteSpace.PreWrap);Row({space:10}){TextInput({text:this.inputCmd}).layoutWeight(1).height(44).onChange(vthis.inputCmdv);Button(发送指令).height(44).onClick(()this.sendCommand());}.width(90%);Flex({wrap:FlexWrap.Wrap,gap:10}){Button(连接本地智能体).onClick(()this.connectAgent());Button(断开连接).backgroundColor(#888888).onClick(()this.disconnectAgent());}.width(90%);Text(支持指令示例100*25、查看备忘录、把屏幕调亮一点).fontSize(12).fontColor(#888888).margin({top:10});Blank();Text( 纯本地离线运行无需联网支持跨应用调用、小艺语音唤起).fontSize(12).fontColor(#AAAAAA).margin({bottom:30});}.width(100%).height(100%).padding({left:16,right:16});}}五、进阶能力1系统全局语音唤起小艺直接调用本地技能完成上述配置后无需额外代码系统小艺语音可直接唤起智能体技能唤醒小艺说出配置在agent_config.json的示例话术「100加50等于多少」系统自动匹配当前应用本地Agent执行skill_calc计算技能并语音播报结果优势无需打开应用页面全局语音直接调用离线业务能力适配自助终端语音交互。六、进阶能力2A2A跨第三方应用调用智能体在onAuth鉴权回调中将第三方应用包名加入allowList授权白名单第三方应用使用完全相同的wantAgent.connectAgent逻辑传入目标应用bundleNameAgentAbility名称跨应用通信全程系统证书校验无恶意应用越权调用风险适合政企多应用协同场景。七、高频开发踩坑大全坑1connectAgent连接智能体持续失败extensionAbilities未配置exported:true外部无法访问扩展能力agent_config.json格式错误、存放路径错误系统无法识别智能体技能bundleName、abilityName填写错误与工程配置不匹配真机未安装完整应用模拟器无Agent系统服务必须真机调试。坑2onData收不到客户端指令客户端必须等待onConnect回调完成后再调用sendData发送指令Agent服务被系统后台回收需配置保活商用Kiosk场景搭配锁机模式。坑3第三方应用无法调用智能体onAuth鉴权逻辑仅放行自身包名未添加第三方应用白名单授权返回deny拒绝连接。坑4语音小艺无法唤起本地技能agent_config.json内skills.examples未填写标准示例话术应用未安装正式签名调试包自动调试签名无法被系统语音匹配设备未开启小艺语音服务。坑5页面反复重建造成连接内存泄漏页面aboutToDisappear必须执行wantAgent.disconnectAgent()断开代理长期运行自助终端会出现句柄耗尽、无响应。坑6重型计算阻塞主线程UI卡顿onData回调运行在主线程复杂运算、文件读写需放入异步子线程处理避免阻塞智能体通信。八、商用生产环境最佳实践技能逻辑分层封装将计算、文件、设备控制等技能单独抽离工具类onData仅做分发便于迭代维护鉴权精细化管控严格配置调用方白名单政企终端拒绝未知应用访问智能体核心技能保障数据安全日志全链路埋点指令接收、技能执行、鉴权结果全部写入hilog线上故障可追溯用户操作记录保活适配无人终端商用自助机搭配Kiosk锁机模式防止AgentExtensionAbility被系统后台清理异常兜底处理所有技能逻辑包裹try-catch指令解析失败返回友好提示避免智能体服务崩溃流式输出优化配置capabilities.streaming:true长文本结果分段推送提升交互流畅度。九、方案总结AgentExtensionAbility本地智能体是鸿蒙7离线交互场景的轻量化方案无需依赖云端大模型、无需平台审核上架仅通过扩展能力配置文件即可实现自定义业务技能。整套开发流程分为工程配置→Agent服务技能实现→客户端交互页面三步同时支持应用内调用、系统全局语音唤起、A2A跨应用互通三大交互方式完美适配政务自助终端、门店商用设备、离线本地工具类应用。对比云端FunctionComponent方案本地智能体隐私性更强、无网络依赖、运维成本更低是线下无人值守终端的首选智能体开发方案。