会话状态概览-函数计算(FC)-阿里云帮助中心

为什么需要会话状态持久化

Agent 的核心能力在于为无状态大语言模型提供有状态的上下文管理。无论使用哪种 Agent 框架，持久化会话状态都是构建生产级 Agent 的关键一步。

AgentRun 会话状态提供了统一的持久化方案：通过 SessionStore 连接阿里云表格存储 Tablestore（OTS），为主流 Agent 框架提供开箱即用的状态持久化适配器，无需修改任何 Agent 逻辑。

什么是会话状态

会话状态是 Agent 在与用户交互过程中产生和维护的上下文信息，包括：

对话历史：用户消息、Agent 回复、工具调用记录等完整的交互轨迹。
执行状态：Agent 当前所处的流程节点、已完成的步骤、待处理的任务。
业务数据：用户偏好、累计统计、跨会话共享的配置等结构化信息。

默认情况下，这些状态仅存在于进程内存中。一旦服务重启、实例扩缩容或请求被路由到不同实例，状态将全部丢失。通过会话状态持久化，这些信息被写入表格存储 Tablestore（OTS），Agent 能够跨请求、跨实例、跨重启地恢复上下文。

典型应用场景

场景	说明
多轮对话	用户与 Agent 连续对话时，Agent 需要记住之前的内容才能给出连贯的回答
服务重启恢复	应用更新部署后，用户打开之前的对话仍能无缝继续，无需重新开始
多实例共享	在弹性伸缩环境下，用户的请求可能被路由到任意实例，所有实例都能访问同一份会话状态
会话列表与检索	产品侧展示用户的历史会话列表，支持按关键词搜索、按时间筛选
长周期任务	Agent 执行耗时较长的任务（如数据分析、多步骤工作流），中途中断后可从最近的状态恢复继续执行

不适用场景

以下场景无需使用会话状态持久化：

单机本地开发测试：单进程运行、无需跨实例或重启恢复的开发调试阶段，使用框架默认的内存存储即可。
无状态单次问答：用户与 Agent 之间仅单次交互、无需上下文关联的简单问答场景。

前提条件

在使用会话状态功能前，需要完成以下准备工作：

已创建表格存储（OTS）类型的记忆存储实例。如尚未创建，请参见创建和管理记忆存储。
已在记忆存储实例中开启会话状态功能。开启后不可关闭。
已设置环境变量 MEMORY_COLLECTION_NAME 为已创建的记忆存储名称。

会话状态持久化使用表格存储 Tablestore，将按 Tablestore 计费标准产生费用。

核心概念

概念	说明
SessionStore	会话状态的核心入口。通过 `SessionStore.from_memory_collection()` 初始化，自动获取 OTS 连接信息并构建客户端。
适配器	针对各 Agent 框架的持久化实现，将框架原生的状态机制桥接到 OTS 存储。每种框架对应一个适配器。

各框架的会话状态

不同 Agent 框架有各自的状态管理机制，AgentRun 为每种机制提供对应的适配器：

框架	状态机制	AgentRun 适配器	持久化内容	初始化方法
LangChain	ChatMessageHistory（消息历史）	OTSChatMessageHistory	每条消息独立持久化，支持多轮对话回溯	`init_langchain_tables()`
LangGraph	Checkpoint（状态快照）	OTSCheckpointSaver	Graph 执行的完整状态快照，包含所有 channel 值	`init_langgraph_tables()`
Google ADK（Agent Development Kit）	SessionService（会话服务）	OTSSessionService	完整事件流 + App/User/Session 三级 State	`init_adk_tables()`

控制台管理会话状态

统一导航路径：登录 AgentRun 控制台 → 在左侧导航栏，选择记忆 → 点击目标记忆存储名称，进入详情页。在详情页中开启会话状态功能后，可以查看、筛选、删除会话状态记录，以及查看代码集成示例。

开启会话状态

登录 AgentRun 控制台，在左侧导航栏，选择记忆，进入记忆存储列表页，点击目标记忆存储名称，进入详情页。
在概览页签中，找到「会话状态」卡片，点击右侧开关将其开启。
开启时系统弹出 确认开启会话状态 对话框，单击 确认开启 完成操作。开启后不可关闭。

MemoryCollection 开启会话状态后不可关闭，计费详见OTS按量付费。

查看会话状态列表

登录 AgentRun 控制台，在左侧导航栏，选择记忆，进入记忆存储列表页，点击目标记忆存储名称，进入详情页。
切换到 会话状态 页签，展示所有会话状态的 Key-Value 列表。每条记录包含：
- 状态 Key：主显示文本，截断显示，悬浮可查看完整值。
- Value 预览：截断至 100 字符。
- 元信息：Session ID、User ID、Agent ID、创建时间、更新时间。

列表支持分页控件，可选每页显示 10、20 或 50 条，并显示总条数信息。

高级筛选

进入记忆存储详情页并切换到会话状态页签后，可以使用搜索和高级筛选功能，方便快速定位目标记录：

搜索：列表顶部提供搜索框，可按状态 Key 进行关键词搜索。
高级筛选：点击「高级筛选」展开筛选面板，支持以下维度组合筛选：
- Agent ID：按 Agent 标识筛选。
- 用户 ID（User ID）：按用户标识筛选。
- Session ID：按会话标识筛选。

查看详情

进入记忆存储详情页并切换到会话状态页签后，可以查看单条状态的详细信息。

在会话状态列表中，点击某条记录。

右侧滑出详情抽屉，展示以下信息：

字段	说明	格式
Key	状态 Key	完整文本
Session ID	会话标识	截断显示
User ID	用户标识	截断显示
Agent ID	Agent 标识	截断显示
创建时间	状态创建时间戳	格式化时间（纳秒精度）
更新时间	状态最后更新时间戳	格式化时间（纳秒精度）
元数据	状态 Value 的完整内容	JSON 格式

删除会话状态

进入记忆存储详情页并切换到会话状态页签后，可以删除单条或批量删除会话状态记录。

单条删除

在列表中，点击某条记录的删除按钮。
在确认对话框中，点击「确认删除」。

批量删除

在列表中，通过复选框勾选多条记录（或点击「全选」）。
列表上方出现「批量删除」按钮，点击该按钮。
在确认对话框中，点击「确认删除」。

删除操作不可恢复，请谨慎操作。

代码集成

进入记忆存储详情页并切换到会话状态页签后，可以查看代码集成示例。

在 会话状态 Tab 中，切换到 代码集成 子 Tab。
页面展示 Python 代码示例，演示如何通过各 Agent 框架（LangChain / LangGraph / Google ADK）结合 AgentRun 实现会话状态自动持久化。
代码示例中的 MEMORY_COLLECTION_NAME 环境变量会自动填充当前记忆存储名称。

验证会话状态已生效

开启会话状态后，可通过以下方式确认功能是否正常生效：

在控制台的 会话状态 页签中，发送一次 Agent 对话请求后刷新页面，查看是否出现新的状态记录。
通过代码调用适配器（如 OTSChatMessageHistory）完成一次对话后，在控制台确认对应的状态 Key 已写入。

异常处理

使用会话状态功能时，可能遇到以下常见异常：

异常场景	可能原因	处理方法
OTS 连接失败	记忆存储配置中的 endpoint 或 instance_name 不正确，或网络不通。	检查记忆存储配置中的 Tablestore 连接信息是否正确，确认网络连通性（VPC 内访问需使用 VPC Endpoint）。
表不存在	未调用 init 方法初始化数据库表。	在应用启动时调用对应框架的初始化方法（如 `init_langchain_tables()`），该方法是幂等的，可安全重复调用。
权限不足（AccessDenied）	RAM 角色缺少 Tablestore 访问权限。	检查 RAM 角色（如 AliyunAgentRunDefaultRole）是否已授予 Tablestore 读写权限，确认角色信任策略包含 AgentRun 服务。

使用指南

根据使用的框架，参阅对应的详细文档：

LangChain 会话状态：通过 OTSChatMessageHistory 持久化消息历史，适配 RunnableWithMessageHistory 等 LangChain 原生接口。参考：在LangChain中使用会话状态。
LangGraph 会话状态：通过 OTSCheckpointSaver 持久化 Graph checkpoint，同一 thread_id 自动恢复执行状态。参考：在LangGraph中使用会话状态。
Google ADK 会话状态：通过 OTSSessionService 持久化会话事件流和三级 State，完整适配 ADK 的 Runner 机制。参考：在Google ADK中使用会话状态。