# 查询智能体会话任务记录

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

读取一个可访问智能体会话中的任务投影，以恢复历次调用的状态、展示内容和产物。此接口不发送新消息，也不执行或重试任务。

```text
GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/conversations/{conversation_id}/tasks
```

## 调用前准备

`PRODUCT_API_BASE_URL` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

PRODUCT_API_BASE_URL 包含目标环境的产品前缀。准备本人的凭据与有权限的 WORKSPACE_ID，路径 ID 和 X-Workspace-ID 必须一致。示例 ID 需替换为该环境的实际返回值。 会话 ID 来自智能体 conversations 的创建、列表或详情，不使用独立 LLM 数值会话 ID。

## 请求

:::::::{div} mo-api-tabs mo-api-request-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --get "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/conversations/$CONVERSATION_ID/tasks" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "agent_id=$AGENT_ID" \
  --data-urlencode "agent_workspace_id=$AGENT_WORKSPACE_ID"
```

:::::
:::::{tab-item} 参数说明

| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| agent_id | string | 否 | 校验会话所属智能体范围。 |
| agent_workspace_id | string | 否 | 智能体来源工作区，只能为当前工作区或 system。传 agent_id 但省略此值时默认当前工作区。 |

本动作没有 limit/offset/游标；当前 handler 不读取这些参数。普通会话限当前创建者；系统 workflow 创作会话另按工作区范围处理，仍需身份和角色授权。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{"code":0,"data":{"items":[{"kind":"task","id":"task-example","contextId":"conversation-example","status":{"state":"working","timestamp":"2026-11-12T01:02:03Z"},"metadata":{"eventCursor":3,"agentId":"agent-example"}}]}}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.items | array | 本次会话任务记录，为 A2A Task 投影。无结果为空数组。 |
| data.items[].kind | string | task。 |
| data.items[].id | string | 真实任务 ID，后续任务查询使用此值。 |
| data.items[].contextId | string | 智能体会话上下文 ID；字段使用 A2A 驼峰格式。 |
| data.items[].status.state | string | A2A 状态，不直接复用原始运行时内部状态枚举。 |
| data.items[].status.timestamp | string | 任务更新时间。 |
| data.items[].status.message | object | 可选的当前展示消息；parts 中可有多种内容。 |
| data.items[].artifacts | array | 有产物时返回的 A2A 产物，可能省略。 |
| data.items[].metadata | object | 任务展示元数据；可含 eventCursor、manifestId、provider、agentId、traceId 等。 |

A2A 状态包括 submitted、working、input-required、auth-required、completed、failed、canceled、rejected；queued 投影为 submitted，cancel_requested/reconciling 等内部状态投影为 working。不要把不同接口的状态枚举直接比较。

:::::
::::::
:::::::

## 判断结果

结果可含运行中尚在变化的展示内容；请求成功不代表所有任务完成，也不是原始私有事件日志。任务按会话回合的持久化顺序合并读取，不能按 id 字符串推断时间。私有事件不会作为直接事件数组返回；缺少产物字段也不等于从未执行过任务。

后续查询或控制任务时保留当前工作区、智能体来源工作区、智能体 ID、contextId 和实际 id。不得把 contextId 当 task ID，或把任务 id 传到会话消息接口。

## 错误

先校验会话作用域，再读取任务历史。会话或任务不存在/范围不匹配可返回 404；参数错误为 400，权限失败为 403。任务或候选展示损坏可返回 500，依赖失败可返回 503/504。失败时不把空列表当成功结果，也不据读取失败重复发送消息。
