使用AgentExtensionAbility组件提供的智能体服务（仅对系统应用开放）

概述

从API version 24开始，支持系统应用可以通过agentManager中的connectAgentExtensionAbility方法，连接其他应用已实现的AgentExtensionAbility组件，并使用其提供的智能体服务。系统应用与智能体可以进行双向通信和双向安全认证。

说明

本文描述中称被连接的AgentExtensionAbility为服务端，称连接AgentExtensionAbility的组件为客户端。

客户端与服务端交互机制概述

客户端与服务端交互流程如下图所示：

演示图

建立连接

客户端可以通过调用agentManager中的connectAgentExtensionAbility方法连接服务端的AgentExtensionAbility（在Want对象中指定连接的目标服务）。

成功建立连接后会触发服务端的onConnect()方法，并在该方法中接收到客户端传递过来的Want对象和客户端的AgentHostProxy对象。
收发数据

客户端通过调用connectAgentExtensionAbility方法连接服务端并接收返回的AgentProxy对象。客户端可以使用该AgentProxy对象的sendData()方法向服务端发送数据。

服务端在onData()方法中可以接收客户端发送的数据和AgentHostProxy对象，并且可以通过AgentHostProxy的sendData()方法向客户端发送数据。

客户端通过AgentExtensionConnectCallback中的onData()方法接收服务端发送的数据。
安全认证（可选）

客户端通过调用connectAgentExtensionAbility方法连接服务端并接收返回的AgentProxy对象。客户端可以使用该AgentProxy对象的authorize()方法向服务端发送安全认证请求。

服务端在onAuth()方法中可以接收客户端发送的安全认证请求以及AgentHostProxy对象，并且可以通过AgentHostProxy的authorize()方法向客户端发送安全认证请求。

客户端通过AgentExtensionConnectCallback的onAuth()方法接收服务端发送的安全认证请求。
断开连接

客户端调用connectAgentExtensionAbility方法连接服务端时，可以保存服务端返回的AgentProxy对象。客户端可以通过调用disconnectAgentExtensionAbility方法利用保存的AgentProxy对象来断开与服务端的连接。

连接和断连AgentExtensionAbility

使用connectAgentExtensionAbility方法建立与AgentExtensionAbility的连接。

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.sample.agentextensionability',
              abilityName: 'AgentExtAbility',
            };
            let agentId: string = 'weather_assistant_001';
            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}.`);
            }
          })
        // ...
      }
    }
  }
}

Index.ets

使用disconnectAgentExtensionAbility方法断开与AgentExtensionAbility的连接。

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('disconnect ability')
          .enabled(true)
          .onClick(() => {
            try{
              // this.agentProxy是连接时保存的proxy对象
              agentManager.disconnectAgentExtensionAbility(this.comProxy).then(() => {
                console.info(`disconnectAgentExtensionAbility success.`);
              }).catch((error: BusinessError) => {
                console.error(`disconnectAgentExtensionAbility failed, err code: ${error.code}, err msg: ${error.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}.`);
            }
          })
      }
    }
  }
}

Index.ets

客户端与服务端双向通信

客户端收发数据

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.sample.agentextensionability',
              abilityName: 'AgentExtAbility',
            };
            let agentId: string = 'weather_assistant_001';
            try {
              // 连接AgentExtensionAbility
              agentManager.connectAgentExtensionAbility(connectWant, agentId, this.connectCallback)
                .then((proxy: common.AgentProxy) => {
                  this.comProxy = proxy;
                  let data = 'test data';
                  try {
                    this.comProxy.sendData(data);
                  } catch (err) {
                    let code = (err as BusinessError).code;
                    let msg = (err as BusinessError).message;
                    console.error(`sendData failed, err code: ${code}, err msg: ${msg}.`);
                  }
                  // ...
                })
                .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}.`);
            }
          })
        // ...
      }
    }
  }
}

Index.ets

服务端收发数据

详见使用AgentExtensionAbility组件收发数据。

客户端与服务端双向安全认证

客户端处理和发送安全认证请求

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.sample.agentextensionability',
              abilityName: 'AgentExtAbility',
            };
            let agentId: string = 'weather_assistant_001';
            try {
              // 连接AgentExtensionAbility
              agentManager.connectAgentExtensionAbility(connectWant, agentId, this.connectCallback)
                .then((proxy: common.AgentProxy) => {
                  this.comProxy = proxy;
                  // ...
                  let authorizeData = 'authorize data';
                  try {
                    this.comProxy.authorize(authorizeData);
                  } catch (err) {
                    let code = (err as BusinessError).code;
                    let msg = (err as BusinessError).message;
                    console.error(`sendData failed, err code: ${code}, err msg: ${msg}.`);
                  }
                })
                .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}.`);
            }
          })
        // ...
      }
    }
  }
}

Index.ets

服务端处理和发送安全认证请求

详见使用AgentExtensionAbility组件接收和发送安全认证请求。