---

1 -> 概述

在鸿蒙6.0（API Version 20）的众多新增Kit中，Agent Framework Kit（智能体框架服务） 的引入尤为引人注目。它不仅仅是又一套API的集合，更代表了鸿蒙生态在AI能力整合与分发模式上的一次重要探索——将“智能体”作为一种标准化的服务组件，以极低的成本嵌入到各类应用之中。

长久以来，应用与AI能力的结合往往意味着复杂的后端集成、对话逻辑的定制化开发以及UI的独立设计。Agent Framework Kit从根本上改变了这一现状。它通过标准化的UI控件（FunctionComponent）和一套简洁的控制器（AgentController），为开发者提供了一条直通“小艺开放平台”上已上线智能体的高速公路。应用开发者不再需要关心智能体内部是如何理解意图、处理逻辑或生成回复的，只需获取一个智能体ID（agentId），就能在自己的应用中拉起一个功能完整、体验一致的智能体交互界面。

这种“应用+智能体”的组合模式，为应用的功能扩展开辟了新的想象空间。原本需要大量代码才能实现的特定场景智能助手（如会议纪要生成、旅行规划助手、专业文档解读），现在可以通过Agent Framework Kit，像嵌入一个普通按钮一样简单地集成进来。对于用户而言，这意味着他们可以在不离开当前应用上下文的情况下，获得专业、即时的智能辅助，体验更加流畅和自然。

本文将深入鸿蒙6.0的这一新增Kit，从核心组件、API设计、典型使用场景到实战代码示例，详细解读如何利用Agent Framework Kit，在应用中快速实现拉起指定智能体的能力。

2 -> 核心组件与API详解

Agent Framework Kit的设计高度模块化，核心围绕三个主要部分展开：FunctionComponent（功能组件）、AgentController（智能体控制器） 以及相关的配置选项。它们的协同工作，构成了从智能体可用性检查到交互界面拉起，再到生命周期监听的全部流程。

2.1 -> FunctionComponent：即插即用的智能体入口

FunctionComponent 是Kit中最核心的UI组件，它是一个@Component装饰的ArkTS组件，可以直接嵌入到你的页面布局中。从功能上看，它封装了一个按钮，点击后会拉起指定智能体的对话界面。整个拉起过程（包括权限校验、界面动画、数据交互）由系统框架层完成，应用侧无需进行任何额外处理。

2.1.1 -> 基础使用示例

以下是最简化的集成方式，只需要提供一个有效的agentId和一个错误处理回调：

import { FunctionComponent, BusinessError } from '@kit.AgentFrameworkKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct SimpleAgentDemo {
  // 请替换为你在小艺开放平台创建的智能体ID
  private agentId: string = 'agentproxy65481da1fa2293a8482d45';

  build() {
    Column() {
      FunctionComponent({
        agentId: this.agentId,
        onError: (err: BusinessError) => {
          hilog.error(0x0001, 'AgentDemo', `拉起智能体失败，错误码: ${err.code}, 信息: ${err.message}`);
        }
      })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

在这个示例中，当用户点击这个未定义任何样式的组件时，系统会尝试拉起ID为agentproxy65481da1fa2293a8482d45的智能体。如果由于网络问题、用户未登录华为账号、隐私协议未签署等原因导致失败，错误信息会通过onError回调返回给应用。

2.1.2 -> 自定义样式与交互

为了适应不同应用的UI风格，FunctionComponent 提供了丰富的可配置参数。这些参数通过options字段传入，其类型为FunctionOptions，继承自BaseOptions。

• 标题与文本：通过title设置按钮上的文字，通过queryText设置拉起智能体后预填的对话内容。这在引导用户进行特定操作时非常有用。
• 按钮样式：通过buttonType可以切换圆形按钮（CIRCLE）、胶囊按钮（CAPSULE） 或图标在上文字在下（ICON_ABOVE_TITLE） 的样式。当title不为空时，默认样式为CAPSULE；否则为CIRCLE。
• 视觉细节：titleFontSize、iconSize、iconColors、titleColors（支持渐变）、backgroundColor、isShowShadow等属性，让开发者能精确控制组件外观，使其与应用主题完美融合。

样式定制示例：

FunctionComponent({
  agentId: this.agentId,
  onError: this.onError,
  options: {
    title: 'AI 旅行规划师',          // 按钮文本
    queryText: '帮我规划一个三天两夜的杭州文化之旅', // 预填充的提问
    buttonType: ButtonType.CAPSULE,   // 使用胶囊样式
    isShowShadow: true,               // 显示阴影，提升立体感
    titleFontSize: 16,                // 标题字体大小
    iconSize: 20,                     // 图标大小
    backgroundColor: '#FFE4E1',       // 背景色
    titleColors: ['#FF6A88', '#FF99AC'] // 文本渐变色
  }
})

这种高度的可定制性，使得智能体入口不再是生硬的功能外挂，而是可以自然融入应用视觉语言的一部分。

2.2 -> AgentController：前置检查与生命周期管理

AgentController 是控制器的核心，它提供了两个关键能力：智能体可用性预检和拉起界面的生命周期监听。

2.2.1 -> 智能体可用性检查（isAgentSupport）

在实际开发中，我们常常需要根据当前环境（如用户是否登录、网络是否通畅、智能体自身是否处于服务状态）来决定是否展示智能体入口。isAgentSupport方法正是为此而生。

它接收UIAbilityContext和agentId，返回一个Promise<boolean>。返回true表示智能体ID有效且当前环境支持拉起（例如用户已登录华为账号并同意隐私协议）；返回false则表示不可用。

预检示例：

import { common } from '@kit.AbilityKit';
import { FunctionController, FunctionComponent } from '@kit.AgentFrameworkKit';

@Entry
@Component
struct SmartAgentDemo {
  private functionController: FunctionController = new FunctionController();
  private agentId: string = 'agentproxy65481da1fa2293a8482d45';
  @State isAgentReady: boolean = false;

  async aboutToAppear() {
    try {
      // 获取上下文
      let context = this.getUIContext()?.getHostContext() as common.UIAbilityContext;
      // 检查智能体是否可用
      this.isAgentReady = await this.functionController.isAgentSupport(context, this.agentId);
    } catch (err) {
      console.error(`检查智能体状态失败: ${err}`);
    }
  }

  build() {
    Column() {
      if (this.isAgentReady) {
        // 仅当智能体可用时才展示入口
        FunctionComponent({
          agentId: this.agentId,
          onError: (err) => console.error(`拉起失败: ${err.message}`)
        })
      } else {
        // 降级处理：展示一个普通的按钮或提示
        Text('智能助手暂不可用，请稍后重试')
      }
    }
  }
}

通过这种方式，可以避免在智能体不可用时向用户展示一个无效的入口，从而提升用户体验。

2.2.2 -> 监听智能体对话框事件

有时我们需要在智能体对话框打开或关闭时执行一些业务逻辑，比如暂停背景音乐播放、记录用户行为日志、或者刷新页面数据。AgentController提供了on和off方法来订阅和取消订阅agentDialogOpened（打开）和agentDialogClosed（关闭）事件。

事件监听示例：

import { FunctionController, FunctionComponent } from '@kit.AgentFrameworkKit';

@Entry
@Component
struct LifecycleAwareDemo {
  private controller: FunctionController = new FunctionController();
  private agentId: string = 'agentproxy65481da1fa2293a8482d45';

  aboutToAppear() {
    // 订阅打开和关闭事件
    this.controller.on('agentDialogOpened', this.onDialogOpen);
    this.controller.on('agentDialogClosed', this.onDialogClose);
  }

  onDialogOpen = () => {
    console.info('智能体对话框已打开，可以暂停背景音效等操作');
    // 例如：暂停视频播放
  }

  onDialogClose = () => {
    console.info('智能体对话框已关闭，可以恢复现场');
    // 例如：恢复视频播放
  }

  aboutToDisappear() {
    // 页面销毁时移除监听，防止内存泄漏
    this.controller.off('agentDialogOpened', this.onDialogOpen);
    this.controller.off('agentDialogClosed', this.onDialogClose);
  }

  build() {
    Column() {
      FunctionComponent({
        agentId: this.agentId,
        onError: (err) => console.error(`拉起失败: ${err.message}`),
        controller: this.controller  // 将控制器传入组件
      })
    }
  }
}

注意：off方法如果不传入具体的回调函数，将取消对应类型的所有回调。通常建议在页面生命周期结束时，精确地移除之前注册的回调，以避免潜在的问题。

3 -> 实战：一个完整的智能体集成流程

让我们通过一个完整的案例，将上述知识点串联起来。假设我们要开发一款“智能写作助手”应用，其中一项核心功能是“AI润色”，我们希望通过Agent Framework Kit集成一个专业的“文本润色智能体”。

3.1 -> 步骤一：在小艺开放平台创建智能体

这一步通常在Web端完成。你需要登录小艺开放平台，按照指引创建一个新的智能体，定义它的能力（如润色、扩写、风格转换），并配置好相应的对话逻辑。创建成功后，平台会为这个智能体分配一个唯一的agentId。

3.2 -> 步骤二：在应用中集成Agent Framework Kit

1. 添加依赖：在模块的oh-package.json5中，确保已包含@kit.AgentFrameworkKit。由于这是系统Kit，通常无需额外配置版本号。

2. 设计UI入口：在用户编辑文本的界面，添加一个醒目的“AI润色”按钮。我们使用自定义样式的FunctionComponent。

3. 结合业务逻辑：当用户选中一段文本时，可以将这段文本作为queryText预填充到智能体对话框中，引导用户直接进行润色操作。

3.3 -> 完整代码示例

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import { FunctionComponent, FunctionController, ButtonType } from '@kit.AgentFrameworkKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WritingAssistant {
  @State selectedText: string = '这是一个普通的句子，可能需要进行润色。';
  @State isAgentSupport: boolean = false;
  private agentId: string = 'agent_proxy_text_polisher_123456'; // 文本润色智能体的ID
  private controller: FunctionController = new FunctionController();

  async aboutToAppear() {
    // 页面出现时，检查智能体是否可用
    try {
      let context = this.getUIContext()?.getHostContext() as common.UIAbilityContext;
      this.isAgentSupport = await this.controller.isAgentSupport(context, this.agentId);
    } catch (err) {
      hilog.error(0x0001, 'WritingApp', `智能体检查失败: ${err}`);
    }

    // 监听对话框状态，用于上报分析或控制媒体播放
    this.controller.on('agentDialogOpened', () => {
      hilog.info(0x0001, 'WritingApp', 'AI润色对话框已打开');
    });
    this.controller.on('agentDialogClosed', () => {
      hilog.info(0x0001, 'WritingApp', 'AI润色对话框已关闭');
    });
  }

  aboutToDisappear() {
    // 页面退出时，移除事件监听
    this.controller.off('agentDialogOpened');
    this.controller.off('agentDialogClosed');
  }

  build() {
    Column({ space: 16 }) {
      // 文本编辑区域
      TextArea({ text: this.selectedText })
        .onChange((value: string) => {
          this.selectedText = value;
        })
        .height(200)
        .width('90%')
        .backgroundColor('#F5F5F5')
        .borderRadius(8)
        .padding(12)

      // 智能体入口区域：根据可用性动态显示
      if (this.isAgentSupport) {
        FunctionComponent({
          agentId: this.agentId,
          onError: (err: BusinessError) => {
            hilog.error(0x0001, 'WritingApp', `拉起智能体失败: ${err.code} - ${err.message}`);
            // 此处可增加用户提示，如弹窗或Toast
          },
          options: {
            title: 'AI 润色',
            queryText: `请帮我润色以下文本，使其更流畅、更有文采：\n\n${this.selectedText}`,
            buttonType: ButtonType.CAPSULE,
            isShowShadow: true,
            titleFontSize: 16,
            iconSize: 20,
            // 使用品牌色
            iconColors: ['#FF6B6B'],
            titleColors: ['#FF6B6B', '#FF8E53']
          },
          controller: this.controller
        })
        .width('90%')
      } else {
        // 降级方案：展示普通按钮或说明文字
        Button('AI 润色 (暂时不可用)')
          .enabled(false)
          .width('90%')
      }
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

在这个实战案例中，我们不仅实现了智能体的拉起和样式定制，还加入了可用性预检和生命周期监听，使整个集成更加健壮和符合业务场景。用户选中或编辑文本后，点击按钮即可带着原文进入润色智能体，整个体验无缝且自然。

4 -> 总结与展望

鸿蒙6.0新增的Agent Framework Kit，以极简的API设计和高度集成的系统能力，为开发者提供了一套标准化的“应用-智能体”连接方案。它所带来的价值是多维度的：

• 对开发者：将复杂AI能力的集成门槛降至最低，无需理解智能体背后的技术实现，通过声明式UI组件即可完成接入，显著提升了开发效率。
• 对应用：可以灵活地利用小艺开放平台丰富的智能体资源，快速扩展应用功能，从“工具”向“智慧助手”演进，增加用户粘性和使用场景。
• 对用户：在不同应用中能获得一致、流畅的智能交互体验，且无需在多个应用间切换，真正实现了“服务找人”的智慧化体验。

目前，该Kit已支持手机和平板设备，并可在元服务（6.0.1版本起）中使用，但需注意其仅在中国大陆地区（港澳台除外）提供服务，且暂不支持模拟器调试。

展望未来，随着鸿蒙生态中智能体数量的增加和能力的多样化，Agent Framework Kit有望成为应用获取AI能力的“标准接口”。或许在不远的将来，我们能看到更多创新的“应用+智能体”组合：在购物应用中拉起“比价智能体”，在新闻应用中拉起“摘要生成智能体”，在健康应用中拉起“运动建议智能体”…… 鸿蒙正通过这样的底层能力开放，赋能开发者，共同构建一个更加智能、开放、协同的生态。对于开发者而言，现在正是探索和利用这一新Kit，为应用注入智能新活力的最佳时机。

---

感谢各位大佬支持！！！
互三啦！！！