openharmony 鸿蒙 js-apis-app-agent-agentManager-sys

2026-08-25 浏览 (1)

@ohos.app.agent.agentManager (Agent管理)(系统接口)

agentManager模块提供Agent管理能力，支持AgentExtensionAbility的连接、断开连接等操作，支持LOW_CODE类型Agent的生命周期管理，支持AgentExtensionAbility与ServiceExtensionAbility的连接管理，同时提供获取设备上的AgentCard信息。

说明：

本模块首批接口从API version 24开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本模块接口均为系统接口。

导入模块

import { agentManager } from '@kit.AbilityKit';

agentManager.getAllAgentCards

getAllAgentCards(): Promise<Array<AgentCard>>

获取设备上所有的AgentCard。使用Promise异步回调。

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

需要权限：ohos.permission.GET_AGENT_CARD

系统能力：SystemCapability.Ability.AgentRuntime.Core

系统接口：此接口为系统接口。

返回值：

类型说明
Promise<Array<AgentCard>>Promise对象，返回设备上所有的AgentCard数组。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.

示例：

import { agentManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

agentManager.getAllAgentCards()
  .then((data) => {
    console.info(`GetAllAgentCards success, data: ${JSON.stringify(data)}.`);
  })
  .catch((err: BusinessError) => {
    console.error(`GetAllAgentCards failed, error code: ${err.code}, error msg: ${err.message}.`);
  });

agentManager.getAgentCardsByBundleName

getAgentCardsByBundleName(bundleName: string): Promise<Array<AgentCard>>

获取指定应用的所有AgentCard。使用Promise异步回调。

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

需要权限：ohos.permission.GET_AGENT_CARD

系统能力：SystemCapability.Ability.AgentRuntime.Core

系统接口：此接口为系统接口。

参数：

参数名类型必填说明
bundleNamestring是AgentCard所属的bundle名称。

返回值：

类型说明
Promise<Array<AgentCard>>Promise对象，返回指定bundleName内的所有AgentCard数组。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.
18500001The bundle does not exist or no patch has been applied.

示例：

import { agentManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'com.example.myapplication';

agentManager.getAgentCardsByBundleName(bundleName)
  .then((data) => {
    console.info(`GetAgentCardsByBundleName success, data: ${JSON.stringify(data)}.`);
  })
  .catch((err: BusinessError) => {
    console.error(`GetAgentCardsByBundleName failed, error code: ${err.code}, error msg: ${err.message}.`);
  });

agentManager.getAgentCardByAgentId

getAgentCardByAgentId(bundleName: string, agentId: string): Promise<AgentCard>

获取指定应用agentId对应的AgentCard。使用Promise异步回调。

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

需要权限：ohos.permission.GET_AGENT_CARD

系统能力：SystemCapability.Ability.AgentRuntime.Core

系统接口：此接口为系统接口。

参数：

参数名类型必填说明
bundleNamestring是AgentCard所属的bundle名称。
agentIdstring是AgentCard所属的agentId。

返回值：

类型说明
Promise<AgentCard>Promise对象，返回指定的AgentCard。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.
18500001The bundle does not exist or no patch has been applied.
35600001The specified agentId does not exist.

示例：

import { agentManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'com.example.myapplication';
let agentId = 'agent_001';

agentManager.getAgentCardByAgentId(bundleName, agentId)
  .then((data) => {
    console.info(`GetAgentCardByAgentId success, data: ${JSON.stringify(data)}.`);
  })
  .catch((err: BusinessError) => {
    console.error(`GetAgentCardByAgentId failed, error code: ${err.code}, error msg: ${err.message}.`);
  });

agentManager.connectAgentExtensionAbility

connectAgentExtensionAbility(want: Want, agentId: string, callback: AgentExtensionConnectCallback): Promise<AgentProxy>

将当前调用方组件连接到AgentExtensionAbility。通过返回的AgentProxy与AgentExtensionAbility进行通信，以使用AgentExtensionAbility对外提供的能力。

说明：

  • 当目标Agent的AgentCard为LOW_CODE类型时，AgentExtensionAbility的onConnect只在此类Agent连接成功时回调；后续连接的此类Agent，只回调onAgentInvoked。

  • 同一个AgentExtensionAbility中，最多只能同时运行100个LOW_CODE类型的Agent，否则会报35600003错误码。

  • 同一个AgentExtensionAbility中，不允许重复连接同一个LOW_CODE类型的Agent。

系统接口：该接口为系统接口。

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

需要权限：ohos.permission.CONNECT_AGENT

系统能力：SystemCapability.Ability.AgentRuntime.Core

参数：

参数名类型必填说明
wantWant是AgentExtensionAbility所属的Want信息，通常需要包括bundle名称、ability名称。
agentIdstring是AgentExtensionAbility所属的agentId。
callbackAgentExtensionConnectCallback是连接回调函数，包含接收AgentExtensionAbility服务端的数据、安全认证数据以及断开连接事件的回调接口。

返回值：

类型说明
Promise<AgentProxy>Promise对象，返回的AgentProxy对象，用于从客户端向AgentExtensionAbility服务端发送数据或安全认证请求。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Cannot start an invisible component.
16000005The specified process does not have the permission.
16000008The crowdtesting application expires.
16000012The application is controlled.
16000013The application is controlled by enterprise device management (EDM).
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16000073The app clone index is invalid.
35600001The specified agentId does not exist.
35600003Maximum connections from the same caller have been reached. Please disconnect at least one agent extension beforehand.
35600007The specified LOW_CODE agent is already active and is not yet completed.

示例：

import { common, Want, agentManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  comProxy: common.AgentProxy|null = null;
  connectCallback: common.AgentExtensionConnectCallback = {
    onData: (data: string) => {
      console.info(`onData, data: ${data}.`);
    },
    onAuth: (handShakeData: string): void => {
      console.info(`onData, data: ${handShakeData}.`);
    },
    onDisconnect: () => {
      console.info(`onDisconnect.`);
      this.comProxy = null;
    }
  }
  build() {
    Column() {
      Row() {
        // 创建连接按钮
        Button('connect ability')
          .enabled(true)
          .onClick(() => {
            let connectWant: Want = {
              bundleName: 'com.acts.agentextensionability',
              abilityName: 'AgentExtAbility',
            };
            let agentId: string = 'test';
            try {
              // 连接AgentExtensionAbility
              agentManager.connectAgentExtensionAbility(connectWant, agentId, this.connectCallback)
                .then((proxy: common.AgentProxy) => {
                  this.comProxy = proxy;
                })
                .catch((err: BusinessError) => {
                  console.error(`connectAgentExtensionAbility failed, err code: ${err.code}, err msg: ${err.message}.`);
                });
            } catch (err) {
              let code = (err as BusinessError).code;
              let msg = (err as BusinessError).message;
              console.error(`connectAgentExtensionAbility failed, err code: ${code}, err msg: ${msg}.`);
            }
          })
      }
    }
  }
}

agentManager.registerAgentCard

registerAgentCard(agentCard: AgentCard): Promise<void>

注册AgentCard到系统中，使系统能够识别和调用对应的AgentExtensionAbility。

系统会根据类型对appInfo进行校验：

  • APP、LOW_CODE类型：校验bundle和ability是否存在，并验证ability是否为agent类型。
  • ATOMIC_SERVICE类型：在原子化服务已安装时，校验ability是否存在，并验证ability是否为agent类型。

起始版本： 26.0.0

系统接口：此接口为系统接口。

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

需要权限：ohos.permission.MODIFY_AGENT_CARD

系统能力：SystemCapability.Ability.AgentRuntime.Core

参数：

参数名类型必填说明
agentCardAgentCard是要注册的AgentCard信息。

返回值：

类型说明
Promise<void>Promise对象，无返回结果。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.
18500001The bundle does not exist or no patch has been applied.
35600005The specified agent card version is invalid.
35600006The specified agent card has already been registered. Use updateAgentCard instead.

示例：

import { agentManager, agentConstant, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let agentCard: common.AgentCard = {
  agentId: 'agent_001',
  name: '智能助手',
  description: '这是一个智能助手',
  version: '1.0.0',
  defaultInputModes: ['text/plain'],
  defaultOutputModes: ['text/plain'],
  skills: [{
    id: 'skill_001',
    name: '基础技能',
    description: '这是一个基础技能',
    tags: ['助手', '查询']
  }],
  iconUrl: 'common/weather_icon.png',
  category: 'productivity',
  type: agentConstant.AgentCardType.APP,
  appInfo: {
    bundleName: 'com.example.myapplication',
    moduleName: 'entry',
    abilityName: 'AgentExtAbility'
  }
};

agentManager.registerAgentCard(agentCard)
  .then(() => {
    console.info('RegisterAgentCard success.');
  })
  .catch((err: BusinessError) => {
    console.error(`RegisterAgentCard failed, error code: ${err.code}, error msg: ${err.message}.`);
  });

agentManager.updateAgentCard

updateAgentCard(agentCard: AgentCard): Promise<void>

更新系统中已存在的AgentCard信息，当SemVer版本不低于当前已存在的AgentCard时执行覆盖更新。当SemVer版本相同时，系统优先保存通过registerAgentCard或updateAgentCard接口调用时传入的AgentCard。

系统会根据类型对appInfo进行校验：

  • APP、LOW_CODE类型：校验bundle和ability是否存在，并验证ability是否为agent类型。
  • ATOMIC_SERVICE类型：在原子化服务已安装时，校验ability是否存在，并验证ability是否为agent类型。

起始版本： 26.0.0

系统接口：此接口为系统接口。

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

需要权限：ohos.permission.MODIFY_AGENT_CARD

系统能力：SystemCapability.Ability.AgentRuntime.Core

参数：

参数名类型必填说明
agentCardAgentCard是要更新的AgentCard信息。

返回值：

类型说明
Promise<void>Promise对象，无返回结果。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.
18500001The bundle does not exist or no patch has been applied.
35600001The specified agentId does not exist.
35600004The specified agent card version is older than the current version.
35600005The specified agent card version is invalid.

示例：

import { agentManager, agentConstant, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let agentCard: common.AgentCard = {
  agentId: 'agent_001',
  name: '智能助手',
  description: '这是更新后的智能助手',
  version: '1.0.1',
  defaultInputModes: ['text/plain'],
  defaultOutputModes: ['text/plain'],
  skills: [{
    id: 'skill_001',
    name: '基础技能',
    description: '这是一个基础技能',
    tags: ['助手', '查询']
  }],
  iconUrl: 'common/weather_icon.png',
  category: 'productivity',
  type: agentConstant.AgentCardType.APP,
  appInfo: {
    bundleName: 'com.example.myapplication',
    moduleName: 'entry',
    abilityName: 'AgentExtAbility'
  }
};

agentManager.updateAgentCard(agentCard)
  .then(() => {
    console.info('UpdateAgentCard success.');
  })
  .catch((err: BusinessError) => {
    console.error(`UpdateAgentCard failed, error code: ${err.code}, error msg: ${err.message}.`);
  });

agentManager.deleteAgentCard

deleteAgentCard(bundleName: string, agentId: string): Promise<void>

删除指定应用agentId对应的AgentCard。

起始版本： 26.0.0

系统接口：此接口为系统接口。

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

需要权限：ohos.permission.MODIFY_AGENT_CARD

系统能力：SystemCapability.Ability.AgentRuntime.Core

参数：

参数名类型必填说明
bundleNamestring是用于标识AgentCard所属的包名。
agentIdstring是用于标识AgentCard所属的agentId。

返回值：

类型说明
Promise<void>Promise对象，无返回结果。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.
35600001The specified agentId does not exist.

示例：

import { agentManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bundleName = 'com.example.myapplication';
let agentId = 'agent_001';

agentManager.deleteAgentCard(bundleName, agentId)
  .then(() => {
    console.info('DeleteAgentCard success.');
  })
  .catch((err: BusinessError) => {
    console.error(`DeleteAgentCard failed, error code: ${err.code}, error msg: ${err.message}.`);
  });

agentManager.disconnectAgentExtensionAbility

disconnectAgentExtensionAbility(proxy: AgentProxy): Promise<void>

断开与指定proxy的AgentExtensionAbility的连接。

系统接口：此接口为系统接口。

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

需要权限：ohos.permission.CONNECT_AGENT

系统能力：SystemCapability.Ability.AgentRuntime.Core

参数：

参数名类型必填说明
proxyAgentProxy是要断开连接的AgentExtensionAbility对应的Proxy对象，在调用connectAgentExtensionAbility接口连接AgentExtensionAbility时会返回其对应的proxy对象。

返回值：

类型说明
Promise<void>Promise对象，无返回结果。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.

示例：

import { common, Want, agentManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
  comProxy: common.AgentProxy|null = null;
  build() {
    Column() {
      Row() {
        // 创建连接按钮
        Button('connect ability')
          .enabled(true)
          .onClick(() => {
            try {
              // 连接AgentExtensionAbility
              agentManager.disconnectAgentExtensionAbility(this.comProxy)
                .then(() => {
                })
                .catch((err: BusinessError) => {
                  console.error(`connectAgentExtensionAbility failed, error code: ${err.code}, error msg: ${err.message}.`);
                });
            } catch (err) {
              let code = (err as BusinessError).code;
              let msg = (err as BusinessError).message;
              console.error(`connectAgentExtensionAbility failed, error code: ${code}, error msg: ${msg}.`);
            }
          })
      }
    }
  }
}

agentManager.notifyLowCodeAgentComplete

notifyLowCodeAgentComplete(agentId: string): Promise<void>

通知指定的LOW_CODE类型的AgentCard关联的Agent生命周期已结束。

起始版本：26.0.0

系统接口：该接口为系统接口。

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

需要权限：ohos.permission.CONNECT_AGENT

系统能力：SystemCapability.Ability.AgentRuntime.Core

参数：

参数名类型必填说明
agentIdstring是用于标识AgentCard的agentId。

返回值：

类型说明
Promise<void>Promise对象，无返回结果。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
201Permission denied.
202Not system application.
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.
35600001The specified agentId does not exist.

示例：

import { agentManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let agentId = 'agent_001';

agentManager.notifyLowCodeAgentComplete(agentId)
  .then(() => {
    console.info('NotifyLowCodeAgentComplete success.');
  })
  .catch((err: BusinessError) => {
    console.error(`NotifyLowCodeAgentComplete failed, error code: ${err.code}, error msg: ${err.message}.`);
  });

agentManager.connectServiceExtensionAbility

connectServiceExtensionAbility(context: AgentExtensionContext, want: Want, callback: ConnectOptions): number

将AgentExtensionAbility连接到ServiceExtensionAbility。若目标ServiceExtensionAbility可见，可直接连接；若不可见，需申请ohos.permission.START_INVISIBLE_ABILITY权限；若目标ServiceExtensionAbility位于远程设备上，需申请ohos.permission.DISTRIBUTED_DATASYNC权限。

起始版本：26.0.0

系统接口：该接口为系统接口。

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

系统能力：SystemCapability.Ability.AgentRuntime.Core

参数：

参数名类型必填说明
contextAgentExtensionContext是当前Agent扩展能力的上下文，包含AgentCard信息。
wantWant是目标ServiceExtensionAbility的Want信息，包含bundleName、abilityName等。
callbackConnectOptions是ConnectOptions类型的回调函数，返回服务连接成功、连接失败、断开的信息。

返回值：

类型说明
number返回一个连接ID，用于标识当前AgentExtensionAbility与ServiceExtensionAbility之间的连接。该连接ID可用于后续调用disconnectServiceExtensionAbility接口断开连接。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
202Not system application.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Cannot start an invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by enterprise device management (EDM).
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16000073The app clone index is invalid.

示例：

import { common, Want, AgentExtensionAbility, agentManager, bundleManager } from '@kit.AbilityKit';
import { JSON } from '@kit.ArkTS';
import { rpc } from '@kit.IPCKit';

let TAG = 'DemoAgentForConnect';

export default class DemoAgentForConnect extends AgentExtensionAbility {

  connectService(want: Want): number {
    try {
      let options: common.ConnectOptions = {
        onConnect(elementName: bundleManager.ElementName, remote: rpc.IRemoteObject) {
          console.info(`${TAG} onConnect ${JSON.stringify(elementName)}`);
        },
        onDisconnect(elementName: bundleManager.ElementName) {
          console.info(`${TAG} onDisconnect ${JSON.stringify(elementName)}`);
        },
        onFailed(code: number) {
          console.info(`${TAG} onFailed... ${code}`);
        }
      };
      console.info(`${TAG} start connect`);
      const connectId = agentManager.connectServiceExtensionAbility(this.context, want, options);
      console.info(`${TAG} connect end, connectId=${connectId} `);
      return connectId;
    } catch (err) {
      console.error(`${TAG} connectServiceExtensionAbility failed.`);
    }
    return -1;
  }
}

agentManager.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(context: AgentExtensionContext, connectId: number): Promise<void>

断开AgentExtensionAbility与ServiceExtensionAbility的连接。

起始版本：26.0.0

系统接口：该接口为系统接口。

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

系统能力：SystemCapability.Ability.AgentRuntime.Core

参数：

参数名类型必填说明
contextAgentExtensionContext是当前Agent扩展能力的上下文，包含AgentCard信息。
connectIdnumber是connectServiceExtensionAbility返回的连接ID，用于标识要断开的目标连接。

返回值：

类型说明
Promise<void>Promise对象，无返回结果。

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID错误信息
202Not system application.
16000011The context does not exist.
16000050Internal error. Possible causes: 1.Connect to system service failed. 2.System service failed to communicate with dependency module.

示例：

import { AgentExtensionAbility, agentManager } from '@kit.AbilityKit';

let TAG = 'DemoAgentForDisConnect';

export default class DemoAgentForDisConnect extends AgentExtensionAbility {

  disconnectService(connectId: number) {
    try {
      console.info(`${TAG} start disconnect:${connectId}`);
      agentManager.disconnectServiceExtensionAbility(this.context, connectId);
      console.info(`${TAG} disconnect end:${connectId}`);
    } catch (err) {
      console.error(`${TAG} client disconnectServiceExtensionAbility failed.`);
    }
  }
}

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 js-apis-app-ability-appServiceExtensionAbility

openharmony 鸿蒙 js-apis-inner-wantAgent-triggerInfo-sys

openharmony 鸿蒙 js-apis-inner-wantAgent-wantAgentInfo-sys

openharmony 鸿蒙 js-apis-appControl-sys

openharmony 鸿蒙 js-apis-app-ability-environmentCallback

openharmony 鸿蒙 js-apis-inner-application-missionInfo-sys

openharmony 鸿蒙 js-apis-bundleManager-sharedBundleInfo-sys

openharmony 鸿蒙 js-apis-inner-application-continueMissionInfo-sys

openharmony 鸿蒙 js-apis-inner-application-appServiceExtensionContext

openharmony 鸿蒙 js-apis-bundleManager-businessAbilityInfo-sys

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/7OJXA995