副标题基于 LangGraph FastAPI SQLite 的 Agent 后端工程实践本文是《从 0 到 1 构建一个智能旅行 Agent 后端》系列第 3 篇。本文基于规则 Mock Agent当前尚未接入真实 LLM重点讨论 Agent 后端工程设计。摘要在智能旅行 Agent 后端开发中当用户需要同时对比多个方案时简单的字段修改无法满足需求。本文通过一个真实场景——用户想保留悉尼方案同时查看墨尔本版本——探讨为什么不能原地修改 State以及如何通过 Session Fork 机制实现多方案时间线并存。文章详细分析了最初方案的不足、核心问题本质、最终解决方案的设计取舍以及当前实现的边界条件。关键词Session Fork、LangGraph、多方案、Trip、Session、TripState、Agent、后端设计、时间线隔离1. 问题背景从单时间线到多方案并存在前两篇实现了 HITL人在回路和条件路由之后用户已经可以在一条时间线上完成完整的确认流程解析需求 → 确认 → 查看路线候选 → 选中一条。然后遇到了一个非常真实的用户需求。方案 A 已经定稿到路线阶段目的地悉尼 圣灵群岛8 天行程三条 route_options 中用户选中了「东岸线」。用户看着地图说「能不能也看看墨尔本版本悉尼这套我想留着对比。」这不是第 2 篇中讨论的MODIFY操作。MODIFY 是在同一条确认流程里修改草稿或重新生成路线仍然只有一条执行时间线。用户真正需要的是两套方案并存——悉尼版继续可查墨尔本版另开一条线从头确认。Chatbot 可以依靠长对话上下文「假装还记得上周那版悉尼」但旅行规划后端不行前端需要并排展示两个方案后端需要能分别获取两个 Session 的快照而不是在内存中覆盖掉上一份 route_options。核心问题因此变得清晰当用户说「换墨尔本看看」时为什么不能直接修改原来的 State2. 最初方案的局限性我最开始考虑过最省事的做法在同一个 TripState 上修改 destinations 字段清空 route_options重新运行 Requirement Agent 和 Route Planner——相当于「原地换方案」。表面上看很合理字段改了重新生成一遍不就行了吗问题在于修改的不只是几个 Domain 字段还会连带抹掉整条执行时间线上的痕迹。2.1 覆盖关键数据覆盖 route_options 和 selected_route_id。悉尼东岸线、圣灵群岛停留点一起消失用户无法再打开方案 A 查看当时选择了什么。2.2 破坏时间线连续性覆盖 LangGraph Checkpoint。LangGraph Checkpointer 按 thread_id 存储执行进度。同一 thread 上每次 invoke / update都是在同一条时间线上前进。原地改写等于告诉系统「历史上从未存在过悉尼方案」。2.3 丧失对比能力无法比较。产品需要的是「A vs B」对比原地修改只能给出「只有 B」。以后用户说「还是悉尼那版好」系统没有独立的快照可供回溯。对应的测试用例固定了以下行为fork 之后父 Session 的 stage、route_options、需求软偏好都不变。如果采用原地 update父状态会被覆盖这类隔离断言根本写不出来。用户不是在「修改方案」而是在探索新的可能。这两种意图后端结构完全不同。3. 核心问题容器与时间线的分离要把「容器」和「时间线」分开我设计的三层结构是Trip一次旅行容器 └── Session一条方案分支session_id thread_id └── TripState该分支在 LangGraph 里的业务快照3.1 Trip容器层Trip管理索引trip_id、original_user_input、active_session_id当前哪条分支可写、root_session_id。一个 Trip 下可以挂载多个 Session形成 fork 树。3.2 Session分支层Session管理分支元数据session_id、parent_session_id、fork_reason、status。每条 Session 对应 LangGraph 中独立的一条 thread。3.3 TripState状态层TripState是执行态投影requirements、route_options、stage、pending_confirmation 等。它存在于 LangGraph Checkpoint 中由 Checkpointer 按 Session 的 thread 进行读写。关键约定thread_id session_id。fork 不是修改旧 thread而是从 sess_abc123 创建新的 sess_def456LangGraph Checkpoint 天然隔离。这层模型不是第一天就设计好的。是在「原地改方案会覆盖悉尼版」的问题逼出来之后才把 Trip 从「只有一个 State 的对象」升级为「多 Session 容器」。一句话总结Branch 是时间线不是版本号。版本号暗示「同一条线上的第 N 次修订」fork 是 Trip 下并列的多条 Session各自有 LangGraph Checkpoint、各自走确认门。4. 最终解决方案Session Fork 机制fork_session 的核心语义创建子分支不修改父分支不复制父 Checkpoint。4.1 父 Session 处理父 Session保留。父的 LangGraph Checkpoint 仍在原 thread_id 上ROUTE_CONFIRMED、route_options、当时选中的 selected_route_id 全部保留。写权限不跟随 status 走而是跟随 Trip.active_session_id。4.2 子 Session 创建子 Session新 session_id新 thread_id二者相等深拷贝父的 requirements防止后续合并污染父分支清空 route_options、selected_route_idstage 回到 REQUIREMENT_DRAFTpending_confirmation 回到 REQUIREMENTS不复制父的 LangGraph Checkpoint全新启动图Trip.active_session_id 切换到 childfork 完成后子分支通常会再次停在 wait_requirement_confirmation——用户需要在新时间线上重新确认需求再生成墨尔本方向的路线。不能「继承父的 route interrupt 位置直接改一条线」那在语义上是克隆半完成进程不是「另开方案」。4.3 权限模型权限模型可以概括为读任意 Session 写仅 active Session fork任意 Session → 新 child active父保留REQUIREMENT_DRAFT 阶段默认不允许 fork除非 force——避免在需求还没定型时滥开分支路线阶段 fork 是主路径。5. 方案对比与取舍5.1 方案 A原地 update 几个字段为什么考虑最省事不用引入多 Session。为什么放弃覆盖旧方案无法并排对比LangGraph Checkpoint 时间线也被抹掉。5.2 方案 Bversion 字段 / route_stale 标记位为什么考虑看起来能「保留历史」而不开新分支。为什么放弃version 曾存在于早期模型但没有自动递增、没有冲突检测后来已删除。stale 位与「独立 Session 保留完整历史」重复历史方案靠独立时间线不靠标记位。5.3 方案 C复制父 LangGraph Checkpoint为什么考虑省事——子分支继承父的 interrupt 位置和执行进度。为什么放弃用户要「墨尔本新版」子分支却克隆了「悉尼已 confirm 到路线门」的半态变成「克隆正在跑的进程」不是干净的新方案。5.4 方案 D同 thread 内模拟 branch / 切回父分支原地编辑为什么考虑少管几条 thread产品上「改回悉尼版接着写」有吸引力。为什么放弃LangGraph Checkpoint 仍是一条链无法真正隔离。switch_active_session 当前刻意未做——要改历史方案只能从历史 Session 再 fork 一条新线。当前方案接受的代价不能切回父 Session 直接编辑多个 Session 可能同为 ACTIVE status前端必须看 is_active (session_id trip.active_session_id)需要分支列表与权限产品化。父 status 不自动 SUPERSEDED是已知取舍不是疏忽。6. 当前实现边界6.1 已实现功能Session Fork新 session / 新 thread不复制父 LangGraph Checkpoint父分支内容不被覆盖历史 Session 可读、可再 fork仅 active Session 可写messages / confirm深拷贝 requirements子分支清空路线并回到需求草稿6.2 刻意未实现switch_active_session切回历史分支原地编辑父 Session 自动标为 SUPERSEDED持久化写入顺序metadata first将在下一篇中详细讨论。7. 总结第一「换墨尔本看看」不是改几个字段而是新开一条执行时间线。用户在探索新可能不是在同一份草稿上覆盖。第二Branch 是时间线不是版本号。Trip 下并列多条 Session各自有 LangGraph Checkpoint、各自走确认门。第三不复制父 LangGraph Checkpoint、不原地覆盖——换来的是可对比、可再 fork代价是不能切回父分支原地写只能「从历史再 fork」。下一篇预告《为什么 Agent 系统需要双存储Business DB 和 Checkpoint 各管什么》
副标题基于 LangGraph FastAPI SQLite 的 Agent 后端工程实践本文是《从 0 到 1 构建一个智能旅行 Agent 后端》系列第 3 篇。本文基于规则 Mock Agent当前尚未接入真实 LLM重点讨论 Agent 后端工程设计。摘要在智能旅行 Agent 后端开发中当用户需要同时对比多个方案时简单的字段修改无法满足需求。本文通过一个真实场景——用户想保留悉尼方案同时查看墨尔本版本——探讨为什么不能原地修改 State以及如何通过 Session Fork 机制实现多方案时间线并存。文章详细分析了最初方案的不足、核心问题本质、最终解决方案的设计取舍以及当前实现的边界条件。关键词Session Fork、LangGraph、多方案、Trip、Session、TripState、Agent、后端设计、时间线隔离1. 问题背景从单时间线到多方案并存在前两篇实现了 HITL人在回路和条件路由之后用户已经可以在一条时间线上完成完整的确认流程解析需求 → 确认 → 查看路线候选 → 选中一条。然后遇到了一个非常真实的用户需求。方案 A 已经定稿到路线阶段目的地悉尼 圣灵群岛8 天行程三条 route_options 中用户选中了「东岸线」。用户看着地图说「能不能也看看墨尔本版本悉尼这套我想留着对比。」这不是第 2 篇中讨论的MODIFY操作。MODIFY 是在同一条确认流程里修改草稿或重新生成路线仍然只有一条执行时间线。用户真正需要的是两套方案并存——悉尼版继续可查墨尔本版另开一条线从头确认。Chatbot 可以依靠长对话上下文「假装还记得上周那版悉尼」但旅行规划后端不行前端需要并排展示两个方案后端需要能分别获取两个 Session 的快照而不是在内存中覆盖掉上一份 route_options。核心问题因此变得清晰当用户说「换墨尔本看看」时为什么不能直接修改原来的 State2. 最初方案的局限性我最开始考虑过最省事的做法在同一个 TripState 上修改 destinations 字段清空 route_options重新运行 Requirement Agent 和 Route Planner——相当于「原地换方案」。表面上看很合理字段改了重新生成一遍不就行了吗问题在于修改的不只是几个 Domain 字段还会连带抹掉整条执行时间线上的痕迹。2.1 覆盖关键数据覆盖 route_options 和 selected_route_id。悉尼东岸线、圣灵群岛停留点一起消失用户无法再打开方案 A 查看当时选择了什么。2.2 破坏时间线连续性覆盖 LangGraph Checkpoint。LangGraph Checkpointer 按 thread_id 存储执行进度。同一 thread 上每次 invoke / update都是在同一条时间线上前进。原地改写等于告诉系统「历史上从未存在过悉尼方案」。2.3 丧失对比能力无法比较。产品需要的是「A vs B」对比原地修改只能给出「只有 B」。以后用户说「还是悉尼那版好」系统没有独立的快照可供回溯。对应的测试用例固定了以下行为fork 之后父 Session 的 stage、route_options、需求软偏好都不变。如果采用原地 update父状态会被覆盖这类隔离断言根本写不出来。用户不是在「修改方案」而是在探索新的可能。这两种意图后端结构完全不同。3. 核心问题容器与时间线的分离要把「容器」和「时间线」分开我设计的三层结构是Trip一次旅行容器 └── Session一条方案分支session_id thread_id └── TripState该分支在 LangGraph 里的业务快照3.1 Trip容器层Trip管理索引trip_id、original_user_input、active_session_id当前哪条分支可写、root_session_id。一个 Trip 下可以挂载多个 Session形成 fork 树。3.2 Session分支层Session管理分支元数据session_id、parent_session_id、fork_reason、status。每条 Session 对应 LangGraph 中独立的一条 thread。3.3 TripState状态层TripState是执行态投影requirements、route_options、stage、pending_confirmation 等。它存在于 LangGraph Checkpoint 中由 Checkpointer 按 Session 的 thread 进行读写。关键约定thread_id session_id。fork 不是修改旧 thread而是从 sess_abc123 创建新的 sess_def456LangGraph Checkpoint 天然隔离。这层模型不是第一天就设计好的。是在「原地改方案会覆盖悉尼版」的问题逼出来之后才把 Trip 从「只有一个 State 的对象」升级为「多 Session 容器」。一句话总结Branch 是时间线不是版本号。版本号暗示「同一条线上的第 N 次修订」fork 是 Trip 下并列的多条 Session各自有 LangGraph Checkpoint、各自走确认门。4. 最终解决方案Session Fork 机制fork_session 的核心语义创建子分支不修改父分支不复制父 Checkpoint。4.1 父 Session 处理父 Session保留。父的 LangGraph Checkpoint 仍在原 thread_id 上ROUTE_CONFIRMED、route_options、当时选中的 selected_route_id 全部保留。写权限不跟随 status 走而是跟随 Trip.active_session_id。4.2 子 Session 创建子 Session新 session_id新 thread_id二者相等深拷贝父的 requirements防止后续合并污染父分支清空 route_options、selected_route_idstage 回到 REQUIREMENT_DRAFTpending_confirmation 回到 REQUIREMENTS不复制父的 LangGraph Checkpoint全新启动图Trip.active_session_id 切换到 childfork 完成后子分支通常会再次停在 wait_requirement_confirmation——用户需要在新时间线上重新确认需求再生成墨尔本方向的路线。不能「继承父的 route interrupt 位置直接改一条线」那在语义上是克隆半完成进程不是「另开方案」。4.3 权限模型权限模型可以概括为读任意 Session 写仅 active Session fork任意 Session → 新 child active父保留REQUIREMENT_DRAFT 阶段默认不允许 fork除非 force——避免在需求还没定型时滥开分支路线阶段 fork 是主路径。5. 方案对比与取舍5.1 方案 A原地 update 几个字段为什么考虑最省事不用引入多 Session。为什么放弃覆盖旧方案无法并排对比LangGraph Checkpoint 时间线也被抹掉。5.2 方案 Bversion 字段 / route_stale 标记位为什么考虑看起来能「保留历史」而不开新分支。为什么放弃version 曾存在于早期模型但没有自动递增、没有冲突检测后来已删除。stale 位与「独立 Session 保留完整历史」重复历史方案靠独立时间线不靠标记位。5.3 方案 C复制父 LangGraph Checkpoint为什么考虑省事——子分支继承父的 interrupt 位置和执行进度。为什么放弃用户要「墨尔本新版」子分支却克隆了「悉尼已 confirm 到路线门」的半态变成「克隆正在跑的进程」不是干净的新方案。5.4 方案 D同 thread 内模拟 branch / 切回父分支原地编辑为什么考虑少管几条 thread产品上「改回悉尼版接着写」有吸引力。为什么放弃LangGraph Checkpoint 仍是一条链无法真正隔离。switch_active_session 当前刻意未做——要改历史方案只能从历史 Session 再 fork 一条新线。当前方案接受的代价不能切回父 Session 直接编辑多个 Session 可能同为 ACTIVE status前端必须看 is_active (session_id trip.active_session_id)需要分支列表与权限产品化。父 status 不自动 SUPERSEDED是已知取舍不是疏忽。6. 当前实现边界6.1 已实现功能Session Fork新 session / 新 thread不复制父 LangGraph Checkpoint父分支内容不被覆盖历史 Session 可读、可再 fork仅 active Session 可写messages / confirm深拷贝 requirements子分支清空路线并回到需求草稿6.2 刻意未实现switch_active_session切回历史分支原地编辑父 Session 自动标为 SUPERSEDED持久化写入顺序metadata first将在下一篇中详细讨论。7. 总结第一「换墨尔本看看」不是改几个字段而是新开一条执行时间线。用户在探索新可能不是在同一份草稿上覆盖。第二Branch 是时间线不是版本号。Trip 下并列多条 Session各自有 LangGraph Checkpoint、各自走确认门。第三不复制父 LangGraph Checkpoint、不原地覆盖——换来的是可对比、可再 fork代价是不能切回父分支原地写只能「从历史再 fork」。下一篇预告《为什么 Agent 系统需要双存储Business DB 和 Checkpoint 各管什么》
