# 管理会话记录与消息

读取和维护工作区内当前身份可见的持久化会话。该服务的数值型会话与消息 ID，与智能体 A2A 的任务和上下文 ID 分开；智能体调用见[调用智能体与管理会话](agents/agent-invocation-sessions.md)。

## 查询与读取

按[调用前准备](../api-call-basics.md)配置凭据，然后请求第一页：

```shell
curl "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/llm/sessions?page=1&page_size=20" \
  -H "X-API-Key: $PRODUCT_API_KEY" -H "X-Workspace-ID: $WORKSPACE_ID"
```

从响应的 `data.sessions` 选择会话 ID，保存为 `SESSION_ID`，结合 `data.total` 逐页读取。可使用 `source`、`keyword`、`tag` 筛选。

```shell
curl "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/llm/sessions/$SESSION_ID/messages" \
  -H "X-API-Key: $PRODUCT_API_KEY" -H "X-Workspace-ID: $WORKSPACE_ID"
```

消息返回在 `data.messages` 中。核对其会话归属、数值角色、状态和内容。消息列表使用 `after` 和 `limit`；下一页的 `after` 取上一页最后一条消息的 `id`，直到返回空数组。`data.total` 是符合角色和状态筛选的消息总数，不是游标之后的剩余条数。

## 维护操作

| 方法与路径 | 输入或结果 |
| --- | --- |
| `GET /workspaces/{workspace_id}/llm/sessions/{session_id}` | 读取会话详情。 |
| `PUT /workspaces/{workspace_id}/llm/sessions/{session_id}` | JSON 如 `{"title":"新标题","expected_title":"原标题"}`；仅在原标题匹配时更新，不匹配则返回当前会话。 |
| `DELETE /workspaces/{workspace_id}/llm/sessions/{session_id}` | 删除前保留仍需使用的消息，删除后回查列表。 |
| `POST /workspaces/{workspace_id}/llm/sessions/{session_id}/messages` | 保存会话消息；写入记录不等于调用模型生成回答。 |

`expected_title` 省略或为 `null` 时不检查原标题；标题不匹配仍可返回 HTTP 200，需比较返回标题确认更新是否生效。`title` 和 `config` 只有非空字符串才会更新，省略、`null` 或空字符串都保留原值。

消息响应维护与模型重新生成分别处理。数值 ID 来自同一会话服务，不从显示名称推导。SDK 与 CLI 的调用顺序见 SDK [管理会话记录](../../sdk/ai-studio/会话记录.md) 和 CLI [智能体、会话与自动化](../../cli/tasks/agents.md#cli-conversation-update)。
