鸿蒙智能体开发实战：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/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": "{{错误描述}}"
    }
}

常见错误码

六、端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 规范