鸿蒙6 AI智能体集成实战

大家好，我是 V 哥。

鸿蒙6的 Agent Framework Kit 是连接应用与小艺智能体生态的核心工具，允许开发者在应用中嵌入智能体入口，实现"应用+智能体"协同服务。以下结合电商、工具类等典型场景，详解集成步骤、代码实战及避坑指南。

一、核心概念与使用前提

关键概念	说明
FunctionComponent	智能体入口UI组件，根据是否设置`title`自动切换为图标或按钮形态。
AgentController	控制器，用于检查智能体可用性、监听对话框状态（如打开/关闭）。
agentId	智能体唯一标识，需从小艺开放平台获取，长度限制1~64字符。

环境要求：

设备：鸿蒙6.0.0(20)及以上版本的手机/平板（模拟器可能不支持）。
依赖：在module.json5中声明权限 "reqPermissions": [{ "name": "ohos.permission.INTERNET" }]。

二、基础集成：快速拉起智能体

场景示例：电商App在商品详情页添加"智能客服"入口，用户点击直接唤起智能体咨询商品信息。

1. 基础代码实现

typescript 复制代码

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）：适合首页导航栏等综合入口。

typescript 复制代码

  FunctionComponent({
    agentId: this.agentId,
    onError: (err) => { /* 处理错误 */ }
    // 不设置title，默认显示小艺图标
  })

按钮形态 （设置title）：适合场景化意图（如"智能生成旅行计划"）。

三、进阶实战：状态监听与可用性检查

场景示例：工具类App在智能体对话框关闭后刷新页面数据（如智能生成报表后更新UI）。

1. 监听对话框状态

typescript 复制代码

@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. 预检查智能体可用性（避免无效加载）

typescript 复制代码

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应用中集成智能体功能，提升用户交互体验。