云A2A(云端Agent-to-Agent),简单来说就是把已经部署在云端的Agent服务,通过标准协议“接”到小艺上来。
可以把它理解成一根“数据管道”——小艺在这头替用户开口说话,你的云服务负责理解和执行,再把结果通过管道送回来。你不需要关心小艺内部怎么运作,只需要按照协议规范提供一个API接口,小艺就能找到你、调用你、把你的能力呈现给用户。
云A2A能够充分利用云端大规模算力与存储,支持大型模型和知识库,可与你的现有业务系统(数据库、ERP、第三方API)直接打通。
✅推荐场景:
进入小艺开放平台->新建项目->Agent,开发模式选择云A2A模式,下划鼠标滚轮配置Agent的名称、头像、描述语和设备类型,全部配置完成后点击确认创建。

配置项 | 说明 | 参考示例 | 小艺效果展示 |
|---|---|---|---|
Agent名称 | 字数限制:20个字以内 | 天气查询助手 |
|
Agent头像 | 直角1:1不透明背景的图片,大小不超过5M,支持png、jpeg、jpg格式;详细见图标设计指南 | / | |
Agent描述 | 一句话概括Agent的主要功能,便于用户通过关键词搜索到该Agent | 可以根据你的要求快速给出天气信息和穿衣建议 |
|
设备类型选择 | 选择Agent支持的设备类型和系统版本,用户可在选定设备上使用该Agent | 分别勾选手机的HarmonyOS5.0及以上系统版本、平板的HarmonyOS5.0及以上系统版本
| Agent上线后,HarmonyOS5.0及以上的手机、平板用户,可在小艺APP搜索并使用该Agent |

下面的页面配置云侧Agent的API URL和鉴权方式,完成小艺Agent与云侧Agent的A2A对接。

API URL:云侧Agent与小艺Client Agent对话的接口,根据云侧Agent的信息配置,通信协议参考协议规范。
客户端服务器间会话维持方式:分为“由服务器侧分批Session”和“服务器间采用无状态通信,每次携带认证凭据”两种方式,按云侧Agent需求选择。
认证信息:根据云侧Agent API的鉴权方式选择,支持APIKey、AK/SK认证、OAuth认证三种方式。以API Key,Header为例,Key:默认填写Authorization即可,Value:填写云侧Agent的API Key的值。
认证方式 | 说明 |
|---|---|
API Key | Header:使用HTTP请求Header域传递参数方式认证。 Query:使用Query传递参数方式认证。该认证方式可能存在安全风险,建议使用其他认证方式。 认证方式可参考创建云插件认证方式部分。 |
AK/SK | 使用预共享密钥认证方式。 |
OAuth认证 | 使用OAuth2.0流程认证,当前仅支持Client模式,OAuth2.0协议规范,可访问OAuth2.0官方网站。 |
开场对话是用户首次进入Agent时自动展示的引导信息,旨在帮助用户快速了解Agent的用途和使用方法。
预置开场对话(静态):每次启动对话时,均展示相同的开场语和预置问题。
示例效果如下:

动态开场对话:如果希望用户每次进入Agent时,给用户呈现不同的开场语和预置问题,就可使用该功能。具体方式参考动态开场对话。
完成上面的配置后,Agent的基础功能已经调通,此时建议通过真机测试验证Agent在手机上的表现,然后再进行下面增加能力的配置和调试。
第一次使用真机测试功能,需要先配置真机测试白名单。点击“测试白名单”->“新建用户组”,创建云A2A真机测试用户组,点击加入测试组,当前开发者账号对应的华为账号便自动加入用户组,若用其它账号测试,点击管理用户可以通过邮件邀请账号加入。打开“是否开启”的开关,该用户组下的用户账号便可用于真机测试。配置好真机测试用户列表后,点击左侧的“编排”回到Agent的编排界面。

点击真机测试图标,点击发布真机测试,便可在白名单账号的小艺APP内进行真机测试。

小艺App中点击左上角菜单按钮,在“智能体”中选择你的Agent,进入后直接进行真机测试。若在小艺APP的对话列表中没有找到你的Agent,可以清理小艺APP进程中重试。

经过上述配置后,Agent答复内容将以txt文本或者markdown格式呈现给用户,如果开发者觉得markdown不足以满足输出和交互功能,希望增加“卡片”展示,可以查看本步骤。卡片展示效果如下所示:

输出配置名称:此处填写的名称必须与云侧Agent返回的绑卡数据中的cardName保持一致。云侧绑卡数据结构参考卡片数据定义。
输出配置描述:描述卡片内容即可。
输出参数:根据云侧Agent返回的卡片数据信息进行配置,可在默认的cardData下面添加参数。
参数名称:云侧Agent返回参数的名称。
参数描述:描述该参数的含义。
参数类型:云侧Agent返回参数的类型,数据类型包含String、Integer、Boolean、Double、Object、Array和Float。
输出配置示例:

Agent Server向Agent Client基于SSE协议推送结果示意:
{
"jsonrpc": "2.0",
"id": "learn-rpc-location-20260923-140551",
"result": {
"taskId": "learn-location-20260923-140551",
"kind": "artifact-update",
"append": false,
"lastChunk": true,
"final": true,
"artifact": {
"artifactId": "97ec3bdf-ea79-41f4-8ee1-9073296bd726",
"parts": [
{
"kind": "text",
"text": "当前位置为南京市,2026-09-24:白天小雨、夜间阴,气温 22~27°C,降水概率 50%,东风3级。"
},
{
"kind": "data",
"data": {
"cardsInfo": [
{
"cardName": "weatherSummary",
"cardData": {
"locationLabel": "南京市",
"dateLabel": "明天 · 09/24",
"temperature": "22~27°C",
"condition": "小雨",
"summary": "全天气温 · 最低~最高",
"detail": "降水概率 50% · 东风3级",
"weatherIcon": "{{icon的url地址}}"
},
"displayType": "EmbedMarkdown"
}
]
}
}
]
}
}
} 绑定卡片:完成输出参数配置后,点击“编辑卡片”进入卡片选择页面。

进入绑卡页面后点击“我的卡片”,点击“+新增”创建卡片。

创建卡片:选择“标准创建”,输入卡片名称(自定义即可)和卡片描述后点击“新建”进入卡片编辑页面。卡片创建也可以采用AI生成的方式,具体参考卡片。

编辑卡片
自定义变量:进入卡片编辑页面后首先在变量页面进行添加变量,自定义变量名称,变量类型选择Object(必须与A2A输出配置保持一致),把卡片参数配置到默认值编辑框。

卡片设计:绑定好变量后在组件页面进行卡片设计,可以添加布局组件和基础组件(也可以在模板页面选择合适模板直接使用或者改造使用),添加完组件后,点击内容区的(x)可以进行变量绑定。

此时,返回卡片绑定页面后,可以在“我的卡片”中看到自己已经发布的卡片。点击“添加”按钮,表示使用这张卡片承载Agent的答复结果。此处绑定变量的映射关系,就是绑定Agent的输出中,各个字段分别映射到卡片的哪些输入变量中。完成此处绑定后,运行态的数据关系就确定了。Agent返回的各个字段,按这个界面的绑定关系给卡片的输入变量,而卡片的输入变量与卡片上各个组件的绑定关系,是上面创作卡片时你设置的(x)决定的。有了这两层绑定关系,就可以做到Agent的输出呈现在卡片中。

提示:若修改卡片配置,需要在新版本卡片发布后,在绑卡页面点击“立即升级”后保存才可生效。

绑定卡片建议使用真机测试功能进行验证,以手机上的展示效果为准。
为使云A2A模式的Agent能够调用位置服务、账号绑定等手机端系统能力,平台支持绑定端插件(插件广场中的端插件目前仅对企业开发者开放),Agent可通过端插件与设备侧应用交互。
添加插件的操作步骤如下:

以位置服务插件为例,可以具备获取当前位置的能力。

处理流程和示例代码:
步骤 | 处理 |
1 | 用户询问当前位置天气,Agent返回GetCurrentLocation指令。 |
2 | 小艺获得用户授权后返回UploadExeResult事件。 |
3 | Agent校验latitude和longitude,并优先读取定位结果中的城市和区县。 |
定位指令示意:
Agent Server向小艺发送报文,调用GetCurrentLocation端插件请求位置服务:
{
"jsonrpc": "2.0",
"id": "ac65354f-ade2-45c9-b7be-2d10d52c9ea4&3&6d69&0",
"result": {
"taskId": "ac65354f-ade2-45c9-b7be-2d10d52c9ea4&3&6d69&0",
"kind": "artifact-update",
"append": true,
"final": false,
"lastChunk": false,
"artifact": {
"artifactId": "875aa96d-43a7-4d05-8469-07673fca35cf",
"parts": [
{
"kind": "data",
"data": {
"commands": [
{
"header": {
"namespace": "Common",
"name": "Action"
},
"payload": {
"cardParam": {},
"needUploadResult": true,
"pageControlRelated": false,
"responses": [
{
"displayText": "",
"ttsText": "",
"resultCode": ""
}
],
"executeParam": {
"permissionId": [],
"executeMode": "background",
"achieveType": "INTENT",
"actionResponse": true,
"intentName": "GetCurrentLocation",
"intentParam": {
"cacheValidityPeriod": 300
},
"bundleName": "com.huawei.******",
"needUnlock": true,
"dimension": "",
"timeOut": 5
}
}
}
]
}
}
]
}
}
} 小艺调用端插件获取到位置信息后,返回给Agent Server的报文示例:
{
"conversationId": "66ab2b954ca241c89efe48882adf16db",
"deviceId": "0181ec2d-cea6-793b-ab22-e974ab724c03",
"id": "ac65354f-ade2-45c9-b7be-2d10d52c9ea4&3&6d69&0",
"jsonrpc": "2.0",
"method": "message/stream",
"params": {
"id": "ac65354f-ade2-45c9-b7be-2d10d52c9ea4&3&6d69&0",
"message": {
"kind": "message",
"messageId": "ac65354f-ade2-45c9-b7be-2d10d52c9ea4&3&6d69&0",
"parts": [
{
"data": {
"events": [
{
"header": {
"name": "UploadExeResult",
"namespace": "Common"
},
"payload": {
"intentName": "GetCurrentLocation",
"isNeedAgentInfo": false,
"outputs": {
"accuracy": 8.5,
"additionSize": 2,
"additions": [
"requestId:f04780f9-a323-4f9e-8808-0fd5c189e978",
"locateType:Wifi"
],
"additionsMap": {},
"altitude": 0,
"altitudeAccuracy": 0,
"direction": 0,
"directionAccuracy": 0,
"isFromMock": false,
"latitude": 40.0572459,
"longitude": 116.1792998,
"sourceType": 2,
"speed": 0,
"speedAccuracy": 0,
"timeSinceBoot": 3428629036054486,
"timeStamp": 1790592612662,
"uncertaintyOfTimeSinceBoot": 0
}
}
}
]
},
"kind": "data"
}
],
"role": "user"
},
"sessionId": "66ab2b954ca241c89efe48882adf16db"
},
"sessionId": "ac65354f-ade2-45c9-b7be-2d10d52c9ea4"
} 实现要点
获取用户的账号信息用于登录使用,云侧Agent有对应的HarmonyOS应用在同一个开发者账号下,可以直接绑定该HarmonyOS应用的Client ID,若无HarmonyOS应用,需要到HarmonyOS开发者中心完成HarmonyOS应用创建,获取Client ID用于绑定使用,参考账号绑定。
