目录

FunctionComponent

Agent Framework Kit provides the capability of starting a specified agent.

After the agent for an app is launched on the Celia open platform, users can enjoy the combined "app + agent" service. They can start the agent on demand through the UI control capability provided by Agent Framework Kit.

Since: 6.0.0(20)

Modules to Import

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

FunctionComponent

Agent function component, which can start an agent.

Decorator: @Component

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Parameters:

Name Type Read-Only Mandatory Decorator Type Description
agentId string Yes Yes -

Agent ID, which uniquely identifies an agent. After the agent is created, you can obtain its agent ID from the URL of the agent configuration page.

The value contains 1 to 64 characters.
onError ErrorCallback Yes Yes - Error callback function. The returned error codes and descriptions are detailed below.
options FunctionOptions Yes No - Optional parameters for Function component initialization.
controller FunctionController Yes No - Function component controller. The default value is undefined.

All parameters of this component are initialization options and only take effect upon component instantiation. Modifying these parameter values at runtime will not trigger dynamic updates. To adjust them, the component must be re-initialized.

Error codes:

The following error codes are returned by the onError callback. For details, please refer to ArkTS API Error Codes.

ID Error Message
1022400010 Parameter error.
1022400014 Internal error.

[h2]build

build(): void

Constructor of the FunctionComponent component.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Example:

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

@Entry
@Component
struct FunctionExample {
  private agentId: string = 'agentproxy65481da1fa2293a8482d45'; // agentId of the agent, which is specified by the Celia agent platform when the agent is created.

  build() {
    Column() {
      FunctionComponent({
        agentId: this.agentId,
        onError: (err: BusinessError) => {
          hilog.error(0x0001, 'FunctionExample', `err code: ${err.code}, message: ${err.message}`);
        },
        options: {
           title: 'Intelligent creation',
           queryText: 'Create a pattern',
           isShowShadow: true
        }
      })
    }
  }
}

AgentController

General controller of Agent Framework Kit controls. It integrates common methods for interacting with the Agent function component. This class is a controller base class that can be extended by higher-level controllers.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

[h2]isAgentSupport

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

Checks whether an agent is available, and returns the agent information if it is available. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
context common.UIAbilityContext Yes Context.
agentId string Yes

Agent ID, which uniquely identifies an agent.

The value contains 1 to 64 characters.

Returns:

Type Description
Promise<boolean> Promise used to return the result. The value true will be returned if the agent ID is valid and the agent function is supported. The value false will be returned if the agent ID is invalid or the agent function is not supported.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1022400010 Parameter error.
1022400011 Privacy agreement not accepted.
1022400012 HUAWEI ID not signed in.
1022400013 Internet error.
1022400014 Internal error.

Example:

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 of the agent, which is specified by the Celia agent platform when the agent is created.
  
  @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() {
      // If this method is used to check whether the agent can be loaded, ensure that **agentId** is valid.
      if (this.isAgentSupport) {
        FunctionComponent({
          agentId: this.agentId,
          onError: (err: BusinessError) => {
            hilog.error(0x0001, 'AgentExample', `err: ${JSON.stringify(err)}, message: ${err.message}`);
          },
          options: {
              title: 'Intelligent creation',
              queryText: 'Create a pattern',
              isShowShadow: true
          }
        })
      }
    }
  }
}

[h2]on('agentDialogOpened')

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

Listens for agent pop-up open events. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
type string Yes The value is agentDialogOpened, indicating the agent pop-up open event.
callback Callback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Example:

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 of the agent, which is specified by the Celia agent platform when the agent is created.

  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: 'Intelligent creation',
          queryText: 'Create a pattern',
          isShowShadow: true
        },
        controller: this.controller
      })
    }
  }
}

[h2]off('agentDialogOpened')

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

Cancels the listening for agent pop-up open events. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
type string Yes The value is agentDialogOpened, indicating the agent pop-up open event.
callback Callback<void> No Callback to be unregistered, which must be the same as that passed for subscription. If this parameter is not passed, all callback functions will be unregistered. If the operation is successful, err is undefined. Otherwise, err is an error object.

Example:

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 of the agent, which is specified by the Celia agent platform when the agent is created.

  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: 'Intelligent creation',
          queryText: 'Create a pattern',
          isShowShadow: true
        },
        controller: this.controller
      })
    }
  }
}

[h2]on('agentDialogClosed')

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

Listens for agent pop-up close events. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
type string Yes The value is agentDialogClosed, indicating the agent pop-up close event.
callback Callback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Example:

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 of the agent, which is specified by the Celia agent platform when the agent is created.

  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: 'Intelligent creation',
          queryText: 'Create a pattern',
          isShowShadow: true
        },
        controller: this.controller
      })
    }
  }
}

[h2]off('agentDialogClosed')

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

Cancels the listening for agent pop-up close events. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Parameters:

Name Type Mandatory Description
type string Yes The value is agentDialogClosed, indicating the agent pop-up close event.
callback Callback<void> No Callback to be unregistered, which must be the same as that passed for subscription. If this parameter is not passed, all callback functions will be unregistered. If the operation is successful, err is undefined. Otherwise, err is an error object.

Example:

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 of the agent, which is specified by the Celia agent platform when the agent is created.

  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: 'Intelligent creation',
          queryText: 'Create a pattern',
          isShowShadow: true
        },
        controller: this.controller
      })
    }
  }
}

FunctionController

Function component controller, which is used to control the interactions with Function components. This API is reserved. In the current version, this API inherits from the AgentController method without any additional implementation.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

BaseOptions

Base object for Agent component optional parameters. It integrates common parameters of the Agent component, which can be used for component attribute customization. This object can be extended by higher-level parameters.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Parameters:

Name Type Read-Only Optional Description
title string No Yes

Title of the AgentFramework component. By default, the parameter value is null.

This parameter does not take effect when FunctionOptions.buttonType is ButtonType.CIRCLE.

Currently, only a maximum of eight Chinese characters can be displayed. Characters beyond this limit will be truncated.

If the font scale is greater than 1.75x, a maximum of two lines can be displayed by default.
titleFontSize number No Yes Font size of the AgentFramework component's title, in vp. The value range is [14, 16]. The default value is 16. For values out of this range, the default value will be used.
iconSize number No Yes

Icon size of the AgentFramework component, in vp. The value range is [16, 24].

- When the button type is CIRCLE, the default value is 24.

- When the button type is CAPSULE, the default value is 20.

For values out of this range, the default value will be used.
iconColors ResourceColor[] No Yes Icon color. Currently, only one color is supported. If this parameter is not set, the default gradient icon is used.

FunctionOptions

Initialization parameters of the FunctionComponent. This API inherits from BaseOptions. You can use it to customize FunctionComponent attributes.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Parameters:

Name Type Read-Only Optional Description
queryText string No Yes Initial query text to use the Function component. By default, this parameter is null.
controlSize ControlSize No Yes Button size of the Function component. The default value is ControlSize.NORMAL.
buttonType ButtonType No Yes Button type of the Function component. If the title attribute is null or not set, the default value is ButtonType.CIRCLE. If the title attribute is not null, the default value is ButtonType.CAPSULE.
isShowShadow boolean No Yes

Indicates whether to display the button shadow. It is valid only for capsule buttons (ButtonType.CAPSULE). The default value is false.

true: yes

false: no
backgroundColor ResourceColor No Yes

Background color of the component with a background panel.

The default value is sys.color.comp_background_tertiary.
titleColors ResourceColor[] No Yes

Function component text color. Currently, a maximum of two colors can be set.

- Setting two colors will create a gradient effect.

- Setting one color will apply a solid color.

- If no color is set, the default gradient color is used.

ButtonType

Enumerates button types.

Atomic service API: This API can be used in atomic services since version 6.0.1(21).

System capability: SystemCapability.AI.Agent.AgentKit

Model restriction: This API can be used only in the stage model.

Since: 6.0.0(20)

Name Value Description
CIRCLE 0 Circle button.
CAPSULE 1

Capsule button (with a default corner radius of half its height).

Note:

A capsule button is displayed when the font scale is less than 1.75x. Otherwise, a rounded rectangular button is displayed.
ICON_ABOVE_TITLE 2

Capsule button with the icon and title arranged vertically.

Since: 6.0.1(21)