鸿蒙 HarmonyOS 6 | AI Kit 集成 Agent Framework Kit 智能体框架服务

文章目录

- 前言
- [一、智能体框架服务的设计初衷与核心价值](#一、智能体框架服务的设计初衷与核心价值)
- [二、 Agent Framework Kit 的硬件约束与环境准备](#二、 Agent Framework Kit 的硬件约束与环境准备)
- [三、 Function 组件的两种形态解析](#三、 Function 组件的两种形态解析)
- [四、核心 API 引入与环境可用性校验](#四、核心 API 引入与环境可用性校验)
- [五、 FunctionComponent 的参数配置与生命周期监听](#五、 FunctionComponent 的参数配置与生命周期监听)
- [六、实操集成构建一个智能业务入口](#六、实操集成构建一个智能业务入口)
- [七、总结](#七、总结)

前言

这篇技术博客会带你快速上手 HarmonyOS Next 的 Agent Framework Kit 智能体框架服务。

通过本文的学习，你可以掌握如何在自己的应用里拉起小艺智能体，让用户通过简单的 UI 控件就能直接获取智能体提供的各种服务。

一、智能体框架服务的设计初衷与核心价值

在 HarmonyOS Next 的系统环境里，应用已经不再是单纯的功能堆叠，而是需要更聪明的交互方式。Agent Framework Kit 的出现就是为了解决这个问题。它通过一套标准化的 UI 控件，让开发者可以把应用里的业务逻辑和小艺智能体深度结合。

以前如果想在应用里集成 AI 能力，开发者往往要对接复杂的模型接口，还要自己写交互界面。现在通过这个 Kit 提供的 Function 组件，底层的模型调度细节都被屏蔽掉了。

你只需要在代码里配置好参数，用户就能在你的应用里直接呼唤智能体来帮忙。这种应用加智能体的组合模式，缩短了用户操作的路径，也让应用的服务显得更加主动。

二、 Agent Framework Kit 的硬件约束与环境准备

在动手写代码之前，我们需要先看清楚它的硬件门槛。

这个 Kit 目前支持手机和平板设备。这里有一个非常关键的细节需要注意，那就是它暂时不支持模拟器。这意味着你必须准备一台真机来进行开发和调试。另外，因为这套服务需要联网获取云端的智能体配置，所以目前只适用于中国境内，且设备必须登录华为账号并保持联网。

在开发之前，你需要去小艺开放平台完成两个核心动作。

一个是创建智能体，这决定了你的智能体能干什么。

另一个是关联应用，要把你的应用包名和智能体 ID 绑定在一起。如果这一步没做，你在代码里填入 agentId 之后，系统是没办法正确拉起服务的。

三、 Function 组件的两种形态解析

Agent Framework Kit 的核心交互主要是靠 Function 组件来实现。根据你传入参数的不同，这个组件会自动变换样子。

如果你在 options 配置里没有传入 title 这个字段，那么组件就会默认显示成一个图标。这种形态占用的空间很小，非常适合放在应用首页或者某个功能页的角落，作为一个全局的智能助手入口。

如果你在 options 里配置了 title 文本，组件就会自动变成一个按钮。按钮模式可以让你自定义功能描述，比如写上智能生成周报。这种样式的引导性更强，能让用户一眼看出点击后能解决什么问题。这种灵活的切换方式，让我们在适配不同页面 UI 时省了不少心。

四、核心 API 引入与环境可用性校验

进入实际开发阶段，首先要在页面文件里引入必要的工具包。我们需要从 AgentFrameworkKit 里拿组件和控制器。

复制代码

// 引入智能体框架核心组件与控制器
import { FunctionComponent, FunctionController } from '@kit.AgentFrameworkKit';
// 引入基础服务与日志工具用于异常处理
import { BusinessError } from "@kit.BasicServicesKit";
import { hilog } from "@kit.PerformanceAnalysisKit";
import { common } from '@kit.AbilityKit';

在实际的业务场景中，我不建议直接就把组件显示出来。最好是在 aboutToAppear 生命周期里先做一次可用性检查。我们可以调用 FunctionController 提供的 isAgentSupport 接口，把当前上下文和 agentId 传进去。如果接口返回支持，我们再加载组件，这样能有效避免因环境不支持导致的页面报错。

复制代码

// 定义一个状态变量来控制组件的加载
@State isAgentSupport: boolean = false;

// 异步检查当前环境是否支持该智能体
async checkAgentSupport() {
  try {
    // 获取当前页面的 UI 场景上下文
    let context = this.getUIContext()?.getHostContext() as common.UIAbilityContext;
    // 调用核心接口判断是否可用
    this.isAgentSupport = await this.controller.isAgentSupport(context, this.agentId);
  } catch (err) {
    // 捕获异常并记录日志
    hilog.error(0x0001, 'AgentDevLog', `检查支持状态失败 错误码 ${err.code} 消息 ${err.message}`);
  }
}

五、 FunctionComponent 的参数配置与生命周期监听

FunctionComponent 是一个封装程度很高的组件。在它的参数列表里，agentId 是唯一的身份标识，而 onError 回调则是我们处理异常情况的关键抓手。

如果想让应用和智能体配合得更默契，我们需要利用 FunctionController 来监听事件。目前框架开放了 agentDialogOpened 和 agentDialogClosed 两个事件。当用户点开智能体对话框时，应用可以感知到并做出反应，比如暂停正在播放的背景音乐。

复制代码

// 创建控制器实例用于管理事件
private controller: FunctionController = new FunctionController();

// 在页面挂载前注册监听器
aboutToAppear() {
  this.initListeners();
}

initListeners() {
  // 订阅对话框打开的事件
  this.controller?.on('agentDialogOpened', () => {
    hilog.info(0x0001, 'AgentDevLog', '监听到智能体对话框已弹出');
  });
  
  // 订阅对话框关闭的事件
  this.controller?.on('agentDialogClosed', () => {
    hilog.info(0x0001, 'AgentDevLog', '监听到智能体对话框已关闭');
  });
}

// 记得在组件销毁前解除订阅防止资源浪费
aboutToDisappear() {
  this.controller?.off('agentDialogOpened');
  this.controller?.off('agentDialogClosed');
}

六、实操集成构建一个智能业务入口

最后我们将所有的逻辑整合在一起。在 options 配置里，除了 title 之外，还有一个非常实用的参数叫 queryText。它能预填用户想说的话，实现一键触发。

比如我们把 queryText 设置为创建一个新的情景，当用户点下按钮时，智能体会直接收到这条指令并开始执行。这种设计省去了用户手动打字或者说话的步骤。

复制代码

@Entry
@Component
export struct AgentServicePage {
  private controller: FunctionController = new FunctionController();
  // 这里的 ID 需要替换为你从小艺平台申请到的真实 ID
  private agentId: string = 'agentproxy65481da1fa2293a8482d45';

  build() {
    Column() {
      // 只有在支持的情况下才渲染组件
      FunctionComponent({
        agentId: this.agentId,
        onError: (err: BusinessError) => {
          // 这里的错误处理逻辑很关键
          hilog.error(0x0001, 'AgentDevLog', `组件运行出错 ${err.code}`);
        },
        options: {
          title: '智能助手', // 有了标题后组件呈现为按钮样式
          queryText: '帮我制定一个本周的运动计划', // 点击后直接发送的指令
          isShowShadow: true // 开启投影增加视觉上的层次感
        },
        controller: this.controller
      })
    }
    .width('100%')
    .padding(20)
  }
}

在真机上运行后，用户点击这个组件，屏幕底部就会弹出一个非常自然的小艺对话界面。背景会随之变暗，让用户的注意力集中在智能服务上。这种交互方式完全符合 HarmonyOS 的原生设计规范。

七、总结

这篇文章带你深度拆解了 Agent Framework Kit 的核心用法。从最初的硬件限制，到组件的形态选择，再到最后的代码实现，我们走通了一整条集成链路。

通过这套 Kit，开发者可以用极低的开发成本，把 AI 智能体变成应用功能的一部分。在实操中，利用好 queryText 能让你的服务场景变得非常精准。

鸿蒙 HarmonyOS 6 | AI Kit 集成 Agent Framework Kit 智能体框架服务

文章目录

前言

一、 智能体框架服务的设计初衷与核心价值

二、 Agent Framework Kit 的硬件约束与环境准备

三、 Function 组件的两种形态解析

四、 核心 API 引入与环境可用性校验

五、 FunctionComponent 的参数配置与生命周期监听

六、 实操集成 构建一个智能业务入口

七、 总结

一、智能体框架服务的设计初衷与核心价值

四、核心 API 引入与环境可用性校验

六、实操集成构建一个智能业务入口

七、总结