200 lines
5.2 KiB
Markdown
200 lines
5.2 KiB
Markdown
# ReAct 循环分离设计
|
||
|
||
**日期**: 2026-05-08
|
||
**状态**: 已批准
|
||
**目标**: 将 "fat node" 中的 ReAct 循环拆分为独立的 agent/tools 图节点
|
||
|
||
---
|
||
|
||
## 1. 目标
|
||
|
||
将当前 `agent.py` 中的"厚节点"（包含完整 while 循环、工具执行、循环检测）重构为标准 LangGraph 图架构：
|
||
- **推理节点 (agent)**：只负责单步 LLM 调用
|
||
- **工具节点 (tools)**：只负责执行工具
|
||
- **条件边**：控制循环逻辑
|
||
- **finalize 节点**：轻量后处理
|
||
|
||
---
|
||
|
||
## 2. 新图结构
|
||
|
||
```
|
||
START
|
||
│
|
||
▼
|
||
init_state ──→ memory_trigger ──→ agent ──┬──→ (条件边) ──→ tools ──→ agent (循环)
|
||
│ │ ▲
|
||
│ └──────────────┘
|
||
│ (无工具调用时)
|
||
▼
|
||
finalize
|
||
│
|
||
▼
|
||
END
|
||
```
|
||
|
||
### 节点职责
|
||
|
||
| 节点 | 职责 | 输入 | 输出 |
|
||
|------|------|------|------|
|
||
| `init_state` | 初始化状态，重置步数 | 无 | `{current_step: 0, max_steps: N}` |
|
||
| `memory_trigger` | 检测记忆指令，触发 Mem0 存储 | AgentState | 无修改 |
|
||
| `agent` | 单步 LLM 调用，输出 AIMessage | AgentState | `{messages: [AIMessage], ...}` |
|
||
| `tools` | 执行 tool_calls，返回 ToolMessage | AgentState | `{messages: [ToolMessage], current_step: N+1, ...}` |
|
||
| `finalize` | 轻量后处理 | AgentState | `{final_reply: str, metadata: {...}}` |
|
||
|
||
---
|
||
|
||
## 3. 状态定义
|
||
|
||
在 `AgentState` 中新增字段：
|
||
|
||
```python
|
||
@dataclass
|
||
class AgentState:
|
||
# 现有字段保留...
|
||
|
||
# 新增字段
|
||
tool_call_history: List[dict] = field(default_factory=list) # [{"name": "...", "args": {...}}]
|
||
tool_result_history: List[str] = field(default_factory=list) # ["结果1", "结果2", ...]
|
||
stop: bool = False # 手动停止标志
|
||
stop_reason: str = "" # 停止原因
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 节点实现
|
||
|
||
### 4.1 agent 节点
|
||
|
||
**职责**：单步 LLM 调用，不执行工具
|
||
|
||
**流程**：
|
||
1. 步数检查（已达上限则用无工具模型）
|
||
2. 循环检测（检测到异常则设置 `stop=True`）
|
||
3. 调用 LLM（带工具绑定）
|
||
4. 流式推送 token
|
||
|
||
**返回值**：
|
||
```python
|
||
{
|
||
"messages": [AIMessage(content=..., tool_calls=[...])],
|
||
"stop": bool,
|
||
"stop_reason": str,
|
||
"llm_calls": int + 1
|
||
}
|
||
```
|
||
|
||
### 4.2 tools 节点
|
||
|
||
**职责**：执行 `AIMessage.tool_calls`，生成 `ToolMessage`
|
||
|
||
**流程**：
|
||
1. 获取最后一条 `AIMessage`
|
||
2. 提取 `tool_calls` 列表
|
||
3. 遍历执行每个工具
|
||
4. 记录历史（tool_call_history, tool_result_history）
|
||
5. 更新步数 `current_step += 1`
|
||
6. 发送工具开始/结束事件（非 token 流）
|
||
|
||
**返回值**：
|
||
```python
|
||
{
|
||
"messages": [ToolMessage(...), ...],
|
||
"current_step": current_step + 1,
|
||
"tool_call_history": [...],
|
||
"tool_result_history": [...],
|
||
"tools_used": [tool_names] # 新增：记录本轮使用的工具
|
||
}
|
||
```
|
||
|
||
### 4.3 finalize 节点
|
||
|
||
**职责**：轻量后处理
|
||
|
||
**流程**：
|
||
1. 从 `messages` 中提取最后一条 `AIMessage.content` 作为最终回复
|
||
2. 汇总元数据：步数、使用的工具、停止原因
|
||
3. 如果 `final_reply` 为空且有 `stop_reason`，生成说明文本
|
||
|
||
**返回值**：
|
||
```python
|
||
{
|
||
"final_reply": str,
|
||
"metadata": {
|
||
"steps_taken": int,
|
||
"tools_used": List[str],
|
||
"stop_reason": str,
|
||
"llm_calls": int
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.4 条件边
|
||
|
||
```python
|
||
def should_continue(state: AgentState) -> Literal["tools", "finalize"]:
|
||
"""根据 agent 节点输出决定下一步"""
|
||
# 手动停止标志
|
||
if getattr(state, "stop", False):
|
||
return "finalize"
|
||
|
||
# 检查是否有工具调用
|
||
last_msg = state.messages[-1]
|
||
if isinstance(last_msg, AIMessage) and last_msg.tool_calls:
|
||
return "tools"
|
||
|
||
return "finalize"
|
||
```
|
||
|
||
### 4.5 循环回边
|
||
|
||
```
|
||
tools 节点执行完后 → 无条件回到 agent 节点
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 流式事件
|
||
|
||
| 阶段 | 事件类型 | 内容 |
|
||
|------|----------|------|
|
||
| agent | `node_start` | `{"node": "agent"}` |
|
||
| agent | `llm_token` | `{"token": "...", "reasoning_token": "..."}` |
|
||
| agent | `node_end` | `{"node": "agent"}` |
|
||
| tools | `tool_start` | `{"tool": "name", "args": {...}, "id": "..."}` |
|
||
| tools | `tool_end` | `{"tool": "name", "id": "...", "result": "..."}` |
|
||
| finalize | 无 | - |
|
||
|
||
---
|
||
|
||
## 6. 循环检测
|
||
|
||
保留现有 `_should_stop_for_loop` 函数，放在 agent 节点中。
|
||
|
||
**检测逻辑**：连续 2 次调用相同工具 + 参数相似 + 结果相似 → 设置 `stop=True, stop_reason="loop_detected"`
|
||
|
||
---
|
||
|
||
## 7. 文件变更
|
||
|
||
### 新增文件
|
||
- `backend/app/main_graph/nodes/tools.py` — tools 节点实现
|
||
- `backend/app/main_graph/nodes/finalize.py` — finalize 节点实现
|
||
|
||
### 修改文件
|
||
- `backend/app/main_graph/state.py` — 新增状态字段
|
||
- `backend/app/main_graph/main_graph_builder.py` — 重构图构建逻辑
|
||
- `backend/app/main_graph/nodes/agent.py` — 移除 while 循环和工具执行逻辑
|
||
|
||
### 删除
|
||
- 无
|
||
|
||
---
|
||
|
||
## 8. 兼容性
|
||
|
||
- 对外接口（`process_message`, `process_message_stream`）保持不变
|
||
- 返回值格式调整：新增 `metadata` 字段
|
||
- checkpointer 兼容性：新增字段需设置默认值
|