HarmonyOS智能体实战：AgentExtensionAbility

鸿蒙专家

在HarmonyOS生态中，应用交互正从传统的“人找服务”向“智能服务找人”的范式转移。用户无需在菜单中层层点击，只需通过自然语言唤醒系统助手，即可跨应用完成复杂任务。\n\n实现这一能力的两大核心组件是AgentExtensionAbility和Function。AgentExtensionAbility是无UI的智能体引擎组件，运行在后台，负责接收系统传递的自然语言意图和结构化参数，执行业务推理逻辑（如查询数据库、调用大模型API），并将结果以结构化数据或卡片形式返回给系统。Function组件则是系统与应用的握手桥梁，系统通过解析用户意图，映射到对应的Function，无需拉起应用界面即可静默唤起智能体并传参。简而言之，Function让应用调起系统AI能力，AgentExtensionAbility让应用将自己的服务提供给系统。\n\n在鸿蒙生态中，今日头条和天气等国民级应用已率先接入：用户在新闻详情页可唤起小艺进行内容分析，在天气页面可基于天气询问穿搭建议。\n\n开发者若想让自己的应用被系统全局召唤，需先入驻小艺开放平台（华为开发者联盟）。在平台上注册意图并定义Function契约——明确规定输入参数（如时间、地点、动作）和输出结构（如结果码、响应文本），形成大模型与端侧代码的API接口文档。\n\n以下以自研日程管理应用“轻规划”为例，演示接入流程。业务场景：用户在开车时想起明天周报未写，直接语音说“帮我把今天下午3点的周报任务顺延到明天，并找个空闲时间安排复盘会议”。预期效果：应用在后台自动查询日程冲突，更新任务并弹出调整成功卡片。\n\n开发步骤：\n\n1. 在小艺开放平台创建智能体模式Agent，填写名称、描述、支持设备，编排后上架。\n\n2. 在工程的module.json5文件中声明AgentExtensionAbility，配置action为接收系统意图：\n\n

2. \n{\n  "module": {\n    "extensionAbilities": [\n      {\n        "name": "QingGuihuaAgentExtensionAbility",\n        "srcEntry": "./ets/agentextability/QingGuihuaAgentExtensionAbility.ets",\n        "type": "agent",\n        "exported": true,\n        "skills": [\n          {\n            "actions": [\n              "action.system.agent.intent"\n            ]\n          }\n        ]\n      }\n    ]\n  }\n}\n

复制代码

\n\n3. 创建继承自AgentExtensionAbility的类，处理onSessionCreate事件。在会话创建时获取Function传递的参数（如actionType和taskName），执行业务逻辑后将结果通过session.sendResponse返回给系统。\n\n

2. \nimport { AgentExtensionAbility, AgentSession } from '@kit.HarmonyOSMobileAIFramework';\nimport hilog from '@ohos.hilog';\n\nexport default class QingGuihuaAgentExtensionAbility extends AgentExtensionAbility {\n  onCreate() {\n    hilog.info(0x0000, 'QingGuihuaAgent', 'AgentExtensionAbility onCreate');\n  }\n\n  onSessionCreate(session: AgentSession) {\n    hilog.info(0x0000, 'QingGuihuaAgent', 'Session created');\n    let intentParams = session.getIntentParams();\n    let actionType = intentParams.action; // 例如："delay_task"\n    let taskName = intentParams.taskName; // 例如："周报任务"\n\n    this.handleTaskPlanning(taskName, actionType).then((result) => {\n      session.sendResponse({\n        code: 0,\n        message: result.replyText,\n        cardData: result.cardInfo\n      });\n    }).catch((err) => {\n      session.sendResponse({ code: -1, message: "日程调整失败" });\n    });\n  }\n\n  onDestroy() {\n    hilog.info(0x0000, 'QingGuihuaAgent', 'AgentExtensionAbility onDestroy');\n  }\n\n  async handleTaskPlanning(taskName: string, actionType: string): Promise<any> {\n    // 可调用大模型判断最佳时间，更新本地数据库\n    return {\n      replyText: `已帮您将${taskName}顺延至明日上午10点`,\n      cardInfo: { /* 卡片渲染数据 */ }\n    };\n  }\n}\n

复制代码

\n\n通过以上步骤，应用即可打破传统UI桎梏，成为与鸿蒙系统智慧助手深度融合的智能体。未来，用户的请求可从全局搜索、智慧视觉、小艺助手等终端发起，接入了智能体生态的应用将第一时间捕获自然语言意图，提供一步直达的服务。开发者应以AI思维重构业务逻辑，让APP长出“智慧大脑”。

热心网友5

非常详细的实战教程！从概念到代码一步步拆解，对想接入鸿蒙智能体生态的开发者来说很有参考价值。“轻规划”这个案例选得也很典型，正好展示了如何把自然语言意图转化成后台静默执行的任务调度。有一点想请教：在 `onSessionCreate` 里通过 `session.getIntentParams()` 获取参数时，参数的结构是不是完全取决于在小艺开放平台注册的 Function 契约里定义的那些字段？如果用户语音输入的意图没有完全匹配所有参数，系统会做模糊匹配还是直接失败？希望能分享更多容错设计的经验。

热心网友5

楼主的分享非常详细，从概念到代码实现都讲得很清楚。这个AgentExtensionAbility的架构确实很符合HarmonyOS“服务找人”的理念，特别是结合小艺开放平台和Function契约的设计，让应用能以无UI方式响应自然语言意图。轻规划这个例子很生动，开车场景下的语音日程调整正是智能助手落地的典型需求。 有个小问题想请教：在onSessionCreate中接收intentParams时，除了action和taskName，是否还能接收更复杂的嵌套参数结构？比如用户说“顺延周报任务到明天下午3点并提醒我”，意图里可能包含多个子动作，这种场景下参数是平铺还是用JSON对象传比较好？另外，卡片返回的cardData格式是否需要在小艺开放平台预先定义schema？谢谢！

热心网友5

这个实战讲解太及时了，正好最近在研究鸿蒙的智能体接入。有个问题想请教：在 `onSessionCreate` 里直接调用大模型或数据库，会不会因为处理耗时导致会话超时？有没有推荐的异步或缓存策略？另外，`cardData` 的卡片渲染数据格式需要和系统约定特定 schema 吗？期待你的后续分享！