登录
【鸿蒙开发实战篇】鸿蒙6 AI智能体集成实战
2025年11月29日 09:52
大家好，我是 V 哥。 鸿蒙6的 Agent Framework Kit 是连接应用与小艺智能体生态的核心工具，允许开发者在应用中嵌入智能体入口，实现“应用+智能体”协同服务。以下结合电商、工具类等典型场景，详解集成步骤、代码实战及避坑指南。
联系V哥获取 鸿蒙学习资料
一、核心概念与使用前提
| 关键概念 | 说明 |
|---|---|
| FunctionComponent | 智能体入口UI组件，根据是否设置title自动切换为图标或按钮形态。 |
| AgentController | 控制器，用于检查智能体可用性、监听对话框状态（如打开/关闭）。 |
| agentId | 智能体唯一标识，需从小艺开放平台获取，长度限制1~64字符。 |
环境要求：
- 设备：鸿蒙6.0.0(20)及以上版本的手机/平板（模拟器可能不支持）。
- 依赖：在
module.json5中声明权限"reqPermissions": [{ "name": "ohos.permission.INTERNET" }]。
二、基础集成：快速拉起智能体
场景示例：电商App在商品详情页添加“智能客服”入口，用户点击直接唤起智能体咨询商品信息。
1. 基础代码实现
import { FunctionComponent, FunctionController } from '@kit.AgentFrameworkKit';
import { common, BusinessError } from '@kit.AbilityKit';
@Entry
@Component
struct ProductDetailPage {
// 替换为实际智能体ID（从小艺开放平台获取）
private agentId: string = 'agentproxy_xxx';
private controller: FunctionController = new FunctionController();
build() {
Column() {
// 商品信息展示...
Text("华为Mate 60 Pro").fontSize(20)
// 智能客服入口（按钮形态）
FunctionComponent({
agentId: this.agentId,
onError: (err: BusinessError) => {
console.error("智能体拉起失败:", err.code, err.message); // 错误处理必填
},
options: {
title: '智能客服', // 设置标题后显示为按钮
queryText: '咨询华为Mate 60 Pro的续航和拍照功能' // 预设用户意图
},
controller: this.controller
})
.margin(20)
}
}
}
2. 形态适配策略
-
图标形态（不设
title）：适合首页导航栏等综合入口。
FunctionComponent({
agentId: this.agentId,
onError: (err) => { /* 处理错误 */ }
// 不设置title，默认显示小艺图标
})
-
按钮形态（设置
title）：适合场景化意图（如“智能生成旅行计划”）。
三、进阶实战：状态监听与可用性检查
场景示例：工具类App在智能体对话框关闭后刷新页面数据（如智能生成报表后更新UI）。
1. 监听对话框状态
@Entry
@Component
struct ReportPage {
@State isDialogOpen: boolean = false;
private controller: FunctionController = new FunctionController();
aboutToAppear() {
// 监听对话框打开
this.controller.on('agentDialogOpened', () => {
this.isDialogOpen = true;
console.info("智能体对话框已打开");
});
// 监听对话框关闭（关键：对话框关闭后刷新数据）
this.controller.on('agentDialogClosed', () => {
this.isDialogOpen = false;
this.refreshReportData(); // 自定义数据刷新逻辑
});
}
// 销毁时移除监听
aboutToDisappear() {
this.controller.off('agentDialogOpened');
this.controller.off('agentDialogClosed');
}
build() {
Column() {
if (this.isAgentSupported) { // 需先检查可用性
FunctionComponent({
agentId: this.agentId,
onError: (err) => { /* 错误处理 */ },
controller: this.controller
})
} else {
Text("当前设备不支持智能体功能").fontColor(Color.Red)
}
}
}
}
2. 预检查智能体可用性（避免无效加载）
import { common } from "@kit.AbilityKit";
@Entry
@Component
struct SafeAgentPage {
@State isAgentSupported: boolean = false;
private agentId: string = 'agentproxy_xxx';
async aboutToAppear() {
try {
const context = getContext(this) as common.UIAbilityContext;
// 异步检查智能体是否可用
this.isAgentSupported = await FunctionController.isAgentSupport(context, this.agentId);
} catch (err) {
console.error("检查支持状态失败:", err);
}
}
build() {
Column() {
if (this.isAgentSupported) {
FunctionComponent({
agentId: this.agentId,
onError: (err) => { /* 处理错误 */ }
})
} else {
Button("下载智能体支持模块")
.onClick(() => { /* 引导用户升级系统 */ })
}
}
}
}
四、常见问题与优化策略
| 问题场景 | 解决方案 |
|---|---|
| agentId无效或设备不支持 | 使用isAgentSupport()预检查，降级显示提示或引导用户升级。 |
| 智能体拉起无响应 | 检查网络权限、确认小艺版本更新，错误回调中输出具体code。 |
| 界面卡顿 | 避免在主线程执行智能体相关操作，耗时逻辑放入TaskPool。 |
五、业务场景扩展建议
-
电商场景：
- 商品页设置“智能推荐”按钮，预设查询文本如“推荐适合老年人的手机”。
- 订单页嵌入“物流查询”智能体，自动读取订单号生成查询意图。
-
工具场景：
- 笔记App用图标形态智能体作为全局入口，支持语音速记。
- 旅行App通过按钮形态智能体生成行程规划（
queryText: "规划北京3日游"）。
通过以上步骤，可快速在鸿蒙6应用中集成智能体功能，提升用户交互体验。
