【 HarmonyOS 6 】HarmonyOS智能体开发实战：Function组件和智能体创建

【 HarmonyOS 6 】HarmonyOS智能体开发实战：Function组件和智能体创建

最近在做HarmonyOS AI应用开发，感觉鸿蒙以后和AI会越来越紧密。AI和鸿蒙两个热门方向，居然融合在一起了。感慨颇多。

智能体功能听着很高大上。目前用户能在App里直接调用小艺生态下的智能体，在小艺开放平台，任何人都可以创建智能体上架。所以我们需要给应用集成智能体功能入口。

而提供的Agent Framework Kit是核心工具，实现了应用内激活小艺智能体的效果。

从入门到跑通流程踩了些小坑，索性整理成一篇实战笔记，希望能帮到同样在做智能体集成的开发者。

一、先搞懂：Agent Framework Kit到底是干啥的？

刚开始接触这个Kit的时候，我还以为是个复杂的框架，实际用下来发现定位很清晰。

它就是帮你在HarmonyOS应用里拉起指定智能体的工具包。

核心价值其实就一点：你先在小艺开放平台把自己的智能体上线，然后通过Agent Framework Kit，就能让用户在你的App里，通过Kit提供的UI控件主动打开这个智能体。简单说，它解决了“应用怎么和智能体对接”的核心问题，不用自己从零搭一套交互入口。

这个Kit里最核心的东西就是Function组件。

所有和智能体拉起相关的操作，基本都围绕这个组件展开。后续的开发实战，也都是基于这个组件来做的。

二、Function组件：智能体入口的两种形态

Function组件是Agent Framework Kit的“门面”，用户就是通过它触发智能体拉起的。

这里有个小细节我刚开始没注意：它会根据你是否设置“标题”，自动切换成两种形态，用途不太一样。

第一种是图标组件：

当你不设置title的时候，组件会默认显示成图标样式。这种适合做“综合型入口”。比如App首页的智能体入口按钮，不带具体的用户意图，点进去就是智能体的主界面。我在项目里把它放在了个人中心的工具栏，作为智能体的总入口，用户一眼就能找到。

第二种是按钮组件：
只要你设置了title，组件就会变成按钮样式，还能自定义功能描述。这种更适合场景化入口。

比如在创建任务页面，我把按钮标题设为“智能生成任务”，queryText设为“帮我生成本周的工作计划”，用户点这个按钮，拉起智能体就直接带了明确的意图，体验更顺畅。

三、开发前必看：那些容易踩坑的限制条件

在动手写代码前，一定要先确认环境是否符合要求。

我刚开始用模拟器测了半天没反应，后来才发现是踩了限制的坑，白浪费时间。

设备限制：目前只支持手机（Phone）和平板（Tablet），其他设备比如手表、车机暂时不兼容，开发和测试必须用真实设备，模拟器跑不起来。
地区限制：仅限中国境内使用，香港、澳门、台湾地区暂时用不了，如果你做的是面向这些地区的应用，可能得等后续更新。
账号准备：设备必须登录华为账号，而且要联网，智能体需要和小艺开放平台交互，没登录的话会直接报错，这点要在App里加个引导提示。

另外，别忘了先在小艺开放平台把你的智能体创建并上线，拿到唯一的agentId。这是后续开发的关键，没有它组件根本拉不起智能体。

四、实战：用Function组件拉起智能体的完整流程

接下来就是最核心的开发步骤了，我按自己项目里的实现过程来写，代码里会标上关键注释，直接复制改改就能用。

1. 第一步：引入必要的依赖包

首先找到项目根目录下的/src/main/ets/pages/Index.ets文件（如果你的入口页面不是Index.ets，就找对应的页面文件），把需要的类引进来。这里要注意包名别写错，尤其是AgentFrameworkKit的路径：

// 引入Agent Framework Kit核心组件和控制器
import { FunctionComponent, FunctionController } from '@kit.AgentFrameworkKit';
// 处理业务错误
import { BusinessError } from "@kit.BasicServicesKit";
// 日志打印（方便调试）
import { hilog } from "@kit.PerformanceAnalysisKit";
// 后面判断Agent可用性会用到UIAbilityContext
import { common } from '@kit.ArkUI';

2. 第二步：构建基础页面与Function组件

接下来在页面中创建FunctionComponent，这里有两个必填参数绝对不能漏：agentId（你在小艺开放平台拿到的智能体ID）和onError（错误回调，不然出问题没法定位）。

我先写了个最基础的示例，组件会默认显示成图标样式（因为没设title）：

@Entry
@Component
export struct AgentDemoPage {// 初始化Function控制器，用来后续监听事件、判断可用性private agentController: FunctionController = new FunctionController();// 替换成你自己的agentId！替换成你自己的agentId！替换成你自己的agentId！private myAgentId: string = 'agentproxy65481da1fa2293a8482d45';build() {// 用Column布局把组件放在页面中间Column({ space: 20, alignItems: ItemAlign.Center }) {Text('我的智能体入口').fontSize(20).fontWeight(FontWeight.Bold)// 核心的Function组件FunctionComponent({agentId: this.myAgentId, // 必填：智能体唯一标识onError: (err: BusinessError) => { // 必填：错误回调// 打印错误信息，方便调试hilog.error(0x0001, 'AgentDemo', `智能体拉起失败：${err.code} - ${err.message}`);// 这里可以加用户提示，比如Toast.showToast},controller: this.agentController, // 绑定控制器options: {// 这里没设title，组件会显示成图标样式queryText: '' // 可选：默认的用户意图，空的话就是智能体主入口}})}.width('100%').height('100%').padding(20)}
}

3. 优化：先判断Agent是否可用，再加载组件

上面的基础版有个问题：如果agentId无效，或者设备不支持智能体功能，组件会加载失败但用户看不到提示。我后来加了个判断逻辑。

页面加载前先检查当前agentId是否可用，可用再渲染组件，体验更友好。

在刚才的代码里加这段逻辑：

@Entry
@Component
export struct AgentDemoPage {private agentController: FunctionController = new FunctionController();private myAgentId: string = 'agentproxy65481da1fa2293a8482d45';// 新增：标记当前agent是否可用@State isAgentAvailable: boolean = false;// 页面即将显示时，检查Agent可用性aboutToAppear() {this.checkAgentSupport();}// 异步检查Agent是否可用async checkAgentSupport() {try {// 获取UIAbility上下文，用于检查const context = this.getUIContext()?.getHostContext() as common.UIAbilityContext;// 调用控制器的isAgentSupport方法，传入上下文和agentIdthis.isAgentAvailable = await this.agentController.isAgentSupport(context, this.myAgentId);} catch (err) {const error = err as BusinessError;hilog.error(0x0001, 'AgentDemo', `检查Agent可用性失败：${error.code} - ${error.message}`);this.isAgentAvailable = false;}}build() {Column({ space: 20, alignItems: ItemAlign.Center }) {Text('我的智能体入口').fontSize(20).fontWeight(FontWeight.Bold)// 只有Agent可用时，才渲染组件if (this.isAgentAvailable) {FunctionComponent({agentId: this.myAgentId,onError: (err: BusinessError) => {hilog.error(0x0001, 'AgentDemo', `智能体拉起失败：${err.code} - ${err.message}`);},controller: this.agentController,options: {title: '智能生成任务', // 这里设了title，组件会显示成按钮样式queryText: '帮我生成本周的工作计划', // 带明确意图isShowShadow: true // 可选：给按钮加阴影，视觉效果更好}})} else {// Agent不可用时，显示提示Text('当前设备不支持智能体功能，请检查设备或账号状态').fontSize(14).fontColor('#ff4444')}}.width('100%').height('100%').padding(20)}
}

4. 进阶：监听智能体对话框的状态

有时候需要知道用户什么时候打开/关闭了智能体对话框，比如统计使用次数，或者在对话框关闭后刷新页面数据。这时候可以给控制器加监听事件，注意在页面销毁时移除监听，避免内存泄漏。

继续完善代码，加入监听逻辑：

@Entry
@Component
export struct AgentDemoPage {private agentController: FunctionController = new FunctionController();private myAgentId: string = 'agentproxy65481da1fa2293a8482d45';@State isAgentAvailable: boolean = false;aboutToAppear() {this.checkAgentSupport();// 页面显示时，初始化监听this.initAgentListeners();}aboutToDisappear() {// 页面销毁时，移除监听，避免内存泄漏this.removeAgentListeners();}async checkAgentSupport() {// （同上，省略重复代码）}// 初始化监听：对话框打开和关闭事件initAgentListeners() {// 监听对话框打开this.agentController?.on('agentDialogOpened', () => {hilog.info(0x0001, 'AgentDemo', '用户打开了智能体对话框');// 这里可以加业务逻辑，比如记录用户行为});// 监听对话框关闭this.agentController?.on('agentDialogClosed', () => {hilog.info(0x0001, 'AgentDemo', '用户关闭了智能体对话框');// 比如对话框关闭后，刷新页面数据// this.refreshPageData();});}// 移除监听removeAgentListeners() {this.agentController?.off('agentDialogOpened');this.agentController?.off('agentDialogClosed');}build() {// （同上，省略重复代码）}
}

5. DEMO源码

最后，我把上面的逻辑整合了一份完整代码，大家复制过去，替换掉myAgentId，用真实手机（登录华为账号、联网）就能跑通：

import { FunctionComponent, FunctionController } from '@kit.AgentFrameworkKit';
import { BusinessError } from "@kit.BasicServicesKit";
import { hilog } from "@kit.PerformanceAnalysisKit";
import { common } from '@kit.ArkUI';
import { Column, Text, ItemAlign } from '@kit.ArkUI';@Entry
@Component
export struct AgentFunctionDemo {// 1. 初始化控制器和agentId（替换成你的真实agentId）private agentController: FunctionController = new FunctionController();private myAgentId: string = 'agentproxy65481da1fa2293a8482d45'; // 替换这里！// 2. 标记Agent是否可用@State isAgentAvailable: boolean = false;// 3. 页面加载前：检查Agent可用性 + 初始化监听aboutToAppear() {this.checkAgentSupport();this.initAgentListeners();}// 4. 页面销毁：移除监听aboutToDisappear() {this.removeAgentListeners();}// 5. 检查Agent是否可用async checkAgentSupport() {try {const context = this.getUIContext()?.getHostContext() as common.UIAbilityContext;this.isAgentAvailable = await this.agentController.isAgentSupport(context, this.myAgentId);} catch (err) {const error = err as BusinessError;hilog.error(0x0001, 'AgentDemo', `检查失败：${error.code} - ${error.message}`);this.isAgentAvailable = false;}}// 6. 监听对话框状态initAgentListeners() {this.agentController?.on('agentDialogOpened', () => {hilog.info(0x0001, 'AgentDemo', '智能体对话框已打开');// 可添加：记录用户行为、切换页面状态等逻辑});this.agentController?.on('agentDialogClosed', () => {hilog.info(0x0001, 'AgentDemo', '智能体对话框已关闭');// 可添加：刷新数据、弹窗提示等逻辑});}// 7. 移除监听removeAgentListeners() {this.agentController?.off('agentDialogOpened');this.agentController?.off('agentDialogClosed');}// 8. 页面渲染build() {Column({ space: 24, alignItems: ItemAlign.Center }) {Text('HarmonyOS智能体入口示例').fontSize(22).fontWeight(FontWeight.Bold).textColor('#1a1a1a')// Agent可用时显示按钮，不可用时显示提示if (this.isAgentAvailable) {FunctionComponent({agentId: this.myAgentId,onError: (err: BusinessError) => {hilog.error(0x0001, 'AgentDemo', `拉起失败：${err.code} - ${err.message}`);// 这里可以加Toast提示用户，比如：// Toast.showToast({ message: '智能体拉起失败，请稍后再试' });},controller: this.agentController,options: {title: '智能生成工作计划', // 按钮标题（显示为按钮组件）queryText: '帮我生成一份本周的开发工作计划，包含需求评审、编码、测试', // 初始意图isShowShadow: true, // 显示按钮阴影// 更多配置可参考官方文档的FunctionComponent参数说明}})} else {Text('当前设备不支持智能体功能\n请检查：1. 登录华为账号 2. 联网 3. 使用手机/平板').fontSize(14).textColor('#ff4444').textAlign(TextAlign.Center).width('80%')}}.width('100%').height('100%').padding(30).backgroundColor('#f5f5f5')}
}

五、如何创建小艺生态智能体

傻瓜操作，在小艺开放平台上，点击创建后，使用自然语言描述你的智能体的功能和作用。目前上架还没完全开放。但是可以体验效果。