FunctionComponent（功能组件）

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

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

起始版本： 6.0.0(20)

导入模块

收起
自动换行
深色代码主题
复制
import { AgentController, BaseOptions, FunctionController, FunctionOptions, ButtonType, FunctionComponent } from '@kit.AgentFrameworkKit';

FunctionComponent

Phone6.0.0(20)+Tablet6.0.0(20)+

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.

build

Phone6.0.0(20)+Tablet6.0.0(20)+

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

Phone6.0.0(20)+Tablet6.0.0(20)+

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

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

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

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

起始版本： 6.0.0(20)

isAgentSupport

Phone6.0.0(20)+Tablet6.0.0(20)+

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个字符。

参数名

类型

必填

说明

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
          }
        })
      }
    }
  }
}

on('agentDialogOpened')

Phone6.0.0(20)+Tablet6.0.0(20)+

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
      })
    }
  }
}

off('agentDialogOpened')

Phone6.0.0(20)+Tablet6.0.0(20)+

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
      })
    }
  }
}

on('agentDialogClosed')

Phone6.0.0(20)+Tablet6.0.0(20)+

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
      })
    }
  }
}

off('agentDialogClosed')

Phone6.0.0(20)+Tablet6.0.0(20)+

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

Phone6.0.0(20)+Tablet6.0.0(20)+

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

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

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

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

起始版本： 6.0.0(20)

BaseOptions

Phone6.0.0(20)+Tablet6.0.0(20)+

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

Phone6.0.0(20)+Tablet6.0.0(20)+

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

Phone6.0.0(20)+Tablet6.0.0(20)+

按钮类型的枚举值。

元服务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)

名称

值

说明

CIRCLE

圆形按钮。

CAPSULE

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

说明：

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

ICON_ABOVE_TITLE

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

起始版本： 6.0.1(21)