目录

创作云A2A模式Agent

云A2A(云端Agent-to-Agent),简单来说就是把已经部署在云端的Agent服务,通过标准协议“接”到小艺上来。

可以把它理解成一根“数据管道”——小艺在这头替用户开口说话,你的云服务负责理解和执行,再把结果通过管道送回来。你不需要关心小艺内部怎么运作,只需要按照协议规范提供一个API接口,小艺就能找到你、调用你、把你的能力呈现给用户。

何时创建

云A2A能够充分利用云端大规模算力与存储,支持大型模型和知识库,可与你的现有业务系统(数据库、ERP、第三方API)直接打通。

✅推荐场景:

创建步骤

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

[h2]第一步:前置准备

在开始之前,你需要确保:

[h2]第二步:在小艺开放平台创建Agent

进入小艺开放平台->新建项目->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

[h2]第三步:A2A基础配置

Agent创建成功后,进入到“编排”页面工作台。其中“A2A基础配置”是你需要完成的必选配置项。

下面的页面配置云侧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官方网站。

[h2]第四步: 设置Agent开场语

开场对话是用户首次进入Agent时自动展示的引导信息,旨在帮助用户快速了解Agent的用途和使用方法。

预置开场对话(静态):每次启动对话时,均展示相同的开场语和预置问题。

示例效果如下:

动态开场对话:如果希望用户每次进入Agent时,给用户呈现不同的开场语和预置问题,就可使用该功能。具体方式参考动态开场对话。

[h2]第五步:真机测试

完成上面的配置后,Agent的基础功能已经调通,此时建议通过真机测试验证Agent在手机上的表现,然后再进行下面增加能力的配置和调试。

第一次使用真机测试功能,需要先配置真机测试白名单。点击“测试白名单”->“新建用户组”,创建云A2A真机测试用户组,点击加入测试组,当前开发者账号对应的华为账号便自动加入用户组,若用其它账号测试,点击管理用户可以通过邮件邀请账号加入。打开“是否开启”的开关,该用户组下的用户账号便可用于真机测试。配置好真机测试用户列表后,点击左侧的“编排”回到Agent的编排界面。

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

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

[h2]第六步:A2A输出配置(可选)

经过上述配置后,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的输出呈现在卡片中。

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

绑定卡片建议使用真机测试功能进行验证,以手机上的展示效果为准。

[h2]第七步:输入文件设置(可选)

根据你的Agent需求配置是否支持用户向Agent发送图片或者文件,配置和使用效果如下。如果你的Agent只接收文字输入,那可以直接越过这一步。

用户侧效果:

[h2]第八步:快捷指令(可选)

配置底部的快捷指令,快速跳转或发送指令。详细情况可参考快捷指令。

[h2]第九步:插件(可选,企业开发者支持)

为使云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"
}

实现要点

[h2]第十步:账号绑定设置(可选)

获取用户的账号信息用于登录使用,云侧Agent有对应的HarmonyOS应用在同一个开发者账号下,可以直接绑定该HarmonyOS应用的Client ID,若无HarmonyOS应用,需要到HarmonyOS开发者中心完成HarmonyOS应用创建,获取Client ID用于绑定使用,参考账号绑定。