目录

创作端A2A模式Agent

何时创建

端侧Agent是指部署在用户设备本地运行的Agent,能够充分利用你HarmonyOS APP内的能力,让用户在小艺内使用你的Agent时,尽可能的复用端侧应用内Agent的体验。

✅推荐场景:

你已经有成熟的端侧应用Agent,希望将自己的Agent通过小艺APP为用户提供服务,获得系统级入口能力。

创建步骤

端A2A模式Agent的接入分为两大块:APP端实现和平台配置。

[h2]第一步:APP端实现

前置条件

APP端的A2A接入准备

APP端只需增加一层接入适配,不需要重写已有Agent。接入由三个文件共同完成:AgentExtensionAbility、module.json5和agent_config.json。

创建AgentExtensionAbility

  1. (API版本24以上)在entry目录,右键选择“New > ArkTS File”,新建一个文件并命名为AgentExtAbility.ets,并且在Module中的module.json5中注册AgentExtensionAbility。
  2. (API版本为26.0.0及以上)可参考应用内Agent开发接入。

在module.json5中注册

{
  "name": "AppAgentAbility",
  "srcEntry": "./ets/agentextability/AppAgentAbility.ets",
  "type": "agent",
  "exported": true,
  "metadata": [{
    "name": "ohos.extension.agent",
    "resource": "$profile:agent_config"
  }]
 }

这里的name是真实Ability名称,稍后要如实填写到AgentCard和小艺开放平台的“应用服务名称”,若不如实填写则无法进行通信。

创建AgentCard

在resources/base/profile/agent_config.json中描述Agent,具体可参考AgentCard定义规范。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "default"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          }
        ]
      }
    ],
    "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",
          }
        ]
      }
    ]
  }
}

[h2]第二步:平台配置

在小艺开放平台创建端A2A

按照如下顺序完成模式选择、应用关联、AgentCard导入、保存和真机发布。

新建Agent并选择“端A2A模式”

进入“新建项目→Agent”,选择与APP部署方式匹配的开发模式。HarmonyOS应用接入选择“端A2A模式”。

关联HarmonyOS应用

在“应用信息”步骤点击“选择应用”,从当前开发者账号下可用的HarmonyOS应用中选择目标APP。

填写应用服务名称

平台需要“应用服务名称”来定位APP内的AgentExtensionAbility。要准确填写module.json5中type=agent那一项的name,否则无法进行通信。

导入AgentCard并创建Agent

创建Agent时,在AgentCard步骤点击“手动导入”,上传APP工程中的agent_config.json。

文件解析完成后,在“选择Agent”下拉框中选择要接入的Agent,再点击“确认创建”。

创建后核对基础信息

创建完成后进入“配置→基础信息”,核对关联应用、包名、服务名称和AgentCard信息。这里的按钮用于“重新选择”应用或“重新导入”AgentCard。

按需配置端插件权限

如果Agent需要使用位置、文件、电话、闹钟、联系人或图库等端侧能力,在“配置→端插件权限”中添加对应权限。如无需要可不进行配置。

完成可选的对话体验配置

“编排”页还提供开场白、输入文件、快捷指令、背景图片和角色声音等配置。它们用于完善体验,不是端A2A最小链路的必填项。

保存并发布真机测试

完成配置后先点击页面右上角“保存”,通过点击“真机测试”按钮进行真机测试。端Agent模式不支持云侧调试。

配置真机测试用户组

在Agent左侧进入“测试白名单”,创建或启用真机测试用户组,并确认当前华为账号已加入用户组。发布真机测试时选择需要生效的用户组。

发起第一次对话

在测试真机的小艺对话列表中找到刚发布的Agent,真机测试的Agent会带有“开发中”的标志,第一次可只验证一问一答。确保小艺和APP消息已经互通,若消息无法互通,请检查消息是否按照A2A协议定义规范。如小艺APP中未检测到最新版本的Agent,请重启小艺APP以刷新进程,待Agent数据同步完成后,再行使用。

错误调试,如果对话中信息无响应,同时查看DevEcoStudioHiLog

手机端不显示详细接入错误,可能对话发出后无任何响应,因此对话失败时,请同时打开DevEcoStudio的Log/HiLog,选择测试真机和APP进程,并按接入层TAG过滤。

正常情况下能够看到onConnect、onAuth、onData和sendData success。出现onData说明消息已经进入APP;出现sendData success说明APP已经回包。

如果对话正常,则会显示开发者预设的信息,祝贺你,端A2A接入成功,如下图:

接入完成检查