管理 Session

Agent 默认持久化 Session（persistSession 默认 true）。创建时传入 sessionId 可指定 ID，使用 resume 恢复已有会话，或使用 continue: true 继续最近一次会话。

Session 选项

选项	类型	默认值	说明
`sessionId`	`string`	自动生成	显式 Session ID
`resume`	`string`	—	按 ID 恢复 Session
`continue`	`boolean`	`false`	继续最近一次 Session
`persistSession`	`boolean`	`true`	将 Session 持久化到磁盘
`maxSessionQueries`	`number`	—	纳入 LLM 上下文的最大查询数；更早的查询触发减半压缩

常用操作

API	用途
`listSessions()`	列出持久化 Session
`forkSession(id)`	从已有 Session 分叉
`agent.clear()`	重置当前会话
`agent.getMessageHistory()`	读取 engine 的持久历史（压缩后视图）
`agent.getMessageLog()`	读取所有已发出消息的追加式审计日志

压缩历史

上下文增长时调用 agent.compact()；流式版本 agent.compactStream() 会发出 compact 事件并持久化 Session。两个独立选项控制最近尾部保留多少：

选项	默认值	含义
`protectedQueries`	`4`	逐字保留的最近用户查询数（头部摘要、尾部保留）
`toolProtectedQueries`	`2`	尾部中保留完整 `tool_result` 内容的查询数；更早的尾部结果会被清空

将 toolProtectedQueries 设为不小于尾部大小可完全禁用 tool result 裁剪。省略参数时保留历史默认值（逐字保留 4 个查询，其中最近 2 个保留完整 tool result）。不经过 Agent 时，compactSessionStream(opts) / compactSession(opts) 可按 sessionId 直接压缩持久化 Session，并原子化写入消息、摘要与 token 计数；宿主持有自定义存储时则使用 compactMessagesStream() / compactMessages()，并将返回的 messages 与 state 一起持久化。完整的压缩入口与行为变化见 API Reference。

跨请求并发访问同一 Session 时，宿主应用负责加锁。