图_6Agent状态管理模块
对应 [[6_代码实现_Agent 状态管理]]。区分数据协议、单次请求状态、跨轮会话存储和 Agent 运行装配。
四块分别解决什么
schemas/chat.py定义合法的数据形状：真实证据、主 / 子 Trace、HITL 恢复和 Chat 会话结果。字段详情留在原文章，不在图里重复列全表。ChatRequestContext隔离一个请求的工具预算、临时 Trace 和事件队列。Tool 写入，Service 读取；请求结束关闭。ConversationStorage维护跨轮消息与 metadata。PG 是持久化来源，Redis 缓存消息和列表；metadata 中的 pending_hitl 不依赖请求 ctx 存活。runtime.py持有共享模型，在每次请求中装配 Agent，并让知识工具绑定正确的 ctx。
重要实现取舍
save() 的真实实现是删除旧消息再重写完整历史，并非只追加一条新消息；会话 metadata 合并保存。load_with_meta() 即使消息缓存命中，也需要读取会话 metadata。原实现的 user_id 参数在存储层按 username 查用户，不能据参数名误画成整数用户主键。
与其他图的关系
[[图_7Agent对话编排模块]] 同时调用 Storage、ctx 和 Runtime；Runtime 装配 [[图_5工具层模块]]；Storage 下接 [[图_1数据存储模块]]。Pipeline 的 RAGState 定义仍在 [[图_4RAG工作流模块]]，不归本文件所有。
图形约定
绿色是目录，蓝色是文件，紫色是类，橙色是函数；标题中的名称与职责之间保留 12 个空格。类框中的编号通常对应其方法；函数框的编号描述内部步骤。没有组合，矩形宽高可分别调整。
导航
[[项目实现|查看项目实现总图]] · [[图_1数据存储模块|数据存储模块]]
Excalidraw Data
Text Elements
06 Agent状态管理模块 · 实现结构 ^2f4f7a87
目录 → 文件 → 类 / 函数；框内编号表示局部职责，箭头表示主要调用。 ^53cbb06d
backend/ 承载本模块的后端代码 ^34c78e94
schemas/ 声明并校验交换数据 ^46b3fcbc
[[6_代码实现_Agent 状态管理#2.1 数据结构实现|chat.py]] 统一 Chat / Trace / HITL 数据协议 ^1347faa3
StrictSchema：Pydantic 基类，extra="forbid"。 下列类只定义 / 校验数据，不直接执行检索或落库。 ^ac52a2cd
RetrievedChunk 规范化一条真实检索证据
- 正文、来源、页码、Chunk 关联 ID 与分数字段 ^f599b0a7
RagTraceFields 定义主 / 子 Trace 共用字段
- 候选与合并、重排、评分、改写、HITL、复杂度信息 ^cb9538cf
RagSubTrace 继承共用字段，表示一个子问题轨迹
- 复用 RagTraceFields 的结构，供父级 Trace 汇总 ^5c5b04f6
RagTrace 表示本轮主问题的完整轨迹
- 继承 RagTraceFields，增加 sub_traces 列表 ^b9eba347
HitlResumeState 校验可跨轮保存的最小恢复快照
- 原问题、route / status、改写次数和复杂度规划信息
- 不含检索全文；恢复时再查知识库 ^0097f53b
PendingHitlState 描述等待用户补充的会话任务
- 追问 ID、原问题、提示 / 选项、已补充答案、创建时间
- 嵌套可选 resume_state，保存到会话 metadata ^cc593f48
normalize_rag_sub_trace() 清理并校验子问题 Trace
- _normalize_trace_fields() 过滤字段；_normalize_chunks() 校验证据 ^d7af0d28
normalize_rag_trace() 统一对外或保存的主 Trace
- 清理主字段与证据，逐个规范化 sub_traces，再做模型校验 ^496d4dcf
同文件其余协议类（此处不展开字段表）： ChatRequest / ChatResponse：问答请求与结果 MessageInfo / SessionMessagesResponse：历史消息 SessionInfo / SessionListResponse：会话摘要与列表 SessionDeleteResponse：删除结果 ^ee627bb9
这些是数据结构；第 8 篇之后的 HTTP 路由尚未纳入。 ^5a058bfc
chat/ 管理请求生命周期、会话历史与模型装配 ^34bddd45
[[6_代码实现_Agent 状态管理#对话上下文数据结构|request_context.py]] 承载本次请求的临时状态 ^2ba4b95d
ChatRequestContext 隔离预算、Trace 和流式事件
- for_sync() / for_stream()：创建同步 / 流式上下文
- reset_knowledge_tool_budget() / acquire_knowledge_tool_slot()：知识工具一次预算
- emit_rag_step()：计算耗时，经事件循环线程安全地推入 Queue
- store_rag_trace()：规范化 Trace，校验并暂存恢复快照
- peek_rag_trace() / take_rag_trace()：查看 / 取走后清空
- close()：停用上下文并释放 Queue / loop 引用 ^e4df9666
存活范围：Service 创建 → Tool / Pipeline 共用 → Service 读取 → finally close()。 RLock 保护共享字段；流式 Queue 只属于本次请求，不负责跨轮持久化。 ^2f553253
[[6_代码实现_Agent 状态管理#2.2 会话存储管理|storage.py]] 把会话与消息保存到关系库并缓存 ^b33e03c4
ConversationStorage 按用户与 session_id 组织会话
- save()：查建会话 → 合并 metadata → 删除旧消息并重写全量历史 → PG 提交
- 提交后刷新 Redis 消息缓存，并失效会话列表缓存
- load()：Redis 命中直接返回；未命中查 PG 并回填
- load_with_meta()：读取消息及 PG 会话 metadata
- list_sessions() / list_session_infos()：缓存优先的会话列表
- get_session_messages()：带 Trace 的历史；delete_session()：删除并清缓存 ^c5873fd4
storage = ConversationStorage()；依赖图 1 的 SessionLocal、ORM 模型与 cache。 metadata 保存 title / persistent_note / pending_hitl；消息附加数据保存 rag_trace。 ^ec5968d0
[[6_代码实现_Agent 状态管理#2.3 Agent Runtime|runtime.py]] 创建共享模型与每请求 Agent ^06ff7ae7
model = init_chat_model(MODEL)：外层回答模型 fast_model = init_chat_model(FAST_MODEL)：记忆摘要模型 SYSTEM_PROMPT：工具使用、证据引用和无知识约束 ^84581867
create_agent_for_request(ctx) 将模型、提示词与工具装配成 Agent
- create_agent(model, tools=[天气工具, make_search_knowledge_base(ctx)])
- 每次请求创建 Agent；知识工具闭包绑定当前 ctx ^217b3f41
四种边界：Schema 是协议；ctx 是本次请求；Storage 是跨轮数据；Runtime 是运行装配。 ^d37b4777
Element Links
1347faa3: [[6_代码实现_Agent 状态管理#2.1 数据结构实现]]
2ba4b95d: [[6_代码实现_Agent 状态管理#对话上下文数据结构]]
b33e03c4: [[6_代码实现_Agent 状态管理#2.2 会话存储管理]]
06ff7ae7: [[6_代码实现_Agent 状态管理#2.3 Agent Runtime]]
%%
Drawing
1 | N4IgLgngDgpiBcIYA8DGBDANgSwCYCd0B3EAGhADcZ8BnbAewDsEAmcm+gV31TkQAswYKDXgB6MSgw4CxAHSp6AWzJJMMJTEZgaCANqg8CECwBmAFlMB2dAA4rqyLGNgUYVcgTmArOQitfECI8MH4EbwBGW3J+GGwAc0EvbzkATgAGTKzsrIA2cnRGePUEdPYwfHoAaxgAYXpMenxjAGIIlgBmdPMHcgAjdFQq+MrORlx6xubECsKaKHR8LXdyU2 |
%%
