多步规划与推理智能体

## 功能概述
- 将复杂任务拆解为多个可独立执行的子任务。
- 对每个子任务进行规划（Plan）和执行（Execute），并在执行后进行验证（Validate）。
- 通过循环的“计划‑执行‑验证”过程，实现可靠的逐步推理。

## 使用场景
- 需要多步决策的业务流程，如客服对话、自动化运维、复杂报告生成。
- 任务目标明确但实现路径不明确，需要先拆解再逐步求解的场景。
- 对每一步结果进行校验，以确保整体输出的准确性。

## 调用步骤
1. **输入任务**：用户提供自然语言描述的目标或任务清单。
2. **任务拆解**：智能体使用内部 LLM 将任务分解为若干子任务，并生成执行顺序。
3. **子任务规划**：对每个子任务，模型先输出一个简短的计划（Plan），说明该子任务的输入、输出和关键步骤。
4. **执行子任务**：依据计划调用相应工具或 API 完成子任务，记录执行日志。
5. **验证结果**：对每个子任务的输出进行检查，若不符合预期则触发重试或回退机制。
6. **状态累计**：将已完成子任务的结果汇总到全局上下文，供后续子任务使用。
7. **最终输出**：所有子任务完成后，生成最终报告或响应，返回给用户。
8. **异常处理**：若在某一步出现不可恢复的错误，智能体应记录错误原因并给出合理的终止建议。

## 示例代码
```json
{
  "type": "agent",
  "name": "multi_step_reasoner",
  "input": "帮我生成一份关于 2023 年全球光伏市场的年度分析报告",
  "steps": [
    {
      "step_id": 1,
      "sub_task": "收集 2023 年全球光伏装机容量数据",
      "plan": "调用公开数据集 API 获取 2023 年全球光伏装机容量",
      "execute": "api_call('pv_installations', year=2023)",
      "validate": "检查返回数据是否完整且为数值型"
    },
    {
      "step_id": 2,
      "sub_task": "分析各国装机容量占比",
      "plan": "使用 Python pandas 计算各国占比并绘制饼图",
      "execute": "python_script('analysis.py')",
      "validate": "确认图表生成且占比总和为 100%"
    },
    {
      "step_id": 3,
      "sub_task": "撰写报告正文",
      "plan": "依据上一步的分析结果生成结构化报告",
      "execute": "llm_generate('report_template', context=analysis_result)",
      "validate": "检查报告章节完整性、语言流畅度"
    }
  ]
}
```
在上述示例中，智能体通过三个子任务完成了从数据获取到报告撰写的完整流程，每一步都经过计划、执行、验证三阶段。

## 注意事项
- **任务粒度**：子任务不宜过细，否则会产生大量交互开销；也不宜过粗，导致难以验证每一步正确性。建议每个子任务的执行时间控制在 5–30 秒之间。
- **上下文管理**：因为是多轮对话，上下文会不断增长，需要使用合适的上下文压缩或摘要技术，以免超出模型的 token 上限。
- **错误回退**：当子任务验证失败时，智能体应先尝试自动重试；若重试次数超过阈值仍未成功，则应返回错误信息并提供可能的补救措施。
- **安全合规**：在调用外部 API 或执行代码时，务必遵守相应的权限和数据安全要求，防止泄露敏感信息。
- **日志审计**：每一次计划、执行、验证的日志都应持久化，以便后期追踪和审计。
- **模型选择**：不同规模的任务可以选用不同容量的语言模型；简单子任务可使用轻量模型，复杂推理步骤则需更强的模型。

## 最佳实践
- 在系统设计阶段明确子任务的验收标准（acceptance criteria），并将其写入计划（Plan）中，便于自动化验证。
- 使用统一的错误码体系，例如 `STEP_ERR_TIMEOUT`、`STEP_ERR_VALIDATION`，方便上层系统进行监控和告警。
- 定期回顾多步推理的执行路径，评估是否可以通过任务合并或拆分提升整体效率。
- 在用户界面展示每个子任务的进度条或状态标签，让用户感知任务正在进行哪一步，提升用户体验。

## 小结
多步规划与推理智能体通过“拆解‑规划‑执行‑验证”的闭环流程，实现对复杂任务的可控、可追溯交付。合理划分任务粒度、严谨的验证机制以及完善的错误处理，是确保该智能体在实际生产环境中稳健运行的关键。