hyperagent

Hyperagent

快速开始 — 简单示例

刚开始使用 Hyperagent？先试试这些适合新手的任务，再进行完整设置。

1. 优化简单的 Python 脚本以提升运行速度

说：“使用 hyperagent 优化此脚本的运行速度”，然后粘贴类似下面的内容：

# slow_sort.py
def sort_numbers(nums):
    result = []
    while nums:
        smallest = min(nums)
        result.append(smallest)
        nums.remove(smallest)
    return result

Hyperagent 会对其进行基准测试，提出更快的实现方案，并验证改进效果。

2. 改进提示词以获得更好的回答

说：“对这个提示词运行 hyperagent 并提高准确率”，并附上类似下面的提示词：

Summarize this article in one sentence.

元 Agent 会迭代优化提示词、衡量质量，并保留得分更高的改进。

3. 提高排序函数的效率

说：“使用 hyperagent 演进这个函数”，然后粘贴任意函数。Hyperagent 会创建基准测试，运行多代改进，并展示每一代带来的性能提升。

4. 自我改进任意脚本

说：“自我改进此 Agent/脚本”，并指定任意 Python 文件。Hyperagent 会将其封装到评估循环中，提出修改方案，并跟踪哪些方案有效。

最简单的设置方式：创建一个会输出 METRIC score=0.5 的 task.sh，然后运行 python3 scripts/init_session.py。之后，整个循环将完全自动化。

---

自指式自我改进：一种会修改任务 Agent（以及自身）的元 Agent，用于优化任何可衡量的目标。

灵感源自 Facebook Research 的 Hyperagents 论文（arXiv:2603.19461）。该论文展示了将任务求解器与可自我修改的元层结合到单个可编辑程序中的 Agent，能够实现开放式、复合式改进，并将改进迁移到不同领域。

工作原理

Hyperagent 是由两个组件组成的系统，这两个组件位于同一个可编辑代码库中：

1. 任务 Agent — 解决目标任务（基准测试、代码生成、数据处理等）
2. 元 Agent — 分析任务性能历史，并提出对任务 Agent 代码（以及可选的自身代码）的修改方案

论文中的关键见解是：如果元层修改过程本身也可编辑，系统就不仅能提升任务性能，还能改进生成后续改进的机制，从而实现复合式、可迁移的收益。

核心原则

1. 自指式修改

   元 Agent 可以修改任务 Agent 的代码，也可以修改自身策略。两者都位于同一个可编辑工作区中。这使元认知式自我改进成为可能：改进改进自身的方式。

2. 基于种群的探索（存档）

   不要只保留最佳变体，还要将所有成功变体存档，作为后续探索的踏脚石。选择父代时，优先考虑表现优异且具有未开发潜力的变体。

3. 实证评估决定一切

   未经测量，不接受任何更改。每个候选方案都要通过多次试验，根据任务基准进行评估。

4. 持久化记忆和性能跟踪

   系统会维护所有实验、假设和结果的结构化历史。后续代会基于先前的见解继续推进，避免重复探索无效路径。

5. 跨领域迁移

   元层改进（性能跟踪、评估策略、假设生成模式）不依赖特定领域，可迁移到新任务中。

可用脚本

• scripts/common.py — 共用工具（归档管理、指标、报告）
• scripts/init_session.py — 初始化 hyperagent 会话，搭建工作区
• scripts/run_task.py — 评估任务 Agent 变体并记录指标
• scripts/log_variant.py — 记录已评估条目、决定处理方式并更新归档和报告
• scripts/render_report.py — 生成完整演化历史的 HTML 报告
• scripts/select_parent.py — 从归档中为下一代选择父代

注意： 没有 generate_variant.py 脚本——元 Agent 的角色（生成假设和修改代码）由 LLM Agent 自身承担，而非由脚本执行。

所有脚本都无需交互，支持 --help，会在 stdout 上输出结构化 JSON，并将诊断信息写入 stderr。

默认工作流

1. 定义优化目标后，初始化会话：

   python3 scripts/init_session.py \
     --goal "Improve prompt accuracy on math benchmark" \
     --metric-name accuracy \
     --unit pct \
     --direction higher \
     --task-command ./task.sh \
     --checks-command ./checks.sh \
     --scope src/agent.py \
     --max-generations 50
   

2. 评估基线（第 0 代）：

   python3 scripts/run_task.py \
     --id gen-000 \
     --hypothesis "Control: unmodified task agent" \
     --change-summary "No modifications" \
     --baseline \
     --output .hyperagent/gen-000.json
   
   python3 scripts/log_variant.py --input .hyperagent/gen-000.json
   

3. 选择 → 修改 → 评估循环：

   # Select a parent from the archive
   python3 scripts/select_parent.py --output .hyperagent/parent.json
   
   # Generate a variant (meta-agent proposes modifications)
   # This is where YOU (the LLM agent) act as the meta-agent:
   # - Read the parent's code and performance history
   # - Hypothesize an improvement
   # - Apply code modifications
   # - Record what you changed and why
   
   # Evaluate the variant
   python3 scripts/run_task.py \
     --id gen-001 \
     --hypothesis "Add chain-of-thought prompting to improve reasoning" \
     --change-summary "Wrap task prompt in step-by-step reasoning template" \
     --parent gen-000 \
     --output .hyperagent/gen-001.json
   
   python3 scripts/log_variant.py --input .hyperagent/gen-001.json
   

4. 随时生成报告：

   python3 scripts/render_report.py
   

前期问答

开始前，请收集或确认以下信息：

1. 目标 — 我们要优化什么？
2. 主要指标 — 确切名称、单位和方向（越低越好／越高越好）
3. 任务命令 — 运行任务 Agent 并输出 METRIC name=value 行的脚本
4. 正确性门槛 — 变体要保留，必须通过哪些测试或检查
5. 范围 — 元 Agent 可以修改哪些文件？
6. 元范围 — 元 Agent 能否修改自身策略？（默认：可以）
7. 代数预算 — 停止前的最大代数
8. 最低改进阈值 — 默认 1%

工作区设置

1. 优先在新分支上使用专用工作树：

   git worktree add ../hyperagent-<goal>-<date> -b hyperagent/<goal>-<date>
   

2. 创建：

   • hyperagent.md — 纳入版本控制的持久会话概要，包含完整演化历史
   • task.sh — 纳入版本控制的基准测试运行脚本（输出 METRIC name=value）
   • checks.sh — 纳入版本控制的正确性门槛
   • .hyperagent/ — 本地构件目录，不纳入版本控制

3. 确保构件保持未跟踪状态：

   rg -qxF '.hyperagent/' .git/info/exclude || printf '\n.hyperagent/\n' >> .git/info/exclude
   

元 Agent 的角色

你（LLM）就是元 Agent。 每一代，你的工作是：

1. 选择父代 — 使用 scripts/select_parent.py，或根据归档进行选择
2. 分析 — 阅读父代的代码、性能历史和过往实验结果
3. 提出假设 — 提出具体、可测试的修改，并说明其可能奏效的因果理论
4. 修改 — 修改任务 Agent 的代码（也可选择更新 hyperagent.md 中的自身策略备注）
5. 评估 — 运行 scripts/run_task.py 测量该变体
6. 记录 — 使用 scripts/log_variant.py 记录结果并更新归档
7. 反思 — 更新 hyperagent.md，记录所学内容

元层面的自我修改

元 Agent 可以通过更新以下内容来改进自身流程：

• hyperagent.md 中的策略备注（假设生成模式、评估启发式）
• .hyperagent/memory.jsonl 中的记忆条目（定性见解、纠正计划）
• 任务评估协议（添加次要指标、更改试验次数）

这些元层面的改进会在各代中不断累积，并迁移到新任务中。

必需文件

hyperagent.md

持久的约定和演化历史。新的 Agent 可以从此处恢复工作。

# Hyperagent: <goal>

## Objective
<What is being optimized and why.>

## Configuration
- Primary metric:
- Unit:
- Direction:
- Minimum improvement: X%
- Task command:
- Correctness gates:
- Generation budget:

## Scope
- Task agent files:
- Meta-agent can self-modify: yes/no

## Archive
`.hyperagent/archive.jsonl`

## Lineage
<Tree showing parent→child relationships and which variants were kept>

## Meta-Strategy
<Current approach to hypothesis generation — updated as the meta-agent learns>

## What We've Learned
<Key wins, dead ends, transferable insights>

## Performance Tracking
<Best variant, improvement trajectory, current plateau status>

task.sh

运行任务 Agent 并输出 METRIC name=value 行的 Bash 脚本：

#!/bin/bash
set -euo pipefail
# Run the task agent
python3 src/agent.py --input data/test.json 2>/dev/null
# The agent script should emit: METRIC accuracy=0.85

归档结构

归档（.hyperagent/archive.jsonl）会存储所有曾评估过的变体：

{
  "id": "gen-007",
  "generation": 7,
  "parent_id": "gen-003",
  "timestamp": "2026-03-27T20:00:00Z",
  "hypothesis": "Add few-shot examples to improve pattern recognition",
  "change_summary": "Inserted 3 domain-specific examples into the task prompt",
  "files_touched": ["src/agent.py"],
  "metric_name": "accuracy",
  "direction": "higher",
  "warmup_trials": [0.82, 0.83],
  "measured_trials": [0.85, 0.86, 0.84, 0.85, 0.87],
  "summary": {"median": 0.85, "mean": 0.854, "min": 0.84, "max": 0.87},
  "checks": "passed",
  "disposition": "keep",
  "children_count": 0,
  "meta_modifications": ["Updated strategy notes with few-shot pattern"],
  "reason": "Improved by 3.2% over parent gen-003 (0.824). Checks passed."
}

父代选择

父代的选择概率与以下因素成正比：

• 性能得分（得分越高，越有助于归档多样性）
• 子代数量的倒数（优先选择子代较少的高性能变体）

这样可以平衡利用（表现良好的变体）和探索（研究不足的变体）。

python3 scripts/select_parent.py
# Output: {"selected_parent": "gen-003", "score": 0.824, "children": 1, "reason": "High performer with few children"}

决策规则

• keep — 变体比当前最佳结果至少高出阈值，检查通过
• discard — 变体表现更差、相同或提升低于阈值
• checks_failed — 指标有所提升，但未通过正确性门槛
• crash — 无法评估变体

平台期检测

跟踪改进速度。在以下情况下停止或调整方向：

• 连续 3 代以上没有改进
• 假设多样性下降（反复使用相同想法）
• 最近 5 代的平均改进速度低于 0.1%

循环行为

自主运行，直到：

• 达到代数预算上限
• 检测到平台期（连续 3 次未改进）
• 已探索所有有前景的假设
• 用户中断

循环期间：

• 每代只测试一个假设
• 明确记录行不通的方向
• 在不同变体之间保持工作树干净（还原已舍弃的更改）
• 每代结束后更新 hyperagent.md

常见陷阱

1. 元 Agent 过拟合自身策略

症状： 元策略过度适应早期的成功案例
修复： 定期审查并拓宽策略；尝试类别截然不同的方法

2. 归档膨胀

症状： 归档变得庞大，选择速度变慢
修复： 在 50 个变体后归档较早的代，并维护精简的摘要

3. 自我修改导致循环不稳定

症状： 元 Agent 修改评估或日志记录方式，导致循环无法运行
修复： 保持外层循环脚本（初始化、运行、记录、选择）不可变。只修改任务代码和策略说明。

4. 假设循环使用

症状： 后续代重复尝试早期失败的想法
修复： 提出新假设前，务必阅读 .hyperagent/memory.jsonl。明确检查是否与已知的失败方向重复。

迁移协议

将元改进迁移到新领域：

1. 从 hyperagent.md 的“已学经验”部分提取元策略
2. 将 .hyperagent/memory.jsonl 复制为初始知识
3. 使用迁移后的策略作为初始上下文，启动新会话
4. 元 Agent 从积累的经验出发，而非从零开始

报告生成

python3 scripts/render_report.py

生成 .hyperagent/report.html，其中包含：

• 血缘树可视化
• 跨代性能表现
• 历史最佳趋势
• 处置结果分类
• 各变体的试验分布
• 元策略演进时间线