Skip to content

Orchestra-Research/AI-Research-SKILLs / 14-agents/a-evolve

evolving-ai-agents

Verified

Provides guidance for automatically evolving and optimizing AI agents across any domain using LLM-driven evolution algorithms. Use when building self-improving agents, optimizing agent prompts and skills against benchmarks, or implementing automated agent evaluation loops.

FileKindSize
SKILL.mdskill md14.3 KB
references/README.mdmarkdown26.5 KB
references/api.mdmarkdown15.4 KB
references/architecture.mdmarkdown15.1 KB
references/design-patterns.mdmarkdown14.8 KB
references/examples.mdmarkdown9.8 KB
references/issues.mdmarkdown16.0 KB
references/releases.mdmarkdown4.5 KB
references/tutorials.mdmarkdown22.6 KB

references/releases.md

View on GitHub
# A-Evolve Release History

## v0.1.0 — Initial Public Release

**Date**: 2025

**Highlights**:
- Universal agent evolution infrastructure
- Three pluggable interfaces: `BaseAgent`, `BenchmarkAdapter`, `EvolutionEngine`
- File-system workspace contract with git versioning
- Four built-in evolution algorithms

**Benchmark Results** (Claude Opus 4.6):
- MCP-Atlas: 79.4% (#1 on leaderboard)
- SWE-bench Verified: 76.8% (~#5 on leaderboard)
- Terminal-Bench 2.0: 76.5% (~#7 on leaderboard)
- SkillsBench: 34.9% (#2 on leaderboard)

### Core Components

**Agent Protocol** (`agent_evolve.protocol.base_agent`):
- `BaseAgent` abstract class with `solve()`, `reload_from_fs()`, `export_to_fs()`
- Memory buffering via `remember()`
- Skill access via `get_skill_content()`
- Properties: `system_prompt`, `skills`, `memories`

**Benchmark Adapter** (`agent_evolve.benchmarks.base`):
- `BenchmarkAdapter` abstract class with `get_tasks()` and `evaluate()`
- Built-in adapters: SWE-bench Verified, MCP-Atlas, Terminal-Bench 2.0, SkillsBench, ARC-AGI-3

**Evolution Engine** (`agent_evolve.engine.base`):
- `EvolutionEngine` abstract class with `step()` and `on_cycle_end()`
- Default engine: AEvolveEngine (LLM-driven workspace mutation via bash tools)
- Additional engines: GuidedSynthesisEngine, AdaptiveEvolutionEngine, AdaptiveSkillEngine

**Evolution Loop** (`agent_evolve.engine.loop`):
- Orchestrates solve → observe → evolve → gate → reload cycles
- Git snapshot versioning (pre-evo-N, evo-N tags)
- Convergence detection with configurable threshold and window
- JSONL observation storage

**Agent Workspace** (`agent_evolve.contract.workspace`):
- `AgentWorkspace` class for typed file I/O
- Prompt read/write (system.md + fragments)
- Skill CRUD (list, read, write, delete)
- Draft management (propose, list, clear)
- Memory management (add, read by category)
- Tool registry and implementation management
- Evolution metadata access

**Configuration** (`agent_evolve.config`):
- `EvolveConfig` dataclass with YAML loading
- Controls: batch_size, max_cycles, holdout_ratio
- Layer toggles: evolve_prompts, evolve_skills, evolve_memory, evolve_tools
- Evolver model configuration (supports Anthropic, OpenAI, Bedrock, LiteLLM)
- Convergence: egl_threshold (default 0.05), egl_window (default 3)

**Top-Level API** (`agent_evolve.api`):
- `Evolver` class: 3-line setup and run
- Auto-resolution of agent seeds and benchmark names
- Workspace copying and manifest validation

### Built-in Seed Agents

| Agent | Domain | Framework | Model |
|-------|--------|-----------|-------|
| SWE Agent | SWE-bench | Strands | Claude Opus 4.6 (Bedrock) |
| Terminal Agent | Terminal-Bench | Strands | Claude Sonnet 4 (Bedrock) |
| MCP Agent | MCP-Atlas | Strands | Claude Opus 4.6 (Bedrock) |

### Evolution Algorithms

| Algorithm | Module | Strategy |
|-----------|--------|----------|
| A-Evolve/SkillForge | `algorithms.skillforge` | LLM with bash tools mutates workspace |
| Guided Synthesis | `algorithms.guided_synth` | Memory-first, curated skill proposals |
| Adaptive Evolution | `algorithms.adaptive` | Reward tracking, observation filtering |
| Adaptive Skill | `algorithms.adaptive_skill` | Skill-centric discovery and refinement |

### Installation Options

```bash
pip install a-evolve                # Core (matplotlib, pyyaml)
pip install a-evolve[anthropic]     # + anthropic>=0.30
pip install a-evolve[openai]        # + openai>=1.30
pip install a-evolve[bedrock]       # + boto3>=1.34
pip install a-evolve[litellm]       # + litellm>=1.0.0
pip install a-evolve[swe]           # + strands-agents, datasets, swebench
pip install a-evolve[mcp]           # + mcp, strands-agents, litellm
pip install a-evolve[all]           # Everything
pip install a-evolve[dev]           # + pytest, ruff, hypothesis
```

### Requirements

- Python >= 3.11
- Core dependencies: matplotlib >= 3.10.0, pyyaml >= 6.0
- Git (for workspace versioning)

### Known Limitations

- Evolution loop is single-threaded (sequential cycles)
- Convergence check uses hardcoded epsilon=0.01 in loop internals vs configurable egl_threshold in EvolveConfig
- No built-in distributed evaluation (parallelize via external orchestration)
- Workspace versioning requires git; non-git workflows not supported

### Links

- **Repository**: [github.com/A-EVO-Lab/a-evolve](https://github.com/A-EVO-Lab/a-evolve)
- **PyPI**: [pypi.org/project/a-evolve](https://pypi.org/project/a-evolve/)
- **Issues**: [github.com/A-EVO-Lab/a-evolve/issues](https://github.com/A-EVO-Lab/a-evolve/issues)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall