多步推理智能体（规划-执行）

## 概述

多步推理智能体是一种基于“规划‑执行”模式的 Agent。它首先对用户提供的复杂任务进行语义理解与拆解，生成有序的子任务序列；随后按顺序执行每个子任务，并在每个子任务完成后进行验证，以确保结果的正确性和完整性。只有在当前子任务通过验证后，智能体才会进入下一个子任务；若验证失败，则会尝试回溯或重新生成子任务，直至整个任务链完成。

## 适用场景

- **跨领域复杂任务**：如多文档分析、系统设计、数据清洗与建模等，需要多步骤协同完成。
- **高可靠性要求**：对结果有严格验证的场景，例如代码生成与单元测试、金融模型校验。
- **动态规划需求**：在执行过程中需要根据中间结果动态调整计划，如对话式交互、交互式数据分析。
- **长流程自动化**：需要一次性完成数十甚至上百个子任务的工作流，例如大规模 ETL、报告生成。

## 工作原理

1. **任务拆解**：使用大型语言模型（LLM）对原始任务进行语义解析，生成包含目标、约束和依赖关系的子任务列表。
2. **逐步执行**：智能体按顺序调用相应的执行器（可以是脚本、API、插件等）完成每个子任务。
3. **结果验证**：每个子任务完成后，通过预设的验证函数或再次调用 LLM 进行质量检查。
4. **异常回溯**：若验证未通过，智能体会根据错误信息重新生成或修正子任务，并尝试重新执行。
5. **结果聚合**：所有子任务成功后，智能体将中间结果合并为最终输出，并生成完整的执行报告。

## 调用步骤

1. **初始化**：实例化 `MultiStepReasoningAgent`，并传入 LLM 配置、验证函数库以及可选的执行插件。
2. **输入任务**：调用 `agent.run(task_description)`，将任务描述作为字符串传入。
3. **查看计划**：`agent.get_plan()` 返回当前的子任务列表及状态，便于人工审查或干预。
4. **执行**：智能体自动遍历子任务并执行，实时返回执行日志和进度。
5. **获取结果**：任务链完成后，通过 `agent.get_result()` 获得最终结果和报告。
6. **异常处理**：如遇不可恢复的错误，可调用 `agent.retry(step_id)` 重试指定步骤，或使用 `agent.reset()` 重新开始。

## 示例代码（Python）

```python
from multi_step_agent import MultiStepReasoningAgent, ValidationFunctions

# 初始化智能体
agent = MultiStepReasoningAgent(
    llm="gpt-4",                # 大模型标识
    validators=ValidationFunctions.default(),  # 默认验证函数集
    plugins={
        "code_exec": CodeExecutorPlugin(),   # 代码执行插件
        "sql_query": SQLPlugin()             # SQL 查询插件（可选）
    }
)

# 定义复杂任务
task = (
    "对用户提供的数据集进行清洗，生成特征工程报告，"
    "并使用线性回归模型进行训练，最后输出模型评估指标。"
)

# 运行智能体
result = agent.run(task)

# 打印最终结果
print("最终结果：", result)
print("执行报告：", agent.get_report())
```

## 注意事项

- **资源限制**：每个子任务的执行时间不宜过长，建议控制在 30 秒以内，以免导致超时或占用过多资源。
- **验证函数**：必须提供可靠的验证函数，否则错误会在后续子任务中层层放大，导致整体失败。
- **插件安全**：自定义执行插件需做好沙箱隔离，防止执行恶意代码或误操作关键系统资源。
- **日志审计**：建议开启执行日志，便于后期追踪错误、审计过程以及持续改进任务拆解策略。
- **并发限制**：当前实现为顺序执行，若业务对时间敏感，可自行改造 `executor` 为线程池或进程池实现并行化。
- **模型成本**：频繁的 LLM 调用会产生较高的 token 费用，请根据业务需求合理设置调用频率和批量处理策略。
- **容错机制**：在关键子任务完成后加入二次确认或人工审批，可进一步提升系统的鲁棒性。
- **数据隐私**：任务中涉及的敏感信息应在调用 LLM 前进行脱敏处理，避免泄露。

通过上述步骤与注意事项，即可快速部署多步推理智能体，实现复杂任务的自动化拆解、验证与执行，提升业务效率和结果可靠性。