Agent/gateway/docs/core/conversations.md

Conversations（对话管理）

模块： gateway/core/conversations/

文档维护规范

1. 先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
2. 文档分层，链接代码 - 关键实现需标注代码文件路径；格式：module/file.py:function_name
3. 简洁快照，日志分离 - 只记录已确认的设计

---

模块职责

对话管理，包括：

• 对话管理：管理用户和 Agent 的对话
• 消息历史存储：存储和查询消息历史
• 消息队列和调度：管理消息队列，调度 Agent 执行

---

核心概念

Conversation（对话）

• 定义：一个用户和一个 Agent 的永久对话
• 特点：
  • 每个对话有独立的消息历史
  • 对话是永久的
  • 对话 ID 格式：conversation:{trace_id}:{user_id}

消息历史

• 每个对话的消息按时间顺序存储
• 包含用户消息和 Agent 回复
• 支持查询历史消息

消息队列

• 管理待处理的消息
• 支持消息调度
• 防止并发冲突

---

模块结构

gateway/core/conversations/
├── conversation_manager.py  # 对话管理
├── message_store.py         # 消息历史存储
└── message_queue.py         # 消息队列和调度

---

关键功能

对话管理

实现位置： gateway/core/conversations/conversation_manager.py

职责：

• 创建对话
• 查询对话信息
• 列出所有对话

消息历史存储

实现位置： gateway/core/conversations/message_store.py

职责：

• 存储消息
• 查询消息历史
• 消息持久化

消息队列和调度

实现位置： gateway/core/conversations/message_queue.py

职责：

• 消息入队
• 消息调度
• 调用 Agent 执行

---

两种 Agent 类型的对话管理

个人助理型 Agent

• 每个用户有独立的 Trace
• 每个用户有独立的对话
• 对话 ID：conversation:trace-alice-001:user_alice

数字员工型 Agent

• 所有用户共享一个 Trace
• 每个用户有独立的对话
• 对话 ID：conversation:trace-receptionist:user_alice
• Agent 可以查看所有对话的消息历史

---

相关文档

• 需求规划：对话管理需求
• 架构设计：模块在整体架构中的位置
• 两种 Agent 类型：详细说明