鸿蒙智能体开发实战：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 数组中，支持以下类型：
| kind |
说明 |
字段结构 |
text |
文本内容 |
{ "kind": "text", "text": "内容" } |
file |
文件/图片 |
{ "kind": "file", "file": {...} } |
data |
结构化数据 |
{ "kind": "data", "data": {...} } |
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"
}
}
两种核心事件类型
服务器给客户端返回时，使用两种事件类型：
| 事件类型 |
kind 值 |
用途 |
TaskStatusUpdateEvent |
status-update |
推送任务中间状态 |
TaskArtifactUpdateEvent |
artifact-update |
推送任务中间处理结果（带内容输出） |
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 |
已提交 |
任务刚被接收时 |
working |
处理中 |
正在执行任务 |
input-required |
需要输入 |
需要用户提供更多信息 |
completed |
已完成 |
任务成功完成 |
canceled |
已取消 |
用户取消任务 |
failed |
失败 |
任务执行失败 |
unknown |
未知 |
未知状态 |
状态更新示例
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 类型说明
| kind |
说明 |
字段结构 |
reasoningText |
深度思考内容 |
{ "kind": "reasoningText", "reasoningText": "内容" } |
text |
正文内容 |
{ "kind": "text", "text": "内容" } |
data |
结构化数据 |
{ "kind": "data", "data": {...} } |
reasoningText 类型
用于展示深度思考过程、优化后的提示词等：
{
"kind": "reasoningText",
"reasoningText": "优化后的提示词：\n详细内容..."
}
text 类型
用于展示正文内容，支持 Markdown 格式：
{
"kind": "text",
"text": "这是智能体的回复内容..."
}
data 类型
用于展示卡片、端侧指令、推荐问题等结构化数据：
{
"kind": "data",
"data": {
"cardsInfo": [{
"cardName": "custom_card",
"cardData": {...},
"displayType": "DisplayFaCard"
}]
}
}
关键字段说明
| 字段 |
类型 |
默认值 |
说明 |
append |
boolean |
false |
是否追加到前序片段 |
lastChunk |
boolean |
true |
是否是流式输出的最后一个片段 |
final |
boolean |
false |
SSE 流是否结束，true 会断开通道 |
注意：一次会话请求（final 为 true 结束）允许若干流式输出。每次流式输出以 lastChunk 为 true 结束。任务结束必须设置 final 为 true。
完整流式交互示例
场景：智能助手对话
步骤 1：客户端发起请求
POST /agent/message
Headers:
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": "{{错误描述}}"
}
}
常见错误码
| 错误码 |
说明 |
0 |
成功 |
400 |
请求参数错误 |
401 |
认证失败（Session ID 无效） |
-32601 |
方法不存在 |
500 |
服务器内部错误 |
99911114 |
内容不合规 |
99911113 |
流控限制 |
六、端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 唯一标识：
- 首次请求不携带contextId，Agent在首帧响应中生成并返回
- 会话失效场景：Agent主动失效（返回错误码99911222）或小艺主动重置
6.3 Task任务生命周期
Task是一件事从发起到完成的完整处理单元，有独立的生命周期：
| 阶段 |
状态 |
说明 |
| 创建 |
submitted |
任务刚被接收 |
| 处理 |
working |
正在执行任务 |
| 完成 |
completed |
任务成功完成 |
| 取消 |
canceled |
用户取消任务 |
| 失败 |
failed |
任务执行失败 |
提示：Task的taskId由Agent在首帧响应中分配，任务终止后不可重启。
6.4 设备上下文参数
Agent Server端可以获取设备的上下文信息，需要在平台变量配置中开启对应的系统变量：
| 参数 |
类型 |
说明 |
app_ver |
string |
小艺APP的版本号 |
foreground_apps |
string |
前台应用列表 |
device_language |
string |
设备语言设置 |
device_id |
string |
设备标识符 |
设备上下文数据通过请求中的 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 协议规范介绍了：
- 请求数据结构：text、file、data 三种 Part 类型
- 响应数据结构：TaskStatusUpdateEvent 和 TaskArtifactUpdateEvent
- 任务状态枚举：submitted、working、completed 等 7 种状态
- 流式控制字段：append、lastChunk、final 的正确使用
遵循这些规范可以确保你的智能体应用与鸿蒙设备端完美兼容。
如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！
相关资源：
- 鸿蒙Agent通信协议技术规范总览 - 华为开发者联盟
- 鸿蒙Agent通信协议消息指令定义 - 华为开发者联盟
- 鸿蒙Agent通信协议消息参数说明 - 华为开发者联盟
- SSE (Server-Sent Events) 规范
参考资源
- 鸿蒙 Agent 通信协议技术规范总览 - 华为开发者联盟
- 鸿蒙 Agent 通信协议消息指令定义 - 华为开发者联盟
10个月宝宝每天需要喝多少奶粉？
