# 使用AgentExtensionAbility组件实现智能体服务

#### 概述

在跨应用协作场景下，开发者经常需要从系统应用调用其他应用提供的智能体服务，但缺少标准化的通信机制，导致集成成本高、安全认证复杂。从API version 24开始，支持开发者使用AgentExtensionAbility类型的组件提供智能体服务。系统应用可以连接其他应用实现的AgentExtensionAbility组件，并使用相应的智能体服务。通过使用该组件，可降低跨应用对接成本，保障通信安全，同时支持双向数据通道实时交互。

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

#### 实现AgentExtensionAbility组件

在DevEco Studio工程中手动新建一个AgentExtensionAbility，具体步骤如下：

1.  在工程Module对应的ets目录下，右键选择"New > Directory"，新建一个目录并命名为agentextability。
    
2.  在AgentExtAbility目录，右键选择"New > ArkTS File"，新建一个文件并命名为AgentExtAbility.ets。
    
    ```
    ├── ets
    │ ├── agentextability
    │ │   ├── AgentExtAbility.ets
    ```
    
3.  在AgentExtAbility.ets文件中，补充AgentExtensionAbility的导入模块，自定义类AgentExtAbility继承AgentExtensionAbility并实现生命周期回调。
    
    ```
    import { common, AgentExtensionAbility, Want } from '@kit.AbilityKit';
    import { hilog } from '@kit.PerformanceAnalysisKit';
    
    export default class AgentExtAbility extends AgentExtensionAbility {
      private comProxy: common.AgentHostProxy | null = null;
      // 创建AgentExtensionAbility
      onCreate(want: Want) {
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
      }
    
      // 连接
      onConnect(want: Want, proxy: common.AgentHostProxy) {
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onConnect');
        this.comProxy = proxy;
      }
    
      // 断开连接
      onDisconnect(want: Want, proxy: common.AgentHostProxy) {
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDisconnect');
        this.comProxy = null;
      }
      // 接收数据
      onData(proxy: common.AgentHostProxy, data: string) {
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onData');
        try {
          let replyData = 'reply message';
          proxy.sendData(replyData);
        } catch (err) {
          let code = (err as BusinessError).code;
          let msg = (err as BusinessError).message;
          console.error(`sendData failed, err code: ${code}, err msg: ${msg}.`);
        }
      }
      // 认证
      onAuth(proxy: common.AgentHostProxy, handshakeData: string) {
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onAuth');
        try {
          // 处理认证逻辑
          let authResult = 'auth success';
          proxy.authorize(authResult);
        } catch (err) {
          let code = (err as BusinessError).code;
          let msg = (err as BusinessError).message;
          console.error(`sendData failed, err code: ${code}, err msg: ${msg}.`);
        }
      }
      // 销毁
      onDestroy() {
        hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy');
      }
    }
    ```
    
4.  在工程Module对应的module.json5配置文件中注册AgentExtensionAbility，type标签需要设置为"agent"，srcEntry标签表示当前ExtensionAbility组件所对应的代码路径。
    
    ```
    {
      "module": {
        "extensionAbilities": [
          {
            "name": "AgentExtAbility",
            "icon": "$media:icon",
            "description": "agent",
            "type": "agent",
            "exported": true,
            "srcEntry": "./ets/agentextability/AgentExtAbility.ets",
            "metadata": [
              {
                "name": "ohos.extension.agent",
                "resource": "$profile:agent_config",
              }
            ]
          }
        ]
      }
    }
    ```
    
5.  在工程Module的resources/base/profile/目录下新建agent\_config.json文件，然后在其中配置AgentCard信息，详细操作步骤请参考Agent配置文件说明。
    

#### 使用AgentExtensionAbility组件收发数据

应用可以在服务端AgentExtensionAbility组件的onData()方法中接收客户端传递的数据和AgentHostProxy对象，并且可以通过调用AgentHostProxy对象的sendData()方法将数据发送给客户端。

```
import { common, AgentExtensionAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class AgentExtAbility extends AgentExtensionAbility {
  // ...
  // 接收数据
  onData(proxy: common.AgentHostProxy, data: string) {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onData');
    try {
      let replyData = 'reply message';
      proxy.sendData(replyData);
    } catch (err) {
      let code = (err as BusinessError).code;
      let msg = (err as BusinessError).message;
      console.error(`sendData failed, err code: ${code}, err msg: ${msg}.`);
    }
  }
  // ...
}
```

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

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

```
import { common, AgentExtensionAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class AgentExtAbility extends AgentExtensionAbility {
  // ...
  // 认证
  onAuth(proxy: common.AgentHostProxy, handshakeData: string) {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onAuth');
    try {
      // 处理认证逻辑
      let authResult = 'auth success';
      proxy.authorize(authResult);
    } catch (err) {
      let code = (err as BusinessError).code;
      let msg = (err as BusinessError).message;
      console.error(`sendData failed, err code: ${code}, err msg: ${msg}.`);
    }
  }
  // ...
}
```