# 管理会话记录

使用 AI Studio SDK 查询当前身份在工作区内可见的持久化会话与消息，并按条件更新会话标题或删除不再保留的会话。持久化会话使用数值型会话 ID；需要读取智能体运行产生的对话上下文时，请参阅 [读取智能体会话](智能体/管理会话和消息.md#sdk-ai-studio-sessions-s1)。

(sdk-ai-studio-conversation-records-flow)=
## 任务流程

```text
工作区会话服务
    │
    ▼
分页列出持久化会话 ──▶ 选定数值型会话 ID
                          │
                          ├── 读取会话详情与消息列表
                          └── 按条件更新标题或删除会话
```

(sdk-ai-studio-conversation-records-prepare)=
## 准备

1. 已完成 [使用 SDK](../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. 工作区内已有当前身份可访问的持久化会话；目标会话 ID 可从下一步的会话列表结果中选择。

(sdk-ai-studio-conversation-records-read)=
## 查询会话与消息

先按分页参数列出可见会话，再使用目标会话的数值型 ID 读取会话详情与消息列表。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
service = client.conversations(os.environ["WORKSPACE_ID"])

page = service.list_sessions(
    sdk.with_query_param("page", "1"),
    sdk.with_query_param("page_size", "20"),
)
print("Total sessions:", page.total)
for item in page.sessions:
    print(item.id, item.title, item.source)

if not page.sessions:
    raise SystemExit("No persisted sessions found in this workspace")

session_id = page.sessions[0].id
session = service.get_session(session_id)
messages = service.list_messages(
    session_id,
    sdk.with_query_param("limit", "50"),
)
print("Selected session:", session.id, session.title)
for message in messages.messages:
    print(message.id, message.role, message.status, message.content)
```

::::

::::{tab-item} Go
:sync: go

```go
package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	service := client.Conversations(os.Getenv("WORKSPACE_ID"))

	page, err := service.ListSessions(
		ctx,
		sdk.WithQueryParam("page", "1"),
		sdk.WithQueryParam("page_size", "20"),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println("Total sessions:", page.GetTotal())
	for _, item := range page.GetSessions() {
		fmt.Println(item.GetId(), item.GetTitle(), item.GetSource())
	}
	if len(page.GetSessions()) == 0 {
		return
	}

	sessionID := page.GetSessions()[0].GetId()
	session, err := service.GetSession(ctx, sessionID)
	if err != nil {
		panic(err)
	}
	messages, err := service.ListMessages(
		ctx,
		sessionID,
		sdk.WithQueryParam("limit", "50"),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println("Selected session:", session.GetId(), session.GetTitle())
	for _, message := range messages.GetMessages() {
		fmt.Println(message.GetId(), message.GetRole(), message.GetStatus(), message.GetContent())
	}
}
```

::::

:::::

会话列表按页码和每页条数翻页，支持附加来源、关键词或标签筛选条件。消息列表按游标向后翻页：首次查询读取起始页，后续查询通过查询参数 `after` 传入上一页末尾消息的 ID，直至返回空列表；返回的总数表示该会话的消息总量，不随翻页游标递减。

(sdk-ai-studio-conversation-records-maintain)=
## 更新或删除会话

更新会话标题时可传入预期原标题作为条件。若服务端当前标题与预期值不一致，接口会直接返回当前会话而不覆盖标题；调用后比对返回的标题即可确认更新是否生效。传入空字符串的标题或配置不会清空已有值。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
expected_title = session.title
updated = service.update_session(
    session_id,
    sdk.ConversationWorkspaceSessionRequest(
        title="归档会话",
        expected_title=expected_title,
    ),
)
print("Updated title:", updated.title)
```

::::

::::{tab-item} Go
:sync: go

```go
expectedTitle := session.GetTitle()
updated, err := service.UpdateSession(ctx, sessionID, &sdk.ConversationWorkspaceSessionRequest{
	Title:         "归档会话",
	ExpectedTitle: &expectedTitle,
})
if err != nil {
	panic(err)
}
fmt.Println("Updated title:", updated.GetTitle())
```

::::

:::::

确认不再保留某个会话及其消息后，可按同一数值型会话 ID 执行删除，并在删除后重新查询会话列表核对结果。修改已存储的助手回复文本属于会话记录维护操作，不会重新触发模型推理。

(sdk-ai-studio-conversation-records-next)=
## 下一步

- [读取智能体会话](智能体/管理会话和消息.md)
- [重新生成回答](智能体/重新生成智能体回答.md)
