【 HarmonyOS 6 】HarmonyOS智能体开发实战：Function组件和智能体创建

【 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的路径：

登录后复制

// 引入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';

• 1.
• 2.
• 3.
• 4.
• 5.
• 6.
• 7.
• 8.

2. 第二步：构建基础页面与Function组件

接下来在页面中创建FunctionComponent，这里有两个必填参数绝对不能漏：agentId(你在小艺开放平台拿到的智能体ID)和onError(错误回调，不然出问题没法定位)。

我先写了个最基础的示例，组件会默认显示成图标样式(因为没设title)：

登录后复制

@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(<