首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >Agent 会话管理怎么做?EdgeOne Makers context.store 的消息历史与上下文持久化

Agent 会话管理怎么做?EdgeOne Makers context.store 的消息历史与上下文持久化

原创
作者头像
克劳德2048
发布于 2026-11-12 20:58:20
发布于 2026-11-12 20:58:20
1420
举报

摘要: EdgeOne Makers 的 context.store 提供零配置的 Agent 会话管理,数据落到平台 Blob 存储实现跨实例持久化。本文说明消息历史与会话上下文两类持久化的区别、conversation_id 的注入方式、五种框架的接入入口,以及 state 状态存储与断点续跑做法。

做 Agent 会话管理最容易踩的坑是只做了一半:只写消息历史,前端能看到记录但模型每轮失忆;只接会话上下文,模型记得住但前端一刷新聊天记录空白。这两类持久化在 EdgeOne Makers 的 context.store 上互相独立、不能互相替代,多数对话应用两个都要。它们的共同点是跨实例持久化——数据落到平台 Blob 存储,不绑定进程,只要带同一个 conversation_id,换实例也读得回来。

一、为什么 Agent 的会话状态不能放在进程内存里

Agent 运行在按需拉起、随时会被回收、且同一对话的多次请求可能落在不同实例上的环境里。把数据放进程内存会遇到三个绕不开的问题:

前端一刷新聊天记录就没了。 内存里的数据不对前端可见,也不随请求持久化。

换了个实例,模型接不上上一轮,表现为失忆。 同一对话的第二次请求可能落到另一个实例,那个实例的内存里没有上一轮的内容。

需要「等一下再回来」的场景状态会丢。 审批流、人工介入这类流程中断后,实例一旦回收,中断时的运行状态就没了。

context.store 是 EdgeOne Makers Agent 内置的会话管理能力,零配置即可保存与读取对话历史,底层基于平台 Blob 存储,不需要自己管理任何外部数据库或缓存。

跨实例持久化自 EdgeOne CLI 1.6.26 起支持,使用前升级 CLI:

代码语言:bash
复制
npm i -g edgeone@latest

二、消息历史与会话上下文的区别

这是理解 context.store 的关键,两者各管一摊:

存哪种

管什么

怎么存

消息历史

前端刷新后聊天记录还在、能重新渲染,侧边栏能列历史会话

通用 API appendMessage / getMessages,纯读写、不调模型

会话上下文

模型记得上一轮说了什么(多轮连续对话)、中断能续跑

交给框架原生适配器,框架按自己的格式读写

一句话区分:消息历史管「刷新后看得见」,会话上下文管「模型记得住」。 两者都是跨实例持久化的,但格式与用途不同——框架的 session 格式不是给前端渲染用的。

三、conversation_id 从哪里来

所有跨实例持久化都以 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/ 两类目录的代码中指向同一份数据,入口名不同:

目录

使用入口

典型用途

agents/

context.store

LLM 对话主路径,追加消息、Checkpointer

cloud-functions/

context.agent.store

对话列表 API、消息查询

这个设计的实际价值是:对话主流程在 Agent 里跑,而给前端用的「历史会话列表」「某条对话详情」这类查询接口可以放在 Cloud Functions 里,两边读的是同一份数据,不需要再加一层同步。

五、五种框架的接入入口

context.store 同时提供框架原生适配器和通用 API:

framework

推荐用法

入口(TypeScript)

claude-agent-sdk

框架原生 SessionStore

context.store.claudeSessionStore()

openai-agents-sdk

框架原生 Session

context.store.openaiSession(sessionId)

langgraph

框架原生 Checkpointer + BaseStore

context.store.langgraphCheckpointer / .langgraphStore

deepagents

复用 LangGraph 两个适配器

context.store.langgraphCheckpointer / .langgraphStore

crewai

暂不支持原生适配,用通用 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:

代码语言:typescript
复制
// 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 为依据自动恢复会话:

代码语言:typescript
复制
const session = context.store.openaiSession(context.conversation_id)
代码语言:python
复制
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 暂未支持按语义检索:

代码语言:typescript
复制
const checkpointer = context.store.langgraphCheckpointer
const store = context.store.langgraphStore

六、消息历史的通用 API

围绕消息的读写方法全部挂在 context.store 上:

Node 方法

Python 方法

描述

appendMessage

append_message

追加一条消息,对话不存在时自动创建

getMessages

get_messages

拉消息列表,支持游标分页

updateMessage

update_message

覆盖式更新指定消息

deleteMessage

delete_message

删除单条消息

clearMessages

clear_messages

清空消息但保留对话元信息

getConversation

get_conversation

取对话元信息

listConversations

list_conversations

列对话,按 lastMessageAt 倒序

updateConversation

update_conversation

更新对话元信息,浅合并

deleteConversation

delete_conversation

删除整个对话,不可恢复

toAnthropicMessages

to_anthropic_messages

转成 Anthropic Messages 格式

toOpenAIInput

to_openai_input

转成 OpenAI Chat Completions 格式

写入一条用户消息:

代码语言:typescript
复制
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;对话不存在不抛异常,返回空列表:

代码语言:typescript
复制
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 端同一套语义,用关键字参数:

代码语言: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:

代码语言:typescript
复制
await context.store.updateConversation({
  conversationId: context.conversation_id,
  metadata: { title: '产品咨询', tag: null },  // 设标题,删 tag
})

七、state:没有原生适配器时怎么办

context.store.state 是一个按对话隔离的 JSON 键值存储,存什么由业务决定。它适合任何框架,尤其是没有原生适配器的 CrewAI,以及需要存业务自定义状态(步骤计数、临时变量、序列化后的框架运行状态)的场景。

conversationId 自动绑定当前对话,方法上不用再传,写入按 conversationId 命名空间隔离。

Node 方法

Python 方法

描述

state.get(key)

state.get(key)

读取,key 不存在返回 null / None

state.set(key, value)

state.set(key, value)

写入,value 必须 JSON 可序列化

state.delete(key)

state.delete(key)

删除该 key

约束:key 为字符串,长度 1~256;value 必须 JSON 可序列化——null、字符串、布尔、有限数字、普通对象、数组。函数、循环引用、NaN、Infinity 会被拒绝。

代码语言:typescript
复制
// 请求开始:读回上一轮状态(没有则 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。

代码语言:typescript
复制
// 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(已摘要到哪条 messageId)

业务侧

决定何时摘要、调模型生成摘要、调 updateConversation 写回

summary 与 summarizedUntil 是约定 key 而非 schema,Store 只把它当任意 JSON 存,换名字也行,前后保持一致即可。

做摘要可以用便宜模型——压缩加保留关键事实不需要主模型那种推理能力。提示词里四条要求不能省:保留关键事实、用户偏好、未完成任务、重要上下文设定;删除寒暄、确认收到、重复内容、工具调用细节;用与最近对话相同的语言书写;控制字数上限。省掉任一条会出现摘要发散、寒暄混入、语言乱跳、越摘越长的问题。

十、数据结构与限制

消息与对话的数据结构:

代码语言:typescript
复制
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 删除。

目录
  • 一、为什么 Agent 的会话状态不能放在进程内存里
  • 二、消息历史与会话上下文的区别
  • 三、conversation_id 从哪里来
  • 四、两类目录里怎么用
  • 五、五种框架的接入入口
  • 六、消息历史的通用 API
  • 七、state:没有原生适配器时怎么办
  • 八、断点续跑:审批流与人工介入怎么实现
  • 九、长对话怎么办:摘要的职责切分
  • 十、数据结构与限制
  • 总结
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档