目录

FunctionComponent（功能组件）

Agent Framework Kit（智能体框架服务）提供了拉起指定智能体的能力。

应用在小艺开放平台上线智能体后，向用户提供应用+智能体组合的服务，让用户可以在适当的场景下通过Agent Framework Kit的UI控件能力主动拉起智能体。配置智能体请参考开发Agent。

起始版本： 6.0.0(20)

导入模块

import { AgentController, BaseOptions, FunctionController, FunctionOptions, ButtonType, FunctionComponent } from '@kit.AgentFrameworkKit';

FunctionComponent

Agent功能组件，可以实现拉起智能体功能。

装饰器类型： @Component

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

参数：

名称 类型 只读 必填 装饰器类型 说明
agentId string 是 是 -

Agent ID，Agent的唯一标识，开发Agent时获取。智能体创建成功后，可在智能体配置页面的网址链接中获取。

长度限制：1~64个字符。
onError ErrorCallback 是 是 - 错误回调函数。返回的错误码及说明如下所示
options FunctionOptions 是 否 - Function组件初始化可选参数。
controller FunctionController 是 否 - Function组件控制器。默认为undefined。

该组件的所有参数均为初始化配置项，仅在组件实例化时生效，运行过程中修改参数值无法实现动态更新，若需调整参数请重新初始化组件。

错误码：

以下错误码为onError回调函数返回的，详细介绍请参见ArkTS API错误码。

错误码ID 错误信息
1022400010 Parameter error.
1022400014 Internal error.

[h2]build

build(): void

FunctionComponent组件的构造函数。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

示例：

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

@Entry
@Component
struct FunctionExample {
  private agentId: string = 'agentproxy65481da1fa2293a8482d45'; // 智能体对应的agentId，由小艺智能体平台在创建智能体时指定

  build() {
    Column() {
      FunctionComponent({
        agentId: this.agentId,
        onError: (err: BusinessError) => {
          hilog.error(0x0001, 'FunctionExample', `err code: ${err.code}, message: ${err.message}`);
        },
        options: {
           title: '智能创建',
           queryText: '创建一个新的模式',
           isShowShadow: true
        }
      })
    }
  }
}

AgentController

Agent Framework Kit控件通用控制器。集成了开发者与Agent功能组件交互的通用方法，该类为控制器基类，可被其它更高阶的控制器继承。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

[h2]isAgentSupport

isAgentSupport(context: common.UIAbilityContext, agentId: string): Promise<boolean>

查询Agent是否可用。若可用，返回Agent信息。使用Promise异步回调。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

参数：

参数名 类型 必填 说明
context common.UIAbilityContext 是 当前上下文环境。
agentId string 是

Agent ID，Agent的唯一标识，开发Agent时获取。

长度限制：1~64个字符。

返回值：

类型 说明
Promise<boolean> Promise对象，返回true表示agentId有效且Agent功能支持，返回false表示agentId无效或者Agent功能不支持。

错误码：

以下错误码的详细介绍请参见ArkTS API错误码。

错误码ID 错误信息
1022400010 Parameter error.
1022400011 Privacy agreement not accepted.
1022400012 HUAWEI ID not signed in.
1022400013 Internet error.
1022400014 Internal error.

示例：

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

@Entry
@Component
struct AgentDemo {
  private functionController: FunctionController = new FunctionController();
  private agentId: string = 'agentproxy65481da1fa2293a8482d45'; // 智能体对应的agentId，由小艺智能体平台在创建智能体时指定
  
  @State isAgentSupport: boolean = false;

  aboutToAppear() {
     void this.checkAgentSupport();
  }

  async checkAgentSupport() {
    try {
      let context = this.getUIContext()?.getHostContext() as common.UIAbilityContext;
      this.isAgentSupport = await this.functionController.isAgentSupport(context, this.agentId);
    } catch (err) {
      hilog.error(0x0001, 'AgentExample', `err code: ${err.code}, message: ${err.message}`);
    }
  }
  build() {
    Column() {
      // 若使用该方法判断是否加载，请确保agentId可用
      if (this.isAgentSupport) {
        FunctionComponent({
          agentId: this.agentId,
          onError: (err: BusinessError) => {
            hilog.error(0x0001, 'AgentExample', `err: ${JSON.stringify(err)}, message: ${err.message}`);
          },
          options: {
              title: '智能创建',
              queryText: '创建一个新的模式',
              isShowShadow: true
          }
        })
      }
    }
  }
}

[h2]on('agentDialogOpened')

on(type: 'agentDialogOpened', callback: Callback<void>): void

监听智能体对话框打开事件。使用callback异步回调。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

参数：

参数名 类型 必填 说明
type string 是 值为'agentDialogOpened'，监听智能体对话框打开事件。
callback Callback<void> 是 回调函数。当具体的操作成功，err为undefined，否则为错误对象。

示例：

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

@Entry
@Component
struct AgentDemo{
  private controller: FunctionController = new FunctionController();
  private agentId: string = 'agentproxy65481da1fa2293a8482d45'; // 智能体对应的agentId，由小艺智能体平台在创建智能体时指定

  aboutToAppear() {
    this.controller?.on('agentDialogOpened', this.onAgentOpenedCallback);
    this.controller?.on('agentDialogClosed', this.onAgentClosedCallback);
  }
  onAgentOpenedCallback = () => {
    hilog.info(0x0001, 'AgentExample', 'agent dialog opened callback');
  };
  onAgentClosedCallback = () => {
    hilog.info(0x0001, 'AgentExample', 'agent dialog closed callback');
  };
  aboutToDisappear() {
    this.controller?.off('agentDialogOpened');
    this.controller?.off('agentDialogClosed');
  }
  build() {
    Column() {
      FunctionComponent({
        agentId: this.agentId,
        onError: (err: BusinessError) => {
          hilog.error(0x0001, 'AgentExample', `err: ${JSON.stringify(err)}, message: ${err.message}`);
        },
        options: {
          title: '智能创建',
          queryText: '创建一个新的模式',
          isShowShadow: true
        },
        controller: this.controller
      })
    }
  }
}

[h2]off('agentDialogOpened')

off(type: 'agentDialogOpened', callback?: Callback<void>): void

取消智能体对话框打开事件的监听。使用callback异步回调。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

参数：

参数名 类型 必填 说明
type string 是 值为 'agentDialogOpened'，取消智能体对话框打开事件的监听。
callback Callback<void> 否 回调函数，需要取消注册的回调函数，需与订阅时传入的回调函数是同一个。若无此参数，则取消注册所有的回调函数。当具体的操作成功，err为undefined，否则为错误对象。

示例：

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

@Entry
@Component
struct AgentDemo{
  private controller: FunctionController = new FunctionController();
  private agentId: string = 'agentproxy65481da1fa2293a8482d45'; // 智能体对应的agentId，由小艺智能体平台在创建智能体时指定

  aboutToAppear() {
    this.controller?.on('agentDialogOpened', this.onAgentOpenedCallback);
    this.controller?.on('agentDialogClosed', this.onAgentClosedCallback);
  }
  onAgentOpenedCallback = () => {
    hilog.info(0x0001, 'AgentExample', 'agent dialog opened callback');
  };
  onAgentClosedCallback = () => {
    hilog.info(0x0001, 'AgentExample', 'agent dialog closed callback');
  };
  aboutToDisappear() {
    this.controller?.off('agentDialogOpened');
    this.controller?.off('agentDialogClosed');
  }
  build() {
    Column() {
      FunctionComponent({
        agentId: this.agentId,
        onError: (err: BusinessError) => {
          hilog.error(0x0001, 'AgentExample', `err: ${JSON.stringify(err)}, message: ${err.message}`);
        },
        options: {
          title: '智能创建',
          queryText: '创建一个新的模式',
          isShowShadow: true
        },
        controller: this.controller
      })
    }
  }
}

[h2]on('agentDialogClosed')

on(type: 'agentDialogClosed', callback: Callback<void>): void

监听智能体对话框关闭事件。使用callback异步回调。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

参数：

参数名 类型 必填 说明
type string 是 值为'agentDialogClosed'，监听智能体对话框关闭事件。
callback Callback<void> 是 回调函数。当具体的操作成功，err为undefined，否则为错误对象。

示例：

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

@Entry
@Component
struct AgentDemo{
  private controller: FunctionController = new FunctionController();
  private agentId: string = 'agentproxy65481da1fa2293a8482d45'; // 智能体对应的agentId，由小艺智能体平台在创建智能体时指定

  aboutToAppear() {
    this.controller?.on('agentDialogOpened', this.onAgentOpenedCallback);
    this.controller?.on('agentDialogClosed', this.onAgentClosedCallback);
  }
  onAgentOpenedCallback = () => {
    hilog.info(0x0001, 'AgentExample', 'agent dialog opened callback');
  };
  onAgentClosedCallback = () => {
    hilog.info(0x0001, 'AgentExample', 'agent dialog closed callback');
  };
  aboutToDisappear() {
    this.controller?.off('agentDialogOpened');
    this.controller?.off('agentDialogClosed');
  }
  build() {
    Column() {
      FunctionComponent({
        agentId: this.agentId,
        onError: (err: BusinessError) => {
          hilog.error(0x0001, 'AgentExample', `err: ${JSON.stringify(err)}, message: ${err.message}`);
        },
        options: {
          title: '智能创建',
          queryText: '创建一个新的模式',
          isShowShadow: true
        },
        controller: this.controller
      })
    }
  }
}

[h2]off('agentDialogClosed')

off(type: 'agentDialogClosed', callback?: Callback<void>): void

取消智能体对话框关闭事件的监听。使用callback异步回调。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

参数：

参数名 类型 必填 说明
type string 是 值为 'agentDialogClosed'，取消智能体对话框关闭事件的监听。
callback Callback<void> 否 回调函数，需要取消注册的回调函数，需与订阅时传入的回调函数是同一个。若不传入此参数，则取消注册所有的回调函数。当具体的操作成功，err为undefined，否则为错误对象。

示例：

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

@Entry
@Component
struct AgentDemo{
  private controller: FunctionController = new FunctionController();
  private agentId: string = 'agentproxy65481da1fa2293a8482d45'; // 智能体对应的agentId，由小艺智能体平台在创建智能体时指定

  aboutToAppear() {
    this.controller?.on('agentDialogOpened', this.onAgentOpenedCallback);
    this.controller?.on('agentDialogClosed', this.onAgentClosedCallback);
  }
  onAgentOpenedCallback = () => {
    hilog.info(0x0001, 'AgentExample', 'agent dialog opened callback');
  };
  onAgentClosedCallback = () => {
    hilog.info(0x0001, 'AgentExample', 'agent dialog closed callback');
  };
  aboutToDisappear() {
    this.controller?.off('agentDialogOpened');
    this.controller?.off('agentDialogClosed');
  }
  build() {
    Column() {
      FunctionComponent({
        agentId: this.agentId,
        onError: (err: BusinessError) => {
          hilog.error(0x0001, 'AgentExample', `err: ${JSON.stringify(err)}, message: ${err.message}`);
        },
        options: {
          title: '智能创建',
          queryText: '创建一个新的模式',
          isShowShadow: true
        },
        controller: this.controller
      })
    }
  }
}

FunctionController

Function组件控制器，用于与Function组件控制交互。预留接口，当前版本完全继承AgentController的方法，无额外的实现。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

BaseOptions

Agent组件可选参数的基础对象。集成了Agent组件的共用参数，用于开发者自定义组件属性，可被其它高阶参数继承。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

参数：

参数名 类型 只读 可选 说明
title string 否 是

表示AgentFramework组件的标题。默认值为空。

FunctionOptions.buttonType按钮类型为ButtonType.CIRCLE时不体现。

当前只显示指定大小，宽度超过8个中文字符会进行省略。

字体大于1.75倍时默认最大显示两行。
titleFontSize number 否 是 表示AgentFramework组件标题的字体大小。取值范围为[14, 16]vp，默认值为16vp。取值在范围外取默认值。
iconSize number 否 是

表示AgentFramework组件图标的大小。取值范围为[16, 24]vp。

- 按钮类型为CIRCLE时，默认值为24vp。

- 按钮类型为CAPSULE时，默认值为20vp。

取值在范围外取默认值。
iconColors ResourceColor[] 否 是 表示图标颜色，当前仅支持设置一种颜色，不设置时，为默认渐变色图标。

FunctionOptions

FunctionComponent功能组件的初始化参数，继承自BaseOptions，开发者可通过该参数自定义FunctionComponent的属性。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

参数：

参数名 类型 只读 可选 说明
queryText string 否 是 使用功能组件的初始查询文本，默认值为空。
controlSize ControlSize 否 是 功能组件按钮的大小，默认值为ControlSize.NORMAL。
buttonType ButtonType 否 是 功能组件的按钮类型。title属性为空或不传时默认值为ButtonType.CIRCLE，title属性不为空时默认值为ButtonType.CAPSULE。
isShowShadow boolean 否 是

如果显示按钮的阴影，仅在 ButtonType.CAPSULE 胶囊类型时有效。默认值为false。

true：显示阴影。

false：不显示阴影。
backgroundColor ResourceColor 否 是

显示背景板时，组件的背景颜色。

默认值为sys.color.comp_background_tertiary背景色。
titleColors ResourceColor[] 否 是

功能组件带文本时，文本的颜色，当前最多仅支持设置两种颜色。

- 设置两种颜色时为渐变色。

- 设置一种颜色时为设置颜色。

- 不设置时为默认渐变色文本。

ButtonType

按钮类型的枚举值。

元服务API： 从版本6.0.1(21)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.AI.Agent.AgentKit

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

名称 值 说明
CIRCLE 0 圆形按钮。
CAPSULE 1

胶囊按钮（圆角默认高度为一半）。

说明：

字体倍数小于1.75倍时，显示为胶囊按钮，大于或等于1.75倍时，显示为矩形倒角按钮。
ICON_ABOVE_TITLE 2

图标与标题为上下结构的胶囊按钮。

起始版本： 6.0.1(21)