鸿蒙应用 Agent 实操：云 A2A 与端 A2A 接入指南

很多开发者把应用接入大模型后，会发现一个非常典型的尴尬：用户问“帮我预约最近的银行网点”，应用只是礼貌地返回一段网点介绍文字。真正有价值的体验，应该是系统理解意图后，应用能自动完成查询、筛选、确认甚至完成预约。本期教程就以鸿蒙 7 的应用 Agent 方案为例，带开发者理清云 A2A 与端 A2A 两条接入路径的选型、实现要点与避坑指南，适合应用架构师、鸿蒙开发者以及正在规划 AI 化改造的产品同学阅读。

先弄懂：A2A 到底解决什么问题？

应用要变成“任务执行者”而不是“陪聊员”，就需要一条稳定的连接通道，让系统（比如小艺）负责理解用户意图，应用负责提供业务能力。这条在 Agent 之间传递意图、上下文和执行结果的通道，就是 A2A（Agent-to-Agent）。判断你的应用属于哪种场景，先回答三个核心问题：

• 你的业务数据主要存在云端，还是设备本地？
• 任务执行是否依赖本地设备、应用内状态或端侧隐私数据？
• 团队是否已有现成的 Agent Server、API 或 MCP 工具链？

简单概括：云 A2A 解决“云上的业务 Agent 如何接入系统入口”，端 A2A 解决“设备和应用内的能力如何被系统安全调用”。

方案选型：云 A2A 与端 A2A 对比一览

明确了数据位置和执行依赖后，可以直接对照下表判断主链路：

实际项目中并不必非此即彼。比较稳妥的做法是把复杂检索和推理放云端，把隐私数据与设备操作留端侧，用清晰的任务边界把两者组合起来。但一定要注意：不能让一条自然语言请求跨越多个系统后，没有人说得清每一步是谁执行的、出了问题怎么回滚。

云 A2A 接入：把云端 Agent 接进小艺

云 A2A 的典型链路是：用户对小艺说话，指令经过小艺开放平台或鸿蒙 A2A channel 到达你的 Agent Server，再由 Server 调用业务 API、数据库或支付服务。接入时有三个最容易踩的坑：

第一，不要只准备一个“文本进、文本出”的接口。 只暴露聊天接口的接入基本只能做演示，无法完成业务闭环。实用做法是返回结构化结果，让系统渲染卡片与后续操作按钮。比如买电影票的返回可以包含状态（需要确认）、说明文字（已找到今晚 19:25 场次）、数据实体（影院、座位图、价格）以及动作列表（选座、换场次）。天气、票务这类多步任务，必须把“文本解释”和“结构化动作”分成两层设计。

第二，状态要存在服务端，而不是塞进超长提示词。 以“帮我买一张电影票”为例，任务可能经历影片搜索、场次选择、座位确认、订单创建、支付跳转五六个阶段。每个阶段都可能需要用户确认，也可能因库存变化回退。Agent Server 必须保存任务状态，支持重复调用与中断恢复，绝不能指望模型自己“记住”一切。

第三，业务闭环能力比意图识别更关键。 一个合格的 Agent Server 至少要做到：识别业务意图、真实调用业务系统（而非生成说明文字）、处理登录授权与超时、任务失败时给出明确原因和可恢复的下一步。

端 A2A 接入：守住数据边界是核心

端 A2A 并不是把云端 Agent 搬到手机上，而是让鸿蒙应用内的 Agent 能与小艺安全通信。它通常依托应用侧的 Agent Extension Ability，承载查询上下文、流式输出与 UI Extension 能力。选择端侧方案的核心价值在于数据边界。

以“用招行预约最近的网点”为例，系统只负责听懂意图并启动任务，银行应用负责网点查询与业务流转。端 A2A 的重点不是替应用决定业务规则，而是让应用保留自己的数据和能力边界，同时能被系统入口触达。它特别适合四类情况：数据本就在设备或应用本地；任务依赖当前应用运行状态；需要调用系统设备能力（如蓝牙、传感器）；用户希望敏感数据留在端侧处理。

这里要重点提醒两个工程细节：其一，“隐私数据不出端”不是一句无需验证的承诺。 必须落实哪些字段允许传递、哪些只能在应用内处理、哪些操作必须二次确认。其二，UI Extension 不是界面装饰。 如果 Agent 只返回一段文字，用户还得切回应用重新操作，体验依然是割裂的。把结构化卡片放进小艺对话中（如选座图、预约详情、控制开关），并只展示完成任务所需的最小信息，才是端侧体验真正闭环的关键。

接入前必查：五项工程清单

无论选哪种方案，正式开发前建议先跑完这份清单：

• 意图清单：从真实用户任务而不是“我们有个 Agent”出发，把高频请求写成具体句子，标注每个请求需要的数据、工具和确认点。
• 权限和身份：明确用户身份如何从系统入口传递到应用；支付、预约、删除等敏感动作必须要求登录或二次确认，不能全靠模型判断。
• 状态和幂等：创建订单、发起支付等接口必须设计幂等键与状态回查，不能因为用户多说了一句话就生成两笔业务记录。
• 端云边界图：画出端侧与云侧的数据流向，标出敏感字段、授权范围与日志内容。日志既要能定位问题，又不能把隐私数据完整打出来。
• 失败兜底：没有结果、结果过期、服务不可用、用户取消，都要有正常回退路径。好的 Agent 不是永远说“可以”，而是办不到时把原因和下一步讲清楚。

小结

应用 Agent 化的关键，从来不是给应用套一个聊天框，而是让应用成为系统任务链中可靠的一环。云 A2A 适合把成熟云端业务快速接入系统入口，端 A2A 适合把应用内能力、设备能力和本地数据交给系统安全调度。选型时先看数据在哪里、执行在哪里，再看协议和 UI。能把用户的一句话拆解成可执行、可确认、可恢复的步骤，你的 Agent 接入才算真正走出了演示阶段。

本文基于 rss-juejin《【HarmonyOS 7】 应用 Agent 接入云 A2A 与端 A2A 的实践详解》深度重写，事实与观点归原作者所有。建议阅读原文。原作者：GeorgePanda。发布于 2026-10-15。