多步推理智能体：任务分解与逐步验证

## 功能概述
多步推理智能体是一种将复杂任务分解为多个可执行的子任务，并按顺序或并行执行，同时对每一步的输出进行验证和必要纠正的 Agent 框架。它通过规划（Plan）和执行（Execute）两大阶段，实现任务的高成功率与可解释性。

## 关键特性
- **任务拆解**：自动识别任务意图，生成细粒度的子任务列表。
- **动态调度**：支持顺序、并行或条件分支执行。
- **结果验证**：对每个子任务输出进行校验，发现异常及时回滚或重试。
- **日志追踪**：记录每个步骤的输入、输出与耗时，便于审计与调试。

## 使用场景
- 需要多步骤数据处理或分析的流水线任务。
- 对外部 API 调用结果进行二次校验的业务流程。
- 需要在不确定环境下进行迭代实验的研究项目。
- 对话式助理在复杂查询时进行多轮信息检索和答案整合。

## 调用步骤
1. **初始化 Agent**：实例化 `MultiStepAgent`，并提供 LLM（如 GPT‑4）以及可选的验证函数集合。
2. **输入任务描述**：调用 `agent.plan(task_description)`，传入完整的用户需求或目标。
   - `task_description` 为字符串，可包含自然语言描述或结构化的任务模板。
3. **获取子任务计划**：`agent.plan` 将返回子任务列表（每个子任务含 `id`、`description`、`depends_on`）。
4. **执行子任务**：调用 `agent.execute(subtask_id)`，逐个运行子任务。
   - 若子任务依赖前置任务，则在所有依赖完成后自动执行。
5. **验证结果**：执行完成后，系统自动调用对应的验证函数（如 `validate_json`、`validate_range`），若验证失败则触发重试或回滚。
6. **聚合最终结果**：所有子任务成功后，`agent.finalize()` 将合并子任务产出，生成统一的报告或回复。
7. **获取日志**：通过 `agent.get_logs()` 可查看每一步的输入、输出、耗时与错误信息。

## 注意事项
- **LLM 调用配额**：规划阶段会产生多次 LLM 调用，请确保 API 配额充足或在 `plan` 时使用缓存。
- **验证函数必须幂等**：验证函数不应修改输入数据，只做检查，否则可能导致状态不一致。
- **超时与重试**：每个子任务默认超时 30 秒，若超时或验证失败最多重试 3 次，可通过 `config.max_retry` 调整。
- **资源占用**：并行执行子任务会占用更多显存或计算资源，建议在资源受限环境下使用顺序执行模式。
- **日志保密**：日志中可能包含用户隐私数据，请在使用前做好脱敏或加密处理。

## 示例代码（Python）
```python
from multi_step_agent import MultiStepAgent, validate_json

agent = MultiStepAgent(
    llm="gpt-4",
    validators=[validate_json],
    max_retry=3,
    timeout=30,
)

task = "对某电商平台的订单数据进行清洗、统计并生成月度报表。"
plan = agent.plan(task)
for subtask in plan.subtasks:
    result = agent.execute(subtask.id)
    if not agent.validate(subtask.id):
        print(f"子任务 {subtask.id} 验证失败，进行重试")
        result = agent.execute(subtask.id, retry=True)

final_report = agent.finalize()
print(final_report)
```

## 最佳实践
- **拆分粒度适中**：子任务不宜过细，以免产生大量调度开销；也不宜过粗，导致验证困难。
- **提前定义验证函数**：在启动 Agent 前准备好所有可能使用的验证规则，可提升整体鲁棒性。
- **监控异常**：在生产环境中接入监控告警，及时捕获 `ExecutionError` 或 `ValidationError`。
- **文档化子任务**：为每个子任务编写简短的说明文档，帮助后续维护者快速理解流程。

通过以上设计，多步推理智能体能够在保持高可解释性的同时，实现复杂任务的自动化拆解与执行，为业务系统提供可靠、灵活的 AI 驱动解决方案。