【HarmonyOS 7】 应用 Agent 接入云 A2A 与端 A2A 的实践详解
英文标题：【HarmonyOS 7】 应用 Agent 接入云 A2A 与端 A2A 的实践详解
【HarmonyOS 7】 应用 Agent 接入云 A2A 与端 A2A 的实践详解 一、前言 用户说一句 帮我预约最近的银行网点，真正有价值的结果不是返回一段网点介绍，而是完成查询、筛选、确认，必
3.2 KB
589 B
28.7 KB
6.2 KB
8.8 KB
3.2 KB
中文
【HarmonyOS 7】 应用 Agent 接入云 A2A 与端 A2A 的实践详解
一、前言
用户说一句 帮我预约最近的银行网点，真正有价值的结果不是返回一段网点介绍，而是完成查询、筛选、确认，必要时继续预约 。
这类体验和普通问答的区别，在于应用要成为任务链中的一个执行者。系统负责理解用户意图，应用负责提供业务能力，两者之间需要一条稳定的连接通道。简单理解：不只是回答问题，而是用手和脚处理问题，与用户交互，直到问题闭环。
在鸿蒙的应用 Agent 方案里，常见的落点可以分成两类：云 A2A 和端 A2A。
从小艺APP的左侧菜单，点击智能体：Agent广场，找到的Agent都属于云A2A： 端侧一般是App应用内的Agent功能。
这里的 A2A 可以理解成，Agent 与 Agent 之间传递意图、上下文和执行结果的通道 。它不是把所有能力都交给一个大模型，也不是把应用简单套上一层聊天界面。
二、应用的能力在哪里执行，来选择云还是端
一个应用接入系统 Agent 之前，先回答三个问题：
**1. 业务数据主要在云端还是设备端？ 2. 任务执行是否依赖本地设备、应用状态或端侧隐私数据？
- 现有系统里是否已经有 Agent Server、API 或 MCP 工具？**
如果应用已经有成熟的云端 Agent，业务服务和数据也主要在云上，云 A2A 通常更顺手。如果任务需要读取应用内数据、调用设备能力，或者希望把应用内的交互卡片复用到小艺对话中，端 A2A 更合适。
简单说：云 A2A 解决，云上的业务 Agent 如何接入系统入口。端 A2A 解决，设备和应用里的智能能力如何被系统安全调用。
三、云 A2A：把已有的云端 Agent 接进小艺
云 A2A 的典型链路大致是：
用户
↓
小艺入口
↓
小艺开放平台 / 鸿蒙 A2A channel
↓
Agent Server
↓
业务 API、数据库、支付或其他云服务
开发者不需要重新实现一个系统级助手，而是准备好一个能够独立完成任务的云端 Agent，再通过开放平台完成接入配置。
1、 Agent Server 需要具备什么
一个可接入的 Agent Server，至少要把下面几件事处理清楚：
能够根据用户输入识别业务意图 能够调用业务系统完成实际操作，而不是只生成说明文字 能够返回结构化结果，方便系统展示卡片、按钮或下一步动作 能够处理登录、授权、超时和重复请求 能够在任务失败时给出明确原因和可恢复的下一步
例如“帮我买一张电影票”不是一个简单的查询接口，它可能包含影片搜索、场次选择、座位布局、订单创建和支付几个阶段。每个阶段都可能需要用户确认，也可能因为库存变化而重新选择。
对 Agent Server 来说，重要的是保存任务状态，而不是把每一步都塞进一条超长提示词里。任务状态可以落在服务端，也可以通过业务订单状态回查，但必须能处理重复调用和中断恢复。
2、 接入时不要只准备一个聊天接口
很多团队接入时只暴露了一个“输入文本，返回文本”的接口，结果只能做演示，无法完成真正的业务闭环。更实用的做法是把结果分成几类：
{
"status": "need_confirmation",
"message": "已找到今晚 19:25 的场次",
"data": {
"cinema": "中影南方影城",
"seatMap": "...",
"price": 38.0
},
"actions": [
{"type": "select_seat", "label": "选择座位"},
{"type": "cancel", "label": "换一个场次"}
]
}
字段名这里只是示意，实际以当前开放平台协议和组件规范为准。 关键思想是：文本负责解释，结构化数据负责让界面和后续动作继续运行。
买电影票的案例就体现了这一点。用户从帮我买电影票开始，后面经历了座位选择、生成订单、跳转收银台和完成支付。对话只是入口，卡片和业务服务才是任务真正落地的地方。
3、云 A2A 更适合这些场景
已经有成熟的云端 Agent 或智能客服系统 需要访问云端商品、订单、内容和金融数据 任务涉及复杂检索、规划或多步业务编排 业务希望同时服务多个终端，不想把核心逻辑绑定在某一种设备上
但云端方案也有边界。它需要认真处理网络抖动、身份传递、结果时效和隐私数据最小化。 不能因为入口变成自然语言，就跳过原有的权限、风控和审计流程。
三、端 A2A：让应用内 Agent 与系统 Agent 协同
端 A2A 的重点不在，把云端 Agent 搬到手机上，而在于让鸿蒙应用中的 Agent 能够与小艺安全通信。
它通常依托应用侧的 Agent Extension Ability，承载查询上下文、流式文本输出和 Agent UI Extension 等能力。用户既可以在应用内部使用 Agent，也可以从小艺主对话进入应用能力。
可以把链路理解成：
小艺
↕ Query 上下文 / 流式结果 / UI Extension
鸿蒙应用内 Agent
↓
应用数据、端侧能力、业务模块
1、端 A2A 的价值在数据边界
端侧方案适合处理这些情况：
数据本来就存在设备端或应用本地 任务依赖当前应用状态 需要调用系统设备能力 用户希望敏感数据留在设备侧处理 应用需要控制自己的 UI 卡片和交互流程
银行的案例可以用来说明这个方向。用户说“用招行预约最近的网点”，系统负责理解意图和进入任务，银行应用负责网点查询及业务流程。端 A2A 的重点不是替应用决定业务规则，而是让应用保留自己的数据和能力边界，同时能够被系统入口触达。
“隐私数据不出端”不能被理解成一句不需要验证的绝对承诺。实际项目仍要看数据类型、调用链路、授权方式和平台规范。工程上应该明确哪些字段可以传递，哪些字段只能在应用内部处理，哪些操作必须二次确认。
2、 UI Extension 不是装饰
如果 Agent 只返回一段文字，用户还要回到应用里完成所有操作，体验仍然是割裂的。UI Extension 的意义在于：应用可以把结构化、可交互的卡片呈现在小艺对话中，并保留必要的加密和数据控制。
这对订单、座位、网点、表单、设备控制等场景尤其重要。展示层应该只暴露完成任务所需的信息，不要把应用内部全部页面原样搬进对话。
四、云 A2A 和端 A2A 怎么选
| 判断项 | 云 A2A | 端 A2A |
|---|---|---|
| 主要执行位置 | 云端 Agent Server | 鸿蒙设备和应用内部 |
| 适合的数据 | 云端业务数据、内容、订单 | 本地数据、应用状态、设备能力 |
| 典型场景 | 票务、内容、云端客服、复杂业务 | 金融端内服务、健康、设备控制、应用内任务 |
| 交互特点 | 通过平台接入系统入口 | 通过 Agent Extension Ability 与小艺协同 |
| 重点工作 | 服务编排、认证、状态、结果组件 | 权限、数据边界、端内能力、UI Extension |
| 主要风险 | 网络、身份、数据传输、重复操作 | 端侧权限、数据泄露、组件隔离和版本适配 |
实际项目不一定非要二选一。一个应用可以把搜索和复杂推理放在云端，把本地隐私数据和设备操作放在端侧，再通过清晰的任务边界组合起来。重要的是不要让一条自然语言请求跨越多个系统后，没人说得清每一步是谁执行的、拿到了什么数据、出了问题怎么回滚。
五、接入前要列出的工程清单
意图清单
先从真实用户任务出发，而不是从“我们有一个 Agent”出发。把高频请求写成具体句子，再标记每个请求需要哪些数据、工具和确认点。
权限和身份
明确用户身份如何从系统入口传递到应用，哪些动作需要登录，哪些动作需要二次确认。支付、预约、删除和提交类操作不能只靠模型判断是否执行。
状态和幂等
多步任务一定会遇到重复请求、中断和网络超时。创建订单、预约网点、发起支付等接口必须设计幂等键和状态查询，不能因为用户重复说了一次就生成两笔业务记录。
结果呈现
把文本、卡片、按钮和可继续执行的动作设计成一套结果模型。用户需要知道当前做到哪一步、下一步是什么、是否需要确认。
端云边界
把端侧和云侧的数据画成一张图，特别标出敏感字段、授权范围和日志内容。出了问题时，日志既要能定位，又不能把隐私数据完整打出来。
失败兜底
没有结果、结果过期、服务不可用、用户取消，都应该有正常的回退路径。一个好的 Agent 不是永远说“可以”，而是在不能完成时把原因和下一步说清楚。
应用 Agent 化的关键，不是给应用加一个聊天框，而是让应用成为系统任务链中可靠的一环。云 A2A 适合把成熟的云端业务接到系统入口，端 A2A 适合把应用内能力、设备能力和本地数据交给系统调度。
选型时先看数据和执行位置，再看协议和界面。把用户的一句话拆成可执行、可确认、可恢复的步骤，Agent 接入才不会停留在演示层面。
小艺开放平台入口：developer.huawei.com/consumer/cn…
English / 原文
【HarmonyOS 7】 应用 Agent 接入云 A2A 与端 A2A 的实践详解
一、前言
用户说一句 帮我预约最近的银行网点，真正有价值的结果不是返回一段网点介绍，而是完成查询、筛选、确认，必要时继续预约 。
这类体验和普通问答的区别，在于应用要成为任务链中的一个执行者。系统负责理解用户意图，应用负责提供业务能力，两者之间需要一条稳定的连接通道。简单理解：不只是回答问题，而是用手和脚处理问题，与用户交互，直到问题闭环。
在鸿蒙的应用 Agent 方案里，常见的落点可以分成两类：云 A2A 和端 A2A。
从小艺APP的左侧菜单，点击智能体：Agent广场，找到的Agent都属于云A2A： 端侧一般是App应用内的Agent功能。
这里的 A2A 可以理解成，Agent 与 Agent 之间传递意图、上下文和执行结果的通道 。它不是把所有能力都交给一个大模型，也不是把应用简单套上一层聊天界面。
二、应用的能力在哪里执行，来选择云还是端
一个应用接入系统 Agent 之前，先回答三个问题：
**1. 业务数据主要在云端还是设备端？ 2. 任务执行是否依赖本地设备、应用状态或端侧隐私数据？
- 现有系统里是否已经有 Agent Server、API 或 MCP 工具？**
如果应用已经有成熟的云端 Agent，业务服务和数据也主要在云上，云 A2A 通常更顺手。如果任务需要读取应用内数据、调用设备能力，或者希望把应用内的交互卡片复用到小艺对话中，端 A2A 更合适。
简单说：云 A2A 解决，云上的业务 Agent 如何接入系统入口。端 A2A 解决，设备和应用里的智能能力如何被系统安全调用。
三、云 A2A：把已有的云端 Agent 接进小艺
云 A2A 的典型链路大致是：
用户
↓
小艺入口
↓
小艺开放平台 / 鸿蒙 A2A channel
↓
Agent Server
↓
业务 API、数据库、支付或其他云服务
开发者不需要重新实现一个系统级助手，而是准备好一个能够独立完成任务的云端 Agent，再通过开放平台完成接入配置。
1、 Agent Server 需要具备什么
一个可接入的 Agent Server，至少要把下面几件事处理清楚：
能够根据用户输入识别业务意图 能够调用业务系统完成实际操作，而不是只生成说明文字 能够返回结构化结果，方便系统展示卡片、按钮或下一步动作 能够处理登录、授权、超时和重复请求 能够在任务失败时给出明确原因和可恢复的下一步
例如“帮我买一张电影票”不是一个简单的查询接口，它可能包含影片搜索、场次选择、座位布局、订单创建和支付几个阶段。每个阶段都可能需要用户确认，也可能因为库存变化而重新选择。
对 Agent Server 来说，重要的是保存任务状态，而不是把每一步都塞进一条超长提示词里。任务状态可以落在服务端，也可以通过业务订单状态回查，但必须能处理重复调用和中断恢复。
2、 接入时不要只准备一个聊天接口
很多团队接入时只暴露了一个“输入文本，返回文本”的接口，结果只能做演示，无法完成真正的业务闭环。更实用的做法是把结果分成几类：
{
"status": "need_confirmation",
"message": "已找到今晚 19:25 的场次",
"data": {
"cinema": "中影南方影城",
"seatMap": "...",
"price": 38.0
},
"actions": [
{"type": "select_seat", "label": "选择座位"},
{"type": "cancel", "label": "换一个场次"}
]
}
字段名这里只是示意，实际以当前开放平台协议和组件规范为准。 关键思想是：文本负责解释，结构化数据负责让界面和后续动作继续运行。
买电影票的案例就体现了这一点。用户从帮我买电影票开始，后面经历了座位选择、生成订单、跳转收银台和完成支付。对话只是入口，卡片和业务服务才是任务真正落地的地方。
3、云 A2A 更适合这些场景
已经有成熟的云端 Agent 或智能客服系统 需要访问云端商品、订单、内容和金融数据 任务涉及复杂检索、规划或多步业务编排 业务希望同时服务多个终端，不想把核心逻辑绑定在某一种设备上
但云端方案也有边界。它需要认真处理网络抖动、身份传递、结果时效和隐私数据最小化。 不能因为入口变成自然语言，就跳过原有的权限、风控和审计流程。
三、端 A2A：让应用内 Agent 与系统 Agent 协同
端 A2A 的重点不在，把云端 Agent 搬到手机上，而在于让鸿蒙应用中的 Agent 能够与小艺安全通信。
它通常依托应用侧的 Agent Extension Ability，承载查询上下文、流式文本输出和 Agent UI Extension 等能力。用户既可以在应用内部使用 Agent，也可以从小艺主对话进入应用能力。
可以把链路理解成：
小艺
↕ Query 上下文 / 流式结果 / UI Extension
鸿蒙应用内 Agent
↓
应用数据、端侧能力、业务模块
1、端 A2A 的价值在数据边界
端侧方案适合处理这些情况：
数据本来就存在设备端或应用本地 任务依赖当前应用状态 需要调用系统设备能力 用户希望敏感数据留在设备侧处理 应用需要控制自己的 UI 卡片和交互流程
银行的案例可以用来说明这个方向。用户说“用招行预约最近的网点”，系统负责理解意图和进入任务，银行应用负责网点查询及业务流程。端 A2A 的重点不是替应用决定业务规则，而是让应用保留自己的数据和能力边界，同时能够被系统入口触达。
“隐私数据不出端”不能被理解成一句不需要验证的绝对承诺。实际项目仍要看数据类型、调用链路、授权方式和平台规范。工程上应该明确哪些字段可以传递，哪些字段只能在应用内部处理，哪些操作必须二次确认。
2、 UI Extension 不是装饰
如果 Agent 只返回一段文字，用户还要回到应用里完成所有操作，体验仍然是割裂的。UI Extension 的意义在于：应用可以把结构化、可交互的卡片呈现在小艺对话中，并保留必要的加密和数据控制。
这对订单、座位、网点、表单、设备控制等场景尤其重要。展示层应该只暴露完成任务所需的信息，不要把应用内部全部页面原样搬进对话。
四、云 A2A 和端 A2A 怎么选
| 判断项 | 云 A2A | 端 A2A |
|---|---|---|
| 主要执行位置 | 云端 Agent Server | 鸿蒙设备和应用内部 |
| 适合的数据 | 云端业务数据、内容、订单 | 本地数据、应用状态、设备能力 |
| 典型场景 | 票务、内容、云端客服、复杂业务 | 金融端内服务、健康、设备控制、应用内任务 |
| 交互特点 | 通过平台接入系统入口 | 通过 Agent Extension Ability 与小艺协同 |
| 重点工作 | 服务编排、认证、状态、结果组件 | 权限、数据边界、端内能力、UI Extension |
| 主要风险 | 网络、身份、数据传输、重复操作 | 端侧权限、数据泄露、组件隔离和版本适配 |
实际项目不一定非要二选一。一个应用可以把搜索和复杂推理放在云端，把本地隐私数据和设备操作放在端侧，再通过清晰的任务边界组合起来。重要的是不要让一条自然语言请求跨越多个系统后，没人说得清每一步是谁执行的、拿到了什么数据、出了问题怎么回滚。
五、接入前要列出的工程清单
意图清单
先从真实用户任务出发，而不是从“我们有一个 Agent”出发。把高频请求写成具体句子，再标记每个请求需要哪些数据、工具和确认点。
权限和身份
明确用户身份如何从系统入口传递到应用，哪些动作需要登录，哪些动作需要二次确认。支付、预约、删除和提交类操作不能只靠模型判断是否执行。
状态和幂等
多步任务一定会遇到重复请求、中断和网络超时。创建订单、预约网点、发起支付等接口必须设计幂等键和状态查询，不能因为用户重复说了一次就生成两笔业务记录。
结果呈现
把文本、卡片、按钮和可继续执行的动作设计成一套结果模型。用户需要知道当前做到哪一步、下一步是什么、是否需要确认。
端云边界
把端侧和云侧的数据画成一张图，特别标出敏感字段、授权范围和日志内容。出了问题时，日志既要能定位，又不能把隐私数据完整打出来。
失败兜底
没有结果、结果过期、服务不可用、用户取消，都应该有正常的回退路径。一个好的 Agent 不是永远说“可以”，而是在不能完成时把原因和下一步说清楚。
应用 Agent 化的关键，不是给应用加一个聊天框，而是让应用成为系统任务链中可靠的一环。云 A2A 适合把成熟的云端业务接到系统入口，端 A2A 适合把应用内能力、设备能力和本地数据交给系统调度。
选型时先看数据和执行位置，再看协议和界面。把用户的一句话拆成可执行、可确认、可恢复的步骤，Agent 接入才不会停留在演示层面。
小艺开放平台入口：developer.huawei.com/consumer/cn…