鸿蒙智能体开发实战：7.A2A 模式消息规范

鸿蒙智能体开发实战：A2A 模式消息规范

前言

在鸿蒙 Agent 通信协议（A2A 模式）中，消息规范是确保智能体与客户端正确通信的关键。本文严格遵循华为官方定义的 A2A 协议规范，详细介绍消息格式、数据结构和状态流转。

本文基于华为鸿蒙官方 A2A 协议规范编写，确保与鸿蒙设备端兼容性。

协议总体架构

鸿蒙 A2A 协议采用JSON-RPC 2.0作为基础通信协议，通过SSE（Server-Sent Events）实现流式输出。

核心端点

所有消息统一通过/agent/message端点处理：

POST /agent/message Headers: Content-Type: application/json agent-session-id: <session-id> (initialize 方法除外)

A2A 基础配置与输出设置

完成协议理解后，在小艺开放平台上创建 A2A 智能体时，需要正确配置基础信息和输出设置。

基础配置入口

A2A 基础配置是 A2A 模式必填节点，入口如下图所示：

基础配置详情

配置页面包含 API URL、会话维持方式、认证信息、方法声明等核心参数：

输出设置

A2A 输出设置用于绑定响应卡片：

绑定卡片

添加输出后可绑定具体卡片：

请求数据结构定义

通用请求格式

{"jsonrpc":"2.0","id":"{{全局唯一消息序列号，字符串}}","method":"{{方法名}}","params":{"id":"{{请求任务唯一 ID}}","sessionId":"{{客户端会话 ID}}","agentLoginSessionId":"{{登录身份凭证 ID}}","message":{"role":"user","parts":[...]}}}

Message Parts 类型说明

客户端发送消息时，内容放在parts数组中，支持以下类型：

text 类型

用户输入的文本内容：

{"kind":"text","text":"用户输入 Query 或子任务 Query"}

file 类型

发送文件或图片：

{"kind":"file","file":{"name":"文件名","mimeType":"MIME 类型","bytes":"文件的字节码（与 uri 互斥）","uri":"文件的 URI 地址（与 bytes 互斥）"}}

data 类型

结构化数据，用于存放用户参数、端侧事件等：

{"kind":"data","data":{"events":[...],// 端侧事件"userInputInfo":{...},// 用户输入信息"variables":{...}// 客户端变量}}

响应数据结构定义

响应总体概览

服务器返回的响应使用 JSON-RPC 2.0 格式：

{"jsonrpc":"2.0","id":"{{从请求中取出的消息序列号}}","result":{// 结果对象（TaskStatusUpdateEvent 或 TaskArtifactUpdateEvent）},"error":{"code":"0","message":"success"}}

两种核心事件类型

服务器给客户端返回时，使用两种事件类型：

TaskStatusUpdateEvent - 状态更新事件

结构定义

{"jsonrpc":"2.0","id":"{{消息序列号}}","result":{"taskId":"{{任务 ID，与请求中的 id 一致}}","kind":"status-update","final":false,"status":{"message":{"role":"agent","parts":[{"kind":"text","text":"{{状态描述文本}}"}]},"state":"{{任务状态}}"}},"error":{"code":"0","message":"success"}}

任务状态（state）枚举值

状态更新示例

submitted 状态

{"jsonrpc":"2.0","id":"msg-001","result":{"taskId":"task-001","kind":"status-update","final":false,"status":{"message":{"role":"agent","parts":[{"kind":"text","text":"正在理解您的需求..."}]},"state":"submitted"}},"error":{"code":"0","message":"success"}}

working 状态

{"jsonrpc":"2.0","id":"msg-001","result":{"taskId":"task-001","kind":"status-update","final":false,"status":{"message":{"role":"agent","parts":[{"kind":"text","text":"正在思考中..."}]},"state":"working"}},"error":{"code":"0","message":"success"}}

TaskArtifactUpdateEvent - 内容更新事件

结构定义

{"jsonrpc":"2.0","id":"{{消息序列号}}","result":{"taskId":"{{任务 ID}}","kind":"artifact-update","append":false,"lastChunk":true,"final":false,"artifact":{"artifactId":"{{本条 Artifact 的唯一 ID}}","parts":[...]}},"error":{"code":"0","message":"success"}}

Artifact Parts 类型说明

reasoningText 类型

用于展示深度思考过程、优化后的提示词等：

{"kind":"reasoningText","reasoningText":"优化后的提示词：\n详细内容..."}

text 类型

用于展示正文内容，支持 Markdown 格式：

{"kind":"text","text":"这是智能体的回复内容..."}

data 类型

用于展示卡片、端侧指令、推荐问题等结构化数据：

{"kind":"data","data":{"cardsInfo":[{"cardName":"custom_card","cardData":{...},"displayType":"DisplayFaCard"}]}}

关键字段说明

注意：一次会话请求（final 为 true 结束）允许若干流式输出。每次流式输出以lastChunk为true结束。任务结束必须设置final为true。

完整流式交互示例

场景：智能助手对话

步骤 1：客户端发起请求

POST/agent/messageHeaders:Content-Type:application/json agent-session-id:8f01f3d172cd4396a0e535ae8aec6687{"jsonrpc":"2.0","id":"msg-001","method":"message/stream","params":{"id":"task-001","sessionId":"session-001","message":{"role":"user","parts":[{"kind":"text","text":"你好，请介绍一下你自己"}]}}}

步骤 2：服务器返回 submitted 状态

{"jsonrpc":"2.0","id":"msg-001","result":{"taskId":"task-001","kind":"status-update","final":false,"status":{"message":{"role":"agent","parts":[{"kind":"text","text":"正在理解您的需求..."}]},"state":"submitted"}},"error":{"code":"0","message":"success"}}

步骤 3：服务器返回 working 状态

{"jsonrpc":"2.0","id":"msg-001","result":{"taskId":"task-001","kind":"status-update","final":false,"status":{"message":{"role":"agent","parts":[{"kind":"text","text":"正在思考中..."}]},"state":"working"}},"error":{"code":"0","message":"success"}}

步骤 4：服务器返回思考内容（reasoningText）

{"jsonrpc":"2.0","id":"msg-001","result":{"taskId":"task-001","kind":"artifact-update","append":false,"lastChunk":true,"final":false,"artifact":{"artifactId":"task-001-thinking","parts":[{"kind":"reasoningText","reasoningText":"用户想要了解我的基本信息和功能..."}]}},"error":{"code":"0","message":"success"}}

步骤 5：服务器流式返回正文内容（text）

第一个片段：

{"jsonrpc":"2.0","id":"msg-001","result":{"taskId":"task-001","kind":"artifact-update","append":false,"lastChunk":false,"final":false,"artifact":{"artifactId":"task-001-response","parts":[{"kind":"text","text":"你好！我是智能助手，"}]}},"error":{"code":"0","message":"success"}}

第二个片段（追加）：

{"jsonrpc":"2.0","id":"msg-001","result":{"taskId":"task-001","kind":"artifact-update","append":true,"lastChunk":false,"final":false,"artifact":{"artifactId":"task-001-response","parts":[{"kind":"text","text":"可以帮你解答问题、完成任务。"}]}},"error":{"code":"0","message":"success"}}

最后一个片段：

{"jsonrpc":"2.0","id":"msg-001","result":{"taskId":"task-001","kind":"artifact-update","append":true,"lastChunk":true,"final":false,"artifact":{"artifactId":"task-001-response","parts":[{"kind":"text","text":"有什么可以帮你的吗？"}]}},"error":{"code":"0","message":"success"}}

步骤 6：服务器返回完成状态

{"jsonrpc":"2.0","id":"msg-001","result":{"taskId":"task-001","kind":"status-update","final":true,"status":{"message":{"role":"agent","parts":[{"kind":"text","text":"任务完成！"}]},"state":"completed"}},"error":{"code":"0","message":"success"}}

错误响应格式

JSON-RPC 错误结构

{"jsonrpc":"2.0","id":"{{消息序列号}}","result":{"taskId":"{{任务 ID}}","kind":"status-update","final":true,"status":{"state":"failed"}},"error":{"code":"{{错误码}}","message":"{{错误描述}}"}}

常见错误码

六、端A2A协议规范

除了云端A2A协议，鸿蒙还支持端侧A2A协议，用于小艺Client Agent与应用内Agent的直接通信。

6.1 核心概念

端A2A协议定义了四个层次的概念模型：

Context（会话） │ 由Agent管理会话并分配contextId，相同的contextId标识同一个会话 │ └── Task（任务）× N │ 一件事从发起到完成的全过程，期间可包含多次消息往返 │ └── Artifact（产出物）× N │ Task的产出单元，同一Artifact内的内容组合呈现 │ └── Part × N Artifact的组成分片，承载具体内容（文本、卡片、指令等）

6.2 Context会话管理

Context是会话的逻辑容器，通过contextId唯一标识：

1. 首次请求不携带contextId，Agent在首帧响应中生成并返回
2. 只要contextId不变，会话即持续有效
3. 会话失效场景：Agent主动失效（返回错误码99911222）或小艺主动重置

6.3 Task任务生命周期

Task是一件事从发起到完成的完整处理单元，有独立的生命周期：

提示：Task的taskId由Agent在首帧响应中分配，任务终止后不可重启。

6.4 设备上下文参数

Agent Server端可以获取设备的上下文信息，需要在平台变量配置中开启对应的系统变量：

设备上下文数据通过请求中的data.variables.systemVariables字段传递：

{"kind":"data","data":{"variables":{"systemVariables":[{"app_ver":"11.3.8.300","foreground_apps":"com.example.app"}]}}}

七、消息规范最佳实践

7.1 必须使用正确的 kind 值

• 状态更新必须使用kind: "status-update"
• 内容输出必须使用kind: "artifact-update"

7.2 正确设置流式控制字段

一次完整交互流程： status-update (submitted) → status-update (working) → artifact-update (append: false, lastChunk: false) → artifact-update (append: true, lastChunk: false) → artifact-update (append: true, lastChunk: true) → status-update (final: true, state: completed)

7.3 及时返回 submitted 状态

收到请求后应立即返回submitted状态，让客户端知道请求已接收。

7.4 合理使用 reasoningText

将思考过程、中间推理结果放在reasoningText中，与正文text分开。

7.5 final 字段谨慎使用

final: true会断开 SSE 连接，只有在任务真正结束时才设置为true。

小结

本文严格按照华为鸿蒙官方 A2A 协议规范介绍了：

1. 请求数据结构：text、file、data 三种 Part 类型
2. 响应数据结构：TaskStatusUpdateEvent 和 TaskArtifactUpdateEvent
3. 任务状态枚举：submitted、working、completed 等 7 种状态
4. 流式控制字段：append、lastChunk、final 的正确使用
5. 完整交互示例：从请求到响应的完整 SSE 流

遵循这些规范可以确保你的智能体应用与鸿蒙设备端完美兼容。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• 鸿蒙Agent通信协议技术规范总览 - 华为开发者联盟
• 鸿蒙Agent通信协议消息指令定义 - 华为开发者联盟
• 鸿蒙Agent通信协议消息参数说明 - 华为开发者联盟
• 端侧插件工具指令说明 - 华为开发者联盟
• 设备上下文参数指令说明 - 华为开发者联盟
• 底部快捷指令说明 - 华为开发者联盟
• SSE (Server-Sent Events) 规范
• JSON-RPC 2.0 规范

参考资源

• 鸿蒙 Agent 通信协议技术规范总览 - 华为开发者联盟
• 鸿蒙 Agent 通信协议消息指令定义 - 华为开发者联盟
• SSE 规范