端侧Agent是指部署在用户设备本地运行的Agent,能够充分利用你HarmonyOS APP内的能力,让用户在小艺内使用你的Agent时,尽可能的复用端侧应用内Agent的体验。
✅推荐场景:
你已经有成熟的端侧应用Agent,希望将自己的Agent通过小艺APP为用户提供服务,获得系统级入口能力。
前置条件
APP端的A2A接入准备
APP端只需增加一层接入适配,不需要重写已有Agent。接入由三个文件共同完成:AgentExtensionAbility、module.json5和agent_config.json。
创建AgentExtensionAbility
在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",
}
]
}
]
}
} 按照如下顺序完成模式选择、应用关联、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接入成功,如下图:

接入完成检查