多步推理规划执行智能体

## 功能概述

多步推理智能体是一种基于规划‑执行（Plan‑Execute）模式的 AI 代理。它首先将用户提出的复杂任务拆解成若干子任务，随后为每个子任务制定执行计划，按顺序执行并在每一步完成后进行结果验证。若验证不通过，智能体会自动回溯或重新规划，以确保最终输出的质量。该智能体适用于任务目标明确、步骤之间有依赖或需要迭代校验的业务场景。

## 适用场景

- **复杂业务流程自动化**：如订单处理、数据清洗与转换、跨系统数据同步。
- **多步骤数据分析**：包括数据抽取、特征工程、模型训练、结果评估。
- **项目管理**：任务拆解、进度跟踪与风险预警。
- **研发任务**：需要在执行期间进行中间结果校验的代码生成、测试用例编写。

## 调用步骤

1. **输入任务描述**
   用户在调用接口时提供完整的需求说明，包括目标、约束以及可选的成功标准。
   ```json
   {
     "task": "请帮我完成从原始 CSV 文件到清洗后数据的完整处理流程，包括去重、缺失值填补、异常值检测，并输出统计报告。",
     "options": {
       "validation_mode": "strict",
       "max_retry": 3
     }
   }
   ```

2. **任务拆解与计划生成**
   多步推理智能体内部调用 LLM 生成子任务列表和对应的执行计划。计划以 YAML 格式返回，便于后续审查与修改。
   ```yaml
   steps:
     - id: step1
       name: 数据导入与初步清洗
       action: load_csv → drop_duplicates
       validation: "row_count > 0"
     - id: step2
       name: 缺失值检测与填补
       action: fillna(strategy="mean")
       validation: "missing_count == 0"
     - id: step3
       name: 异常值检测
       action: detect_outliers(method="IQR")
       validation: "outlier_ratio < 0.05"
     - id: step4
       name: 生成统计报告
       action: generate_report(format="markdown")
   ```

3. **按序执行子任务**
   系统会逐条执行 `action`，每完成一步立即调用 `validation` 检查点。如果验证通过，进入下一步；否则根据 `options.max_retry` 进行重试或回滚。

4. **结果聚合与输出**
   所有子任务完成后，智能体将结果聚合为统一响应，并附带每一步的执行日志、耗时以及校验状态。

5. **可选的人工干预**
   在关键节点（如异常检测、重大决策）可配置人工确认环节，确保业务合规。

## 示例代码（Python）

```python
import json
from agent_sdk import MultiStepAgent

agent = MultiStepAgent(model="gpt-4", api_key="YOUR_API_KEY")

task_payload = {
    "task": "请完成从原始 CSV 到清洗后数据的完整流程，并输出统计报告。",
    "options": {"validation_mode": "strict", "max_retry": 3}
}

response = agent.run(task_payload)
print(json.dumps(response, indent=2, ensure_ascii=False))
```

运行后返回的 `response` 结构示例如下：

```json
{
  "status": "success",
  "total_steps": 4,
  "steps": [
    {"id": "step1", "status": "pass", "duration_ms": 120},
    {"id": "step2", "status": "pass", "duration_ms": 85},
    {"id": "step3", "status": "pass", "duration_ms": 200},
    {"id": "step4", "status": "pass", "duration_ms": 310}
  ],
  "report": "## 数据统计报告\n- 原始记录数: 10000\n- 去重后记录数: 9850\n- 缺失值填补后完整率: 100%\n- 异常值比例: 0.02"
}
```

## 注意事项

- **输入完整性**：提供的任务描述应尽量包含明确的约束条件和期望结果，否则智能体可能在计划阶段产生歧义。
- **资源限制**：每个子任务的执行时间受平台资源限制，若单步超时可能导致整体任务失败。请在 `options` 中设置合理的超时时间。
- **验证模式**：默认 `strict` 模式要求每一步校验通过才能继续。若业务允许容错，可切换为 `relaxed`，并自行在后续步骤中处理异常。
- **敏感数据**：在跨系统数据同步或涉及用户隐私的场景下，请确保已在调用前对数据进行脱敏或加密，智能体本身不提供数据加密功能。
- **日志审计**：所有执行日志（包括计划、动作、校验结果）都会被持久化，建议在生产环境开启审计日志，以便事后追溯。
- **并发限制**：同一时间只能有一个活跃的任务实例，若需要并行处理多个复杂任务，请使用多实例部署或任务队列。
- **模型更新**：智能体的规划能力依赖于底座大模型，建议定期更新模型版本，以获得更精准的拆解和校验策略。

## 小结

多步推理智能体通过“计划‑执行‑验证”闭环，显著提升了复杂任务的可靠性与可解释性。适用于需要严谨流程控制、逐步校验以及对错误容忍度低的业务场景。调用时只需提供清晰的任务描述，系统即可自动完成从拆解到输出的全链路工作，帮助开发者聚焦业务价值而非实现细节。