self-improving-agent-builder

自我改进 Agent 构建器

用途

对任意目标导向型 Agent 实现运行闭环改进周期：

EVAL -> ANALYZE -> RESEARCH -> IMPROVE -> RE-EVAL -> DECIDE -> (repeat)

每次迭代都会测量 L1-L12 渐进式测试分数，使用 error_analyzer.py 识别失败，开展包含假设、证据和反方论据的研究步骤，应用有针对性的修复，并通过回归检查决定是否晋级。

何时启用

• “改进 Agent”或“自我改进循环”
• “Agent 评估循环”或“运行改进周期”
• “对 Agent 进行基准测试”或“比较 SDK 实现”
• “迭代提升 Agent 分数”或“修复 Agent 回归问题”

快速开始

User: "Run the self-improving loop on the mini-framework agent for 3 iterations"

Skill: Executes 3 iterations of EVAL->ANALYZE->RESEARCH->IMPROVE->RE-EVAL->DECIDE
       Reports per-iteration scores, net improvement, and commits/reverts.

运行器脚本

自我改进循环通过 Python CLI 实现：

# Basic usage
python -m amplihack.eval.self_improve.runner --sdk mini --iterations 3

# Full options
python -m amplihack.eval.self_improve.runner \
  --sdk mini \
  --iterations 5 \
  --improvement-threshold 2.0 \
  --regression-tolerance 5.0 \
  --levels L1 L2 L3 L4 L5 L6 \
  --output-dir ./eval_results/self_improve \
  --dry-run  # evaluate only, don't apply changes

源码： src/amplihack/eval/self_improve/runner.py

循环（每次迭代包含 6 个阶段）

阶段 1：EVAL

在当前 Agent 实现上运行 L1-L12 渐进式测试套件。

执行：

python -m amplihack.eval.progressive_test_suite \
  --agent-name <agent_name> \
  --output-dir <output_dir>/iteration_N/eval \
  --levels L1 L2 L3 L4 L5 L6

输出： 各级分数和总体基线。

阶段 2：ANALYZE

使用 error_analyzer.py 对失败进行分类。将每个失败的问题映射到失败分类体系（retrieval_insufficient、temporal_ordering_wrong 等）以及对应的具体代码组件。

from amplihack.eval.self_improve import analyze_eval_results

analyses = analyze_eval_results(level_results, score_threshold=0.6)
# Each ErrorAnalysis maps to:
#   failure_mode -> affected_component -> prompt_template

阶段 3：RESEARCH（新增）

关键的思考步骤，可避免盲目更改。针对每项拟议改进：

1. 提出假设：哪项具体更改可以修复失败？
2. 收集证据：来自评估结果、失败模式和基线分数
3. 考虑反方论据：可能出现什么问题？是否有回归风险？
4. 做出决定：给出完整理由，选择应用、跳过或暂缓

决定会记录在 research_decisions.json 中，以便审计。

决定标准：

• 应用：失败模式明确 + 有可用的提示词模板 + 分数较低
• 跳过：分数高于 50%（可能是随机波动）
• 暂缓：证据模糊，需要更多数据

阶段 4：IMPROVE

应用研究步骤批准的改进。优先顺序：

1. 提示词模板改进（最安全、影响最大）
2. 调整检索策略
3. 修复代码逻辑（风险最高，需要仔细审查）

阶段 5：RE-EVAL

应用修复后重新运行同一评估套件，以衡量影响。

阶段 6：DECIDE

晋级门槛：

• 总分净提升 >= +2%：提交更改
• 任一级别的回归 > 5%：撤销所有更改
• 否则：提交更改，并注明提升幅度较小

配置

参数	默认值	描述
sdk_type	mini	使用哪个 SDK：mini/claude/copilot/microsoft
max_iterations	5	最大改进迭代次数
improvement_threshold	2.0	提交所需的最低提升百分比
regression_tolerance	5.0	任一级别允许的最大回归百分比
levels	L1-L6	要评估的级别
output_dir	./eval_results/self_improve	结果目录
dry_run	false	仅评估，不应用更改

编程方式使用

from amplihack.eval.self_improve import run_self_improvement, RunnerConfig

config = RunnerConfig(
    sdk_type="mini",
    max_iterations=3,
    improvement_threshold=2.0,
    regression_tolerance=5.0,
    levels=["L1", "L2", "L3", "L4", "L5", "L6"],
    output_dir="./eval_results/self_improve",
    dry_run=False,
)

result = run_self_improvement(config)
print(f"Total improvement: {result.total_improvement:+.1f}%")
print(f"Final scores: {result.final_scores}")

四路基准测试模式

并排比较所有 SDK 实现：

User: "Run a 4-way benchmark comparing all SDK implementations"

Skill: Runs eval suite on mini, claude, copilot, microsoft
       Generates comparison table with scores, LOC, and coverage.

集成点

• src/amplihack/eval/self_improve/runner.py：自我改进循环运行器
• src/amplihack/eval/self_improve/error_analyzer.py：失败分类
• src/amplihack/eval/progressive_test_suite.py：L1-L12 评估运行器
• src/amplihack/agents/goal_seeking/sdk_adapters/：全部 4 种 SDK 实现
• src/amplihack/eval/metacognition_grader.py：高级评估维度
• src/amplihack/eval/teaching_session.py：L7 教学质量评估