A2A Message：角色、字段与使用场景

Message 是客户端与服务器之间的一个通信单元。它有发送者角色，以及承载内容的一个或多个 Part 。它可以属于某个对话上下文、某个任务，或者两者都属于。

字段

字段	必填	说明
`messageId`	是	唯一标识，由创建消息的一方生成
`role`	是	发送者：`ROLE_USER`（客户端发往服务器）或 `ROLE_AGENT`（服务器发往客户端）
`parts`	是	消息内容，是一组 Part
`contextId`	否	把消息关联到某个对话上下文
`taskId`	否	把消息关联到某个 Task
`referenceTaskIds`	否	本消息为获取更多上下文而引用的其他任务 ID
`metadata`	否	任意附加的键值元数据
`extensions`	否	出现在本消息中或由本消息贡献的扩展的 URI

JSON 中的 role 使用枚举名 ROLE_USER 和 ROLE_AGENT，本页所有示例都是如此。

各个 ID 之间的关系

来自服务器的消息必须带 contextId；只有创建了任务时才带 taskId。
来自客户端的消息可以两者都带、只带一个，或都不带。两者都带时必须一致，即 contextId 必须是任务上设置的那一个。只带 taskId 时，服务器会根据它推断 contextId。
messageId 由发送方创建。智能体可以用它检测重复消息，SendMessage 因此可以做到幂等。
referenceTaskIds 是客户端把跟进请求指向早前工作的方式。客户端应当用它显式引用相关任务，智能体应当借助这些任务理解跟进请求的意图。

发送消息

对话的第一条消息只需要角色、parts 和 messageId。下面是规范基础场景中的请求：

POST /message:send HTTP/1.1
Host: agent.example.com
Content-Type: application/a2a+json
Authorization: Bearer token

{
  "message": {
    "role": "ROLE_USER",
    "parts": [{"text": "What is the weather today?"}],
    "messageId": "msg-uuid"
  }
}

之后由智能体选择如何回答。它可以创建任务来处理消息，也可以为简单交互直接返回一条 Message。使用流式传输时，直接回答就是一个只包含一条 Message 的流，随后立即关闭。

跟进早前的工作

细化请求是在同一个 contextId 下、引用早前任务的新消息。下面是任务的生命周期中的跟进消息，这里只展示消息本体，role 写成协议的枚举值：

{
  "role": "ROLE_USER",
  "messageId": "msg-user-002",
  "contextId": "ctx-conversation-abc",
  "referenceTaskIds": [
    "task-boat-gen-123"
  ],
  "parts": [
    {
      "text": "Please modify the sailboat to be red."
    }
  ]
}

要回答智能体提出的问题，客户端则发送带有被暂停任务 taskId 的消息。这一交互见 Task 页面。

消息用来做什么

规范赋予消息四项职责：

发起任务：客户端发送消息以启动新任务。
澄清：智能体可以在发起任务之前，回送一条消息请求澄清。
状态消息：智能体在状态更新上附带一条消息，用于汇报进度、请求输入或提供信息。
任务交互：客户端发送消息，为运行中的任务提供更多输入或指令。

消息不用来交付结果。 规范指出消息不应用来交付任务输出，结果应当作为任务上的 Artifact 返回。通信走消息，数据输出走产出物。

消息与任务历史

任务的 history 保存任务期间交换的消息，但并不保证每条消息都会被存储。临时的提示性消息可能不会保留，任务创建之前交换的消息也可能不会存储。具体持久化哪些，由智能体决定。使用流式传输的客户端如果断开后重连，也可能错过部分状态消息，所以消息不得被当作关键信息的可靠送达机制。

可能遇到的错误

ContentTypeNotSupportedError：消息某个 part 使用的媒体类型不被智能体支持。
TaskNotFoundError：taskId 不存在或不可访问。
UnsupportedOperationError：消息被发送给了已处于终态的任务。