查询任务状态与结果¶

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

前提条件¶

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

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

查询任务¶

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

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 本身不负责选择智能体。

检查状态和结果¶

{
  "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`。
收到未知状态	原始状态和协议版本	保持任务未完成的保守处理，并重新获取智能体调用信息。

下一步¶

最后更新于 2026 年 8 月 14 日