
摘要: EdgeOne Makers 的 context.store 提供零配置的 Agent 会话管理,数据落到平台 Blob 存储实现跨实例持久化。本文说明消息历史与会话上下文两类持久化的区别、conversation_id 的注入方式、五种框架的接入入口,以及 state 状态存储与断点续跑做法。
做 Agent 会话管理最容易踩的坑是只做了一半:只写消息历史,前端能看到记录但模型每轮失忆;只接会话上下文,模型记得住但前端一刷新聊天记录空白。这两类持久化在 EdgeOne Makers 的 context.store 上互相独立、不能互相替代,多数对话应用两个都要。它们的共同点是跨实例持久化——数据落到平台 Blob 存储,不绑定进程,只要带同一个 conversation_id,换实例也读得回来。
Agent 运行在按需拉起、随时会被回收、且同一对话的多次请求可能落在不同实例上的环境里。把数据放进程内存会遇到三个绕不开的问题:
前端一刷新聊天记录就没了。 内存里的数据不对前端可见,也不随请求持久化。
换了个实例,模型接不上上一轮,表现为失忆。 同一对话的第二次请求可能落到另一个实例,那个实例的内存里没有上一轮的内容。
需要「等一下再回来」的场景状态会丢。 审批流、人工介入这类流程中断后,实例一旦回收,中断时的运行状态就没了。
context.store 是 EdgeOne Makers Agent 内置的会话管理能力,零配置即可保存与读取对话历史,底层基于平台 Blob 存储,不需要自己管理任何外部数据库或缓存。
跨实例持久化自 EdgeOne CLI 1.6.26 起支持,使用前升级 CLI:
npm i -g edgeone@latest这是理解 context.store 的关键,两者各管一摊:
存哪种 | 管什么 | 怎么存 |
|---|---|---|
消息历史 | 前端刷新后聊天记录还在、能重新渲染,侧边栏能列历史会话 | 通用 API |
会话上下文 | 模型记得上一轮说了什么(多轮连续对话)、中断能续跑 | 交给框架原生适配器,框架按自己的格式读写 |
一句话区分:消息历史管「刷新后看得见」,会话上下文管「模型记得住」。 两者都是跨实例持久化的,但格式与用途不同——框架的 session 格式不是给前端渲染用的。
所有跨实例持久化都以 conversation_id 作为 key,不需要自己解析。
平台从请求头 makers-conversation-id 解析后注入 context.conversation_id,并在响应头回显 makers-conversation-id 和 makers-run-id。直接取 context.conversation_id 用即可,不要自己从请求体里另拼一个。 作为存储 key 时,对话 ID 长度上限 256 字符。
store 在 agents/ 与 cloud-functions/ 两类目录的代码中指向同一份数据,入口名不同:
目录 | 使用入口 | 典型用途 |
|---|---|---|
|
| LLM 对话主路径,追加消息、Checkpointer |
|
| 对话列表 API、消息查询 |
这个设计的实际价值是:对话主流程在 Agent 里跑,而给前端用的「历史会话列表」「某条对话详情」这类查询接口可以放在 Cloud Functions 里,两边读的是同一份数据,不需要再加一层同步。
context.store 同时提供框架原生适配器和通用 API:
framework | 推荐用法 | 入口(TypeScript) |
|---|---|---|
| 框架原生 SessionStore |
|
| 框架原生 Session |
|
| 框架原生 Checkpointer + BaseStore |
|
| 复用 LangGraph 两个适配器 |
|
| 暂不支持原生适配,用通用 API 自管 | 见第七节 |
Node 与 Python 两端 API 完全镜像,JavaScript 用 camelCase,Python 用 snake_case。
Claude Agent SDK 的一个必知细节:它的 sessionId 必须是合法 UUID。如果业务侧的 conversation_id 不保证是 UUID(比如 chat-2026-08-12-abc),用 claudeSessionBinding 做映射——本身是 UUID 就原样返回,不是就生成一个并持久化映射,同一个 conversation_id 每次都换回同一个 sessionId:
// agents/chat/index.ts
const conversationId = context.conversation_id ?? ''
const sessionStore = context.store.claudeSessionStore()
// 把任意业务 ID 映射成稳定的 UUID sessionId
const sessionId = await context.store.claudeSessionBinding(conversationId)
// 判断这个 sessionId 之前有没有落过盘:有就 resume 续上,没有就当新会话
// dir 不能省——SessionStore 的 blob key 按项目目录派生
const info = await getSessionInfo(sessionId, { dir: process.cwd(), sessionStore })
const options: Record<string, any> = { model, systemPrompt, sessionStore }
if (info) {
options.resume = sessionId // 恢复已有会话
} else {
options.sessionId = sessionId // 新建会话
}OpenAI Agents SDK 的接入最简洁,会以 conversation id 为依据自动恢复会话:
const session = context.store.openaiSession(context.conversation_id)session = context.store.openai_session(context.conversation_id)LangGraph 与 DeepAgents 用同一组适配器。langgraphCheckpointer 实现 BaseCheckpointSaver(getTuple / list / put / putWrites),langgraphStore 实现 BaseStore(get / put / search / listNamespaces / batch)。需要注意 BaseStore 的 search 暂未支持按语义检索:
const checkpointer = context.store.langgraphCheckpointer
const store = context.store.langgraphStore围绕消息的读写方法全部挂在 context.store 上:
Node 方法 | Python 方法 | 描述 |
|---|---|---|
|
| 追加一条消息,对话不存在时自动创建 |
|
| 拉消息列表,支持游标分页 |
|
| 覆盖式更新指定消息 |
|
| 删除单条消息 |
|
| 清空消息但保留对话元信息 |
|
| 取对话元信息 |
|
| 列对话,按 lastMessageAt 倒序 |
|
| 更新对话元信息,浅合并 |
|
| 删除整个对话,不可恢复 |
|
| 转成 Anthropic Messages 格式 |
|
| 转成 OpenAI Chat Completions 格式 |
写入一条用户消息:
const messageId = await context.store.appendMessage({
conversationId: context.conversation_id,
role: 'user',
content: context.request.body.message,
userId: context.request.body.userId,
metadata: { source: 'web' },
})读出历史并直接喂给模型。getMessages 默认按时间正序(order='asc',最早优先),方便直接拼 prompt;对话不存在不抛异常,返回空列表:
const messages = await context.store.getMessages({
conversationId: context.conversation_id,
limit: 50,
})
const reply = await openai.chat.completions.create({
model: 'gpt-4o',
messages: context.store.toOpenAIInput(messages),
})Python 端同一套语义,用关键字参数:
messages = await context.store.get_messages(
conversation_id=context.conversation_id,
limit=50,
)
reply = await openai_client.chat.completions.create(
model="gpt-4o",
messages=context.store.to_openai_input(messages),
)两个容易混淆的方法差别:clearMessages 清空消息但保留 ConversationMeta,deleteConversation 删除整个对话并同步清理消息索引、会话元信息和全局会话索引,不可恢复。
updateConversation 是浅合并语义——同 key 覆盖、不同 key 保留,传 null 表示删除该 key:
await context.store.updateConversation({
conversationId: context.conversation_id,
metadata: { title: '产品咨询', tag: null }, // 设标题,删 tag
})context.store.state 是一个按对话隔离的 JSON 键值存储,存什么由业务决定。它适合任何框架,尤其是没有原生适配器的 CrewAI,以及需要存业务自定义状态(步骤计数、临时变量、序列化后的框架运行状态)的场景。
conversationId 自动绑定当前对话,方法上不用再传,写入按 conversationId 命名空间隔离。
Node 方法 | Python 方法 | 描述 |
|---|---|---|
|
| 读取,key 不存在返回 null / None |
|
| 写入,value 必须 JSON 可序列化 |
|
| 删除该 key |
约束:key 为字符串,长度 1~256;value 必须 JSON 可序列化——null、字符串、布尔、有限数字、普通对象、数组。函数、循环引用、NaN、Infinity 会被拒绝。
// 请求开始:读回上一轮状态(没有则 null)
const saved = await context.store.state.get<MyState>('session')
// ... 跑一轮对话 ...
// 请求结束:把最新状态存回去
await context.store.state.set('session', latestState)CrewAI 的处理方式:CrewAI 自带 Memory 强依赖向量库(默认 LanceDB + embedder),context.store 暂时未建向量层,对话历史用通用 API 自管即可,多角色编排、任务链、工具调用等核心能力不受影响。需要跨实例恢复会话时,每轮结束把框架的会话状态序列化成 JSON 存进 state,下一轮开始先读回来还原。
典型场景是工具调用需要人工批准。关键认知是:openaiSession 只持久化对话上下文,不持久化中断时的 RunState。中断态必须自己存进 state。
// agents/hitl/index.ts
import { RunState, run } from '@openai/agents'
const RUN_STATE_KEY = 'openai.run-state'
// —— 首轮:跑起来,如果中断就把 RunState 存进 state ——
const result = await run(agent, message, { signal })
if (result.state.getInterruptions().length > 0) {
await context.store.state.set(RUN_STATE_KEY, result.state.toString())
return json({ status: 'awaiting_approval' })
}
await context.store.state.delete(RUN_STATE_KEY) // 没中断,跑完了,清掉
// —— 下一轮:带批准或拒绝进来,读回 RunState 还原、续跑 ——
const stored = await context.store.state.get<string>(RUN_STATE_KEY)
const state = await RunState.fromString(agent, stored) // 还原中断态
const [approval] = state.getInterruptions()
body.approved ? state.approve(approval) : state.reject(approval)
const resumed = await run(agent, state, { signal }) // 从断点续跑这套做法不依赖特定框架:只要状态能表达成可 JSON 序列化的对象,任何框架都能实现跨实例的多轮记忆和断点续跑。序列化的状态始终只留在服务端,前端只发消息和「批准 / 拒绝」的决定。
getMessages 单次最多取 100 条。长对话下的推荐做法是保留最近 N 条原文加上早期内容压成一段摘要,每次请求时从 Store 拼装回 prompt。
Store 本身不调 LLM、不生成摘要,只提供 ConversationMeta.metadata 这个 JSON 容器。职责切分如下:
谁 | 负责什么 |
|---|---|
Store | 提供 metadata JSON 字段与浅合并写入,约定两个 key: |
业务侧 | 决定何时摘要、调模型生成摘要、调 |
summary 与 summarizedUntil 是约定 key 而非 schema,Store 只把它当任意 JSON 存,换名字也行,前后保持一致即可。
做摘要可以用便宜模型——压缩加保留关键事实不需要主模型那种推理能力。提示词里四条要求不能省:保留关键事实、用户偏好、未完成任务、重要上下文设定;删除寒暄、确认收到、重复内容、工具调用细节;用与最近对话相同的语言书写;控制字数上限。省掉任一条会出现摘要发散、寒暄混入、语言乱跳、越摘越长的问题。
消息与对话的数据结构:
interface Message {
messageId: string // msg_xxx(appendMessage 自动生成)
role: 'user' | 'assistant' | 'system' | 'tool'
content: any // string / array / object(多模态)
createdAt: number // ms 时间戳
metadata?: Record<string, any>
updatedAt?: number // 仅 updateMessage 后存在
}
interface ConversationMeta {
conversationId: string
createdAt: number
lastMessageAt: number
messageCount: number
metadata?: Record<string, any>
}限制与超限行为:
项 | 默认 | 超限行为 |
|---|---|---|
conversation_id 长度 | ≤ 256 字符 | 抛 MemoryValidationError |
单条 content 大小 | ≤ 50MB(序列化后) | 抛 MemoryValidationError |
单对话最大消息数 | 10000 | 抛 MemoryQuotaExceededError |
limit 取值范围 | 1~100 | 抛 MemoryValidationError |
单条 content 超大的情况(长文档、图片原始数据)建议放对象存储,消息里只传 URL。
context.store 的使用路径可以归纳成四步:从 context.conversation_id 取对话身份;用 appendMessage / getMessages 维护给前端看的消息历史;用框架原生适配器维护给模型看的会话上下文;需要断点续跑或框架无原生适配时,把可 JSON 序列化的状态存进 state。
三个最容易出错的点:只做了消息历史没接会话上下文导致模型失忆;Claude SDK 没做 UUID 映射导致 sessionId 不合法;以为 openaiSession 会保存中断态而漏存 RunState。
产品完整能力与控制台入口见 EdgeOne Makers 产品页:https://cloud.tencent.com/product/makers
当前首购特惠 EdgeOne Makers 专业版 Pro 套餐 39 元/月,具体以活动页实际展示为准:https://cloud.tencent.com/act/pro/makers-pro
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。