【 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的路径:
typescript
// 引入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):
typescript
@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是否可用,可用再渲染组件,体验更友好。
在刚才的代码里加这段逻辑:
typescript
@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方法,传入上下文和agentId
this.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. 进阶:监听智能体对话框的状态
有时候需要知道用户什么时候打开/关闭了智能体对话框,比如统计使用次数,或者在对话框关闭后刷新页面数据。这时候可以给控制器加监听事件,注意在页面销毁时移除监听,避免内存泄漏。
继续完善代码,加入监听逻辑:
typescript
@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
,用真实手机(登录华为账号、联网)就能跑通:
typescript
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')
}
}
五、如何创建小艺生态智能体
傻瓜操作,在小艺开放平台上,点击创建后,使用自然语言描述你的智能体的功能和作用。目前上架还没完全开放。但是可以体验效果。