hyperagents-self-improving

Imported from reason-machines/trending-skills (skills/hyperagents-self-improving/SKILL.md). Install upstream with npx skills add reason-machines/trending-skills --skill hyperagents-self-improving. Copyright stays with the author.

---
name: hyperagents-self-improving
description: Self-referential self-improving agents from Meta Research that optimize for any computable task using meta-agents and task-agents in a recursive loop
triggers:
  - set up hyperagents
  - run self-improving agent loop
  - configure meta agent for domain
  - use hyperagents to optimize a task
  - implement self-referential agent
  - run generate loop with hyperagents
  - hyperagents experiment setup
  - facebookresearch hyperagents
---

# HyperAgents Self-Improving Agents

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

HyperAgents is a Meta Research framework for self-referential, self-improving agents that recursively optimize themselves for any computable task. A **meta-agent** proposes code changes (diffs) to improve a **task-agent**, which is then evaluated on a target domain. The loop continues, progressively improving agent performance.

## Architecture Overview

generate_loop.py └── meta_agent.py ← proposes improvements (diffs) to task agent code └── task_agent.py ← executes tasks in a target domain └── agent/ ← foundation model wrappers (OpenAI, Anthropic, Gemini) └── domains/ ← domain-specific evaluation code └── run_meta_agent.py ← helper to run meta agent and get diffs

The meta-agent reads the current task-agent source, generates improved versions, applies diffs, and evaluates the new agent. This is repeated in a loop.

---

## Installation

### 1. System Dependencies (Fedora/RHEL)
```bash
sudo dnf install -y python3.12-devel
sudo dnf install -y graphviz graphviz-devel cmake ninja-build \
    bzip2-devel zlib-devel ncurses-devel libffi-devel

2. Python Environment

python3.12 -m venv venv_nat
source venv_nat/bin/activate
pip install -r requirements.txt
pip install -r requirements_dev.txt

3. API Keys

Create a .env file in the project root:

OPENAI_API_KEY=your_openai_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here
GEMINI_API_KEY=your_gemini_key_here

4. Initial Agent Setup

bash ./setup_initial.sh

5. (Optional) Docker

docker build --network=host -t hyperagents .

⚠️ Safety Warning: HyperAgents executes untrusted, model-generated code. Run in an isolated environment (Docker, VM, or sandboxed container). Never run on a production system.

Key Commands

Run the Main Loop

# Basic run on a domain
python generate_loop.py --domains <domain>

# Examples:
python generate_loop.py --domains coding
python generate_loop.py --domains math
python generate_loop.py --domains reasoning

Run the Meta Agent Standalone

python run_meta_agent.py

Extract Experiment Logs

# Combine multi-part ZIP archive
zip -s 0 outputs_os_parts.zip --out unsplit_logs.zip
unzip unsplit_outputs.zip

Outputs are saved in outputs/ by default.

Core Files and Usage

generate_loop.py — Entry Point

# Typical invocation pattern (from source)
import argparse
from meta_agent import MetaAgent
from task_agent import TaskAgent

parser = argparse.ArgumentParser()
parser.add_argument("--domains", type=str, required=True)
parser.add_argument("--output_dir", type=str, default="outputs/")
parser.add_argument("--num_iterations", type=int, default=10)
parser.add_argument("--model", type=str, default="gpt-4o")
args = parser.parse_args()

meta_agent.py — Meta Agent

The meta-agent reads task-agent code and proposes improvements:

from meta_agent import MetaAgent

meta = MetaAgent(
    model="claude-3-5-sonnet-20241022",  # or "gpt-4o", "gemini-pro"
    task_description="Solve competitive programming problems",
    current_agent_code=open("task_agent.py").read()
)

# Get proposed diff/improvement
diff = meta.propose_improvement()
print(diff)

task_agent.py — Task Agent

The task-agent executes tasks in a domain:

from task_agent import TaskAgent

agent = TaskAgent(
    model="gpt-4o",
    domain="coding"
)

# Run agent on a task
result = agent.run(task_input="Solve: given an array, find the maximum subarray sum")
print(result)

agent/ — Foundation Model Wrappers

# Using OpenAI wrapper
from agent.openai_agent import OpenAIAgent

agent = OpenAIAgent(model="gpt-4o")
response = agent.generate(
    system_prompt="You are a helpful coding assistant.",
    user_prompt="Write a binary search implementation in Python."
)

# Using Anthropic wrapper
from agent.anthropic_agent import AnthropicAgent

agent = AnthropicAgent(model="claude-3-5-sonnet-20241022")
response = agent.generate(
    system_prompt="You are a helpful assistant.",
    user_prompt="Explain self-referential improvement."
)

# Using Gemini wrapper
from agent.gemini_agent import GeminiAgent

agent = GeminiAgent(model="gemini-pro")
response = agent.generate(prompt="Optimize this Python function for speed.")

Domain Configuration

Domains live in domains/. Each domain defines how tasks are sampled and how agents are evaluated:

# Example domain structure (domains/coding/)
# domains/coding/__init__.py
# domains/coding/tasks.py      ← task definitions
# domains/coding/evaluator.py  ← scoring/evaluation logic

from domains.coding.evaluator import CodingEvaluator

evaluator = CodingEvaluator()
score = evaluator.evaluate(
    agent_output="def max_subarray(arr): ...",
    ground_truth_tests=[...]
)

To add a custom domain:

1. Create domains/my_domain/ directory
2. Implement tasks.py with task generation
3. Implement evaluator.py with scoring logic
4. Register the domain in generate_loop.py

Common Patterns

Pattern 1: Full Self-Improvement Loop

import os
from dotenv import load_dotenv
from meta_agent import MetaAgent
from task_agent import TaskAgent

load_dotenv()

DOMAIN = "coding"
NUM_ITERATIONS = 5
META_MODEL = "claude-3-5-sonnet-20241022"
TASK_MODEL = "gpt-4o"

# Load initial task agent source
with open("task_agent.py", "r") as f:
    agent_code = f.read()

meta = MetaAgent(model=META_MODEL)
scores = []

for i in range(NUM_ITERATIONS):
    print(f"\n=== Iteration {i+1}/{NUM_ITERATIONS} ===")
    
    # Meta-agent proposes improvement
    improved_code = meta.propose_improvement(
        current_code=agent_code,
        domain=DOMAIN,
        iteration=i
    )
    
    # Evaluate improved agent
    task_agent = TaskAgent(model=TASK_MODEL, code=improved_code)
    score = task_agent.evaluate_on_domain(DOMAIN, num_tasks=10)
    scores.append(score)
    print(f"Score: {score:.3f}")
    
    # Accept improvement if score is better
    if score > max(scores[:-1], default=0):
        agent_code = improved_code
        print("✓ Improvement accepted")
    else:
        print("✗ Improvement rejected, keeping previous version")

Pattern 2: Running With Docker (Recommended for Safety)

# Build image
docker build --network=host -t hyperagents .

# Run with env file
docker run --env-file .env \
    -v $(pwd)/outputs:/app/outputs \
    hyperagents python generate_loop.py --domains coding

# Interactive shell inside container
docker run -it --env-file .env hyperagents /bin/bash

Pattern 3: Analyzing Results

import json
import os

output_dir = "outputs/"

# Load all iteration results
results = []
for fname in sorted(os.listdir(output_dir)):
    if fname.endswith(".json"):
        with open(os.path.join(output_dir, fname)) as f:
            results.append(json.load(f))

# Plot improvement curve
import matplotlib.pyplot as plt

iterations = [r["iteration"] for r in results]
scores = [r["score"] for r in results]

plt.plot(iterations, scores, marker='o')
plt.xlabel("Iteration")
plt.ylabel("Score")
plt.title("HyperAgents Self-Improvement Curve")
plt.savefig("improvement_curve.png")
plt.show()

Pattern 4: Selecting Baseline vs. HyperAgents

# Run with a specific baseline (see generate_loop.py --help for options)
python generate_loop.py --domains coding --baseline random
python generate_loop.py --domains coding --baseline zero_shot
python generate_loop.py --domains coding  # default: HyperAgents loop

Environment Variables Reference

Load via .env file or export directly:

export OPENAI_API_KEY=$(cat ~/.secrets/openai_key)

Troubleshooting

graphviz import error

sudo dnf install -y graphviz graphviz-devel
pip install --force-reinstall pygraphviz

python3.12-devel not found (Ubuntu/Debian)

sudo apt-get install python3.12-dev
sudo apt-get install libgraphviz-dev cmake ninja-build

API rate limit errors

• Add retry logic or reduce --num_iterations
• Switch to a different model provider in your config

Generated code causes crashes

• This is expected behavior — the framework catches exceptions and rejects bad improvements
• Run inside Docker for full isolation
• Check outputs/ for logs of what code was generated

.env not being loaded

pip install python-dotenv
# Ensure load_dotenv() is called at the top of your entry script

Extracting multi-part experiment logs

# All parts (.z01, .z02, .zip) must be in the same directory
zip -s 0 outputs_os_parts.zip --out unsplit_logs.zip
unzip unsplit_outputs.zip -d logs/

Citation

@misc{zhang2026hyperagents,
      title={Hyperagents}, 
      author={Jenny Zhang and Bingchen Zhao and Wannan Yang and Jakob Foerster 
              and Jeff Clune and Minqi Jiang and Sam Devlin and Tatiana Shavrina},
      year={2026},
      eprint={2603.19461},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2603.19461}, 
}

Links: arXiv Paper | Meta AI Blog | License: CC BY-NC-SA 4.0