<span id="管理会话记录与消息"></span>

# Manage persisted conversations and messages

Read and maintain workspace sessions visible to the current identity. Numeric session and message IDs belong to this service and differ from Agent A2A task/context IDs. For invocation, see [Agent tasks and sessions](agents/agent-invocation-sessions.md).

<span id="查询与读取"></span>

## List and read

Configure credentials using [API call basics](../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"
```

Select a conversation ID from `data.sessions`, save it as `SESSION_ID`, and paginate using `data.total`. Use `source`, `keyword`, and `tag` to filter.

```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"
```

Messages return in `data.messages`. Check session ownership, numeric roles, status, and content. Lists use `after` and `limit`. Set the next `after` to the previous page's last message `id`, continuing until an empty array. `data.total` counts messages matching role/status filters, not remaining messages after the cursor.

<span id="维护操作"></span>

## Maintenance

| Method and path | Input or result |
| --- | --- |
| `GET /workspaces/{workspace_id}/llm/sessions/{session_id}` | Read session details. |
| `PUT /workspaces/{workspace_id}/llm/sessions/{session_id}` | JSON such as `{"title":"新标题","expected_title":"原标题"}`. Updates only if the original title matches; otherwise returns the current conversation. |
| `DELETE /workspaces/{workspace_id}/llm/sessions/{session_id}` | Preserve needed messages first, then inspect the list afterward. |
| `POST /workspaces/{workspace_id}/llm/sessions/{session_id}/messages` | Save a message record; this does not invoke model generation. |

Omitting `expected_title` or setting it to `null` disables the title condition. A mismatch can still return HTTP 200; compare the returned title to confirm whether the update took effect. Only nonempty `title` and `config` strings are updated; omission, `null` and empty strings preserve existing values.

Maintain message responses separately from model regeneration. Numeric IDs come from the same conversation service, not display names. For call sequences, see the SDK guide [Manage Conversation Records](../../sdk/ai-studio/会话记录.md) and the CLI guide [Agents, Conversations, and Automations](../../cli/tasks/agents.md#cli-conversation-update).
