# 查询任务状态与结果

发送消息后，使用任务 ID 查询智能体的最新状态和结果。任务可能经历运行、等待输入和终态；只有进入完成终态并读取到应用需要的结果，才算完成调用。

## 前提条件

- 已从发送消息的响应中保存 Task `id`。
- 已保存创建该任务时使用的 `agent_id` 或 `agent_code`。

```bash
export TASK_ID='<task-id-from-message-response>'
export REQUEST_ID='<new-unique-request-id>'
```

## 查询任务

`tasks/get` 和发送消息使用相同的接口地址，通过 `method` 区分操作：

```bash
curl -X POST "$PRODUCT_API_BASE_URL/agents/a2a" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent_id\": \"$AGENT_ID\",
    \"jsonrpc\": \"2.0\",
    \"id\": \"$REQUEST_ID\",
    \"method\": \"tasks/get\",
    \"params\": {
      \"id\": \"$TASK_ID\"
    }
  }"
```

`params.id` 是任务 ID，不是 JSON-RPC 请求 ID。查询时应继续使用创建任务时的智能体选择器；任务 ID 本身不负责选择智能体。

## 检查状态和结果

```json
{
  "jsonrpc": "2.0",
  "id": "<REQUEST_ID>",
  "result": {
    "kind": "task",
    "id": "<TASK_ID>",
    "contextId": "<CONTEXT_ID>",
    "status": {
      "state": "completed"
    },
    "artifacts": [
      {
        "artifactId": "<ARTIFACT_ID>",
        "parts": [
          {
            "kind": "text",
            "text": "<RESULT_TEXT>"
          }
        ]
      }
    ]
  }
}
```

| 字段 | 返回条件 | 说明 |
| --- | --- | --- |
| `result.id` | Task 结果返回 | 当前任务 ID。 |
| `result.status.state` | Task 结果返回 | 当前任务状态。应用应容忍尚未识别的新状态。 |
| `result.status.message` | 状态带消息时返回 | 与当前状态相关的消息。按其中的 Part 类型读取。 |
| `result.artifacts` | 任务已经产生结果时返回 | 智能体产物列表。Artifact 是有类型的结果容器，不一定只有文本。 |
| `result.artifacts[].parts` | 智能体产物有内容时返回 | 文本、结构化数据或文件信息等结果部件。按 `kind` 分别处理。 |
| `result.contextId` | 智能体提供上下文时返回 | 后续普通消息继续同一会话时使用。 |

常见状态的处理方式：

| 状态 | 应用动作 |
| --- | --- |
| `submitted`、`working` | 任务仍在处理。按调用方的最大等待时间继续查询。 |
| `input-required` | 暂停查询，向用户展示智能体的问题，再提交后续输入。 |
| `completed` | 读取并校验智能体产物或消息中的业务结果。 |
| `failed` | 读取状态消息和错误信息，保留任务 ID 用于排查。 |
| `canceled` | 停止等待；不要假定智能体已经回滚外部副作用。 |

轮询应设置整体截止时间、最大次数和退避间隔。客户端超时不等于服务端任务失败，也不能把未知状态当作成功。

## 取消任务

仍允许取消时，使用 `tasks/cancel`，参数仍为任务 ID。取消请求返回后再次使用 `tasks/get` 确认状态。任务取消不能撤销已经发生的外部写入或工具调用。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 查不到任务 | Task ID、智能体选择器和工作区 | 使用创建任务时保存的三个值重新请求。 |
| 状态长期为运行中 | 最后状态、状态消息和等待时长 | 停止无界轮询，保留任务 ID 并检查调用日志。 |
| `completed` 但没有文本 | `artifacts` 和各 Part 的 `kind` | 检查结构化数据或文件 Part，不要只搜索 `text`。 |
| 收到未知状态 | 原始状态和协议版本 | 保持任务未完成的保守处理，并重新获取智能体调用信息。 |

## 下一步

- [提交后续输入](submit-follow-up-input.md)
- [发送消息并启动任务](call-agent-a2a.md)