前言

这篇技术博客会带你快速上手 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 能让你的服务场景变得非常精准。