A2A Task：生命周期、状态与操作

Task 是 A2A 中的核心行动单元。它有自己的标识、当前状态、到目前为止产生的结果，以及一路上交换过的消息。智能体不必为每个请求都创建任务：它可以直接用一条 Message 回答，也可以在工作需要长时间跟踪时发起任务。何时用哪种，见任务的生命周期。

字段

字段	必填	说明
`id`	是	唯一标识，由服务器在创建任务时生成
`contextId`	否	把属于同一次对话或会话的任务与消息归为一组
`status`	是	一个 `TaskStatus`：当前 `state`，以及可选的 `message` 和 `timestamp`
`artifacts`	否	该任务产生的输出，即 Artifact
`history`	否	任务期间交换的 Message
`metadata`	否	自定义元数据的键值对象

TaskStatus 中的 timestamp 是 ISO 8601 的 UTC 字符串，例如 2024-03-15T11:00:00Z。

任务状态

每个任务恰好处于八个状态之一。终态会结束任务；中断状态会让任务暂停，直到客户端采取行动。

状态	类型	含义
`TASK_STATE_SUBMITTED`	活跃	任务已提交并被确认
`TASK_STATE_WORKING`	活跃	智能体正在处理任务
`TASK_STATE_INPUT_REQUIRED`	中断	智能体需要用户补充输入才能继续
`TASK_STATE_AUTH_REQUIRED`	中断	需要认证才能继续
`TASK_STATE_COMPLETED`	终态	成功完成
`TASK_STATE_FAILED`	终态	因错误结束
`TASK_STATE_CANCELED`	终态	在完成前被取消
`TASK_STATE_REJECTED`	终态	智能体决定不执行该任务，无论是创建时还是之后

另外还有 TASK_STATE_UNSPECIFIED，表示状态未知，它不属于正常的生命周期。

任务一旦进入终态就不能重新开始。细化或跟进要在同一个 contextId 下启动新任务，这样每个任务都是清晰、不可变的工作单元。向处于终态的任务发送消息，会返回 UnsupportedOperationError。

创建任务

客户端不会直接创建任务。它用 SendMessage（或 SendStreamingMessage）发送一条消息，由智能体决定用 Task 还是 Message 来响应。规范中有两条标识规则：

任务 ID 始终由服务器生成。不支持由客户端提供 taskId 来创建新任务。
客户端在消息中填写 taskId 时，必须引用一个已存在的任务，否则智能体返回 TaskNotFoundError。

立即完成的任务

这是规范中的基础场景：客户端提问，响应是一个已带有产出物的已完成任务。请求：

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"
  }
}

响应：

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "task": {
    "id": "task-uuid",
    "contextId": "context-uuid",
    "status": {"state": "TASK_STATE_COMPLETED"},
    "artifacts": [{
      "artifactId": "artifact-uuid",
      "name": "Weather Report",
      "parts": [{"text": "Today will be sunny with a high of 75°F"}]
    }]
  }
}

需要更多输入的任务

智能体缺少信息无法完成时，会把任务切换到 TASK_STATE_INPUT_REQUIRED，并在状态消息里说明需要什么。客户端随后发送一条带相同 taskId（和 contextId）的新消息继续交互。第一个请求：

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

{
  "message": {
    "role": "ROLE_USER",
    "parts": [{"text": "Book me a flight"}],
    "messageId": "msg-1"
  }
}

智能体返回一个被中断的任务：

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "task": {
    "id": "task-uuid",
    "status": {
      "state": "TASK_STATE_INPUT_REQUIRED",
      "message": {
        "role": "ROLE_AGENT",
        "parts": [{"text": "I need more details. Where would you like to fly from and to?"}]
      }
    }
  }
}

跟进请求带上 taskId：

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

{
  "message": {
    "taskId": "task-uuid",
    "role": "ROLE_USER",
    "parts": [{"text": "From San Francisco to New York"}],
    "messageId": "msg-2"
  }
}

多轮之间适用同样的 contextId 与 taskId 规则：

只提供 taskId 时，智能体根据任务推断 contextId。
两者都提供但不一致时，智能体必须拒绝该消息。
客户端可以只发送 contextId 而不带 taskId，在已有对话中启动一个新任务。

读取、列出与取消任务

操作	作用	值得注意的规则
`GetTask`	返回单个任务的当前状态，包括状态、产出物，以及可选的历史	`historyLength` 未设置表示客户端不设上限，`0` 表示不返回历史，正数表示最多返回这么多条最近的消息
`ListTasks`	列出已认证客户端可见的任务，支持过滤和分页	可按 `contextId`、`status` 或 `statusTimestampAfter` 过滤；基于游标分页，用 `pageSize`（默认 50，最大 100）和 `pageToken`；最近更新的排在前面；除非 `includeArtifacts` 为 `true`，否则不返回产出物；最后一页的 `nextPageToken` 是空字符串
`CancelTask`	请求取消一个运行中的任务	不保证成功；无法取消的任务返回 `TaskNotCancelableError`
`SubscribeToTask`	为已有任务打开更新流	需要 `capabilities.streaming`；对已处于终态的任务返回 `UnsupportedOperationError`

获取更新

A2A 提供三种互补的方式来跟踪任务：

轮询，使用 GetTask：简单，适用于所有绑定，延迟较高。
流式传输，使用 SendStreamingMessage 和 SubscribeToTask：低延迟，需要持久连接以及 capabilities.streaming: true。
推送通知：智能体向客户端注册的 webhook 发送 HTTP POST。需要 capabilities.pushNotifications: true。

流式响应要么只有一条 Message，要么以 Task 开头。对于任务，流从 Task 对象开始，随后是零个或多个 statusUpdate 与 artifactUpdate 事件，任务进入终态时流关闭。事件按生成顺序送达。下面是规范中的流式示例：

HTTP/1.1 200 OK
Content-Type: text/event-stream

data: {"task": {"id": "task-uuid", "contextId": "context-uuid", "status": {"state": "TASK_STATE_WORKING"}}}

data: {"artifactUpdate": {"taskId": "task-uuid", "contextId": "context-uuid", "artifact": {"parts": [{"text": "# Climate Change Report\n\n"}]}}}

data: {"statusUpdate": {"taskId": "task-uuid", "contextId": "context-uuid", "status": {"state": "TASK_STATE_COMPLETED"}}}

流式传输和推送见流式传输与异步操作。

影响任务的发送选项

SendMessage 接受可选的 configuration：

returnImmediately：为 true 时，任务创建后立即返回；为 false（默认）时，智能体会等到任务进入终态或中断状态才返回。
historyLength：响应中最多包含多少条最近的历史消息。
acceptedOutputModes：客户端能接受的媒体类型，智能体应据此调整输出。
taskPushNotificationConfig：用于接收任务更新通知的 webhook。