# 查询会话消息

读取可见会话中已保存的消息。此接口只读；新消息由智能体调用的 A2A 运行时写入，不通过此接口创建。

```text
GET https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/conversations/{conversation_id}/messages
```

## 调用前准备

先[查询会话详情](get-session.md)或[创建会话](create-session.md)取得会话 ID。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和会话 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$CONVERSATION_ID`：要查询消息的会话 ID。
- `$AGENT_ID`：可选的智能体筛选 ID。

## 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `workspace_id` | string | 是 | 当前工作区 ID，必须与 `X-Workspace-ID` 一致。 |
| `conversation_id` | string | 是 | 要查询消息的会话 ID。 |

## 查询参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `agent_id` | string | 否 | 仅查询属于指定智能体的会话。未提供时不按智能体 ID 过滤。 |
| `agent_workspace_id` | string | 否 | 智能体所属工作区 ID。指定 `agent_id` 时未提供该参数则使用当前工作区；只能指定当前工作区或系统工作区。 |
| `role` | string | 否 | 按消息角色筛选。 |
| `limit` | integer | 否 | 单次返回数量。未提供或小于等于 `0` 时为 `50`，最大为 `200`。 |
| `offset` | integer | 否 | 返回偏移量。未提供或小于 `0` 时为 `0`。 |

## 请求示例

```bash
curl --get "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/conversations/$CONVERSATION_ID/messages" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "agent_id=$AGENT_ID" \
  --data-urlencode "role=assistant" \
  --data-urlencode "limit=50"
```

## 成功响应

成功时返回 `200`。`data.items` 是本页已保存的消息，按会话消息序号提供关联信息和内容分段。

```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "msg_01",
        "workspace_id": "ws_01",
        "conversation_id": "conv_01",
        "task_id": "task_01",
        "agent_id": "agent_01",
        "role": "assistant",
        "parts": [
          {
            "kind": "text",
            "text": "分析已完成"
          }
        ],
        "seq": 2,
        "created_at": "2026-01-02T15:04:05Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

响应字段如下。

本文中，字段路径中的 `[]` 表示数组中的每一项。例如，`items[].name` 表示 `items` 数组中每一项的 `name` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功时为 `0`。 |
| `data.items` | object（对象数组） | 本页消息列表。 |
| `data.items[].id` | string | 消息 ID。 |
| `data.items[].workspace_id` | string | 消息所属工作区 ID。 |
| `data.items[].conversation_id` | string | 消息所属会话 ID。 |
| `data.items[].task_id` | string | 关联任务 ID；没有关联任务时不返回。 |
| `data.items[].agent_id` | string | 关联智能体 ID；没有关联智能体时不返回。 |
| `data.items[].manifest_id` | string | 关联运行时清单 ID；没有关联清单时不返回。 |
| `data.items[].role` | string | 消息角色。 |
| `data.items[].parts` | object（对象数组） | 消息内容分段。每个元素的字段由消息分段类型决定。 |
| `data.items[].parent_message_id` | string | 父消息 ID；没有父消息时不返回。 |
| `data.items[].seq` | integer | 会话内消息序号。 |
| `data.items[].created_at` | string | 消息创建时间，采用 RFC 3339 格式。 |
| `data.total` | integer | 符合筛选条件的消息总数。 |
| `data.limit` | integer | 本次实际采用的返回数量上限。 |
| `data.offset` | integer | 本次实际采用的偏移量。 |

## 错误响应

```json
{
  "code": 3,
  "message": "会话不存在"
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `2`（`INVALID_ARGUMENT`）
  - 会话 ID、智能体筛选参数或分页参数无效。
  - 检查路径和查询参数。
* - `404`
  - `3`（`NOT_FOUND`）
  - 会话不存在、不可见，或不属于指定的智能体范围。
  - 确认会话 ID 和智能体筛选条件。
* - `500`
  - `1`（`INTERNAL`）
  - 服务端无法查询消息或生成消息展示数据。
  - 记录请求时间和错误信息后重试。
* - `503`
  - `15`（`UNAVAILABLE`）
  - 会话服务暂不可用。
  - 稍后重试。
```

## 后续操作

使用[查询会话详情](get-session.md)读取会话的当前展示信息和活动任务关联。