A-Evolve

Evolves an agent’s prompts, skills, and memory from benchmark feedback.

Stars
★ 844
Last updated
2d ago
Primary language
Python

At a glance

How it runs
Library / SDKFrameworkCLI
Works with
Universal · cross-platformOpenAI API · Claude API
Cost
Free software; you pay for model usage
Setup effort
Medium · a few setup steps
You'll need
Python 3.11+GitShell / CLINetwork accessLocal filesystemMCP Server
Typical use
A research team improving a code-repair agent on SWE-bench Verified can begin with the built-in swe-verified seed workspace and adapter.
Not a fit if
  • End users who want a ready-made agent, not to evolve their own
  • Teams that cannot supply paid Anthropic, OpenAI, or Bedrock API keys
  • Teams unwilling to let the engine auto-rewrite prompts, skills, and memory files

What does this agent do, and when should you use it?

A-Evolve is Python infrastructure for evolving an existing agent, not a standalone end-user agent. Developers provide an agent workspace and benchmark adapter to ae.Evolver, which runs a Solve, Observe, Evolve, Gate, Reload loop. Its filesystem workspace contract covers manifest.yaml, prompts, SKILL.md skills, tool configuration, and JSONL memory. Evolution engines modify those files from trajectories and evaluation feedback, then validate candidates on holdout tasks and can roll back regressions through Git. The repository includes adapters and seed workspaces for SWE-bench Verified, MCP-Atlas, Terminal-Bench, SkillsBench, and CL-Bench, while exposing interfaces for custom agents, benchmarks, and algorithms.

When Evolver.run(cycles=10) is called, A-Evolve has the agent run solve() on task batches, collects Trajectory objects and benchmark feedback, and records structured observations. An EvolutionEngine.step() implementation can inspect the workspace, observations, history, and trial context before changing prompt, skill, or memory files. The Gate phase validates a candidate on holdout tasks; regressed mutations are reverted through Git, while accepted versions are tagged as evo-1, evo-2, and so on. A custom agent implements BaseAgent.solve(self, task: Task) -> Trajectory; a custom benchmark implements BenchmarkAdapter.get_tasks() and .evaluate().

  1. A research team improving a code-repair agent on SWE-bench Verified can begin with the built-in swe-verified seed workspace and adapter.
  2. A developer building an MCP tool-calling agent can use mcp-atlas and let evaluation feedback drive changes to skill files.
  3. An algorithm researcher testing a new self-improvement strategy can implement EvolutionEngine.step() while reusing trial, history, and Git rollback primitives.
  4. A team with an existing custom agent that wants a benchmark-driven loop for prompts, skills, and memory can wrap it as a BaseAgent.
  5. An evaluator comparing evolution approaches for terminal-operation or skill-discovery tasks can use the Terminal-Bench or SkillsBench examples.

How do you install or deploy this agent?

Python 3.11+ is required. Install the core package with pip install a-evolve; Claude support with pip install a-evolve[anthropic]; MCP-Atlas support with pip install a-evolve[mcp]; SWE-bench support with pip install a-evolve[swe]; or all extras with pip install a-evolve[all]. For source development, run git clone https://github.com/A-EVO-Lab/a-evolve.git && cd a-evolve, then pip install -e ".[all,dev]". The README names Anthropic, OpenAI, and AWS Bedrock as LLM Provider examples, but does not document the exact credential configuration; configure authentication for the selected provider before use.

How do you use this agent?

For a minimal run, import with import agent_evolve as ae, create evolver = ae.Evolver(agent="swe-verified", benchmark="swe-verified"), then run results = evolver.run(cycles=10) and inspect results.final_score and results.converged. To evolve your own agent, subclass BaseAgent, implement solve() to return a Trajectory, and pass it as ae.Evolver(agent=MyAgent("./my_workspace"), benchmark="mcp-atlas"). The agent workspace should follow the documented filesystem contract and be reloadable by the agent after each cycle; accepted changes are Git-tagged.

What are this agent's strengths and limitations?

Pros
  • Uses a standard directory as the evolvable state, so prompts, skills, and memory can be processed through one workflow without requiring knowledge of the agent’s internals.
  • Separately pluggable BaseAgent.solve(), BenchmarkAdapter, and EvolutionEngine.step() interfaces let adopters replace the agent, evaluation, or evolution strategy.
  • Candidate changes are checked on holdout tasks, with Git rollback for regressions and evo-* tags for accepted versions.
  • Includes benchmark adapters and seed workspaces spanning code repair, MCP tool calling, terminal operations, skill discovery, and continual-learning evaluation.
Limitations
  • Outcomes depend on the benchmark, base model, evolution algorithm, and task setup; the reported results do not establish comparable gains for a custom agent.
  • It automatically changes workspace files and relies on Git-style version control, so teams must define which prompts, skills, and memory files are safe to evolve.
  • Although Anthropic, OpenAI, and AWS Bedrock are listed as provider examples, the supplied material does not specify credential setup, model selection, or cost controls.
  • The Terminal-Bench domain explicitly involves Docker, so adopting that adapter may require a container runtime.

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
A-Evolve This agent 48 · Major gaps Library / SDKFree + model costs ★ 844 2d ago Python OpenAI API · Claude API
hax 66 · Some gaps CLIFree + model costs ★ 978 today C OpenAI API · Claude API
mlx-serve: Native LLM Inference for Apple Silicon 62 · Some gaps Desktop appFree ★ 2.4k today Zig Claude Code · OpenAI API · Claude API
Stripe AI 55 · Major gaps Library / SDKFree + model costs ★ 2k today TypeScript Codex · Claude Code · OpenAI API · Claude API

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Major gaps
48/ 100 5-point scale 2.4 / 5
Trust 12/29
Reliability 6/14
Adaptability 12/18
Convention 8/18
Effectiveness 7/13
Verifiability 3/8
Why each dimension lost points
Trust12 / 29 · 2.1/5

The framework reads and rewrites agent workspace files, and a custom evolution engine may choose whether to use validation and version control. The README describes holdout gates, Git rollback, and mutation tags, but the supplied material does not establish permissions or confirmation across all execution paths, so least privilege, user confirmation, and external effects score 1–2. The MCP agent obtains server keys through a key registry and imports a secret-redaction utility, but the excerpt does not establish end-to-end sensitive-data protection, so that criterion scores 1. Dependencies have minimum version bounds but no lock or security policy, scoring 1. The project cites a paper and names A-EVO Lab authors, but publisher identity is unverified, so source attribution scores 1.

Reliability6 / 14 · 2.1/5

The README's general Python 3.11+ requirement and CLAUDE.md's ARC SDK requirement of Python 3.12+ are not necessarily contradictory, but the general installation description does not clearly explain this branch-specific exception. More directly, the README says CC BY-NC 4.0 while pyproject declares MIT; this direct license conflict limits self-consistency to 1. Dependencies have optional extras and minimum versions, but no lockfile or evidence of availability across environments, scoring 1. The CLI gives a clear invalid-boolean message, and the ARC agent returns a structured error trajectory when arc-agi is missing, so failure messages score 2.

Adaptability12 / 18 · 3.3/5

The framework explicitly targets researchers, agent authors, and benchmark authors, with custom agent, benchmark, and algorithm interfaces plus several built-in benchmark paths; audience and scenario coverage scores 3. The extension interfaces are described, but custom engines can bypass shared validation and rollback primitives, leaving capability boundaries incomplete at 2. The CLI exposes task directories, filters, modes, and scoring choices, but the general quick start does not clearly define when to use each, so trigger precision scores 2. The README's Python 3.11+ guidance differs from the ARC-specific environment requirement, and examples depend on external model, Docker, or benchmark environments, so environment fit scores 1.

Convention8 / 18 · 2.2/5

The README is clearly organized around use cases, architecture, installation, algorithms, and community information, scoring 3. It provides PyPI extras and source installation, but benchmark and model environment requirements are spread across dedicated guides, scoring 2. The product, package, and import names are A-Evolve, a-evolve, and agent_evolve, and the packet refers to different branches, so naming stability scores 1. Quick starts, interface examples, and benchmark guide links are useful, though there is no FAQ, scoring 2. CLAUDE.md records incomplete ARC attempts and weak pure-LLM results, but the README does not systematically present framework limitations, scoring 1. The README's CC BY-NC 4.0 and pyproject's MIT declaration conflict, so license scores 0. News lists dated announcements, but there is no clear release-matched changelog, scoring 1. Issue and PR links exist, but ongoing maintenance responsibility and update process are not clearly stated, scoring 1.

Effectiveness7 / 13 · 2.7/5

The framework API, CLI JSON results, standard workspace contract, and benchmark adapters provide usable integration outputs. However, the supplied material does not support underlying reports for README benchmark figures and claims such as SOTA, so output usability scores 2. The unified agent, evaluation, and evolution interfaces have a clear potential reuse benefit, but the benefit is mostly asserted in the supplied material, scoring 2. Repeated evaluation cycles, model calls, containers, and external benchmarks can incur cost; the CLI exposes token, retry, task, and cycle settings, but cost estimates and budget controls are not sufficiently described, scoring 1.

Verifiability3 / 8 · 1.9/5

Paper citations and algorithm and benchmark guides provide some paths to trace claims, but several README rankings and scores are not tied to verifiable reports or results in the supplied packet, scoring 1. The README, source, and tests complement one another on interfaces, workspaces, and some GEPA behavior, but tests cover sampled components and do not substantiate broad benchmark claims, scoring 1. The README gives a results-check date and some baseline comparisons, but the supplied material does not consistently separate evidence from promotional claims, scoring 1.

Risks and how to mitigate them
  • The license information materially conflicts: the README labels the project CC BY-NC 4.0, while pyproject.toml declares MIT. Resolve the applicable license before use or redistribution.
  • The framework rewrites agent workspaces, and ARC/MCP source defaults BYPASS_TOOL_CONSENT to true. Review actual execution paths, external service calls, and workspace recovery before use.
  • Benchmark scores and rankings in the README are primarily project claims in this packet; this static review does not establish reproducibility or result correctness.
Evidence confidence: Low Reviewed Nov 08, 2026 Reviewed revision 48c4814e9236
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/a-evolve.svg)](https://followagents.com/en/agents/a-evolve)
<a href="https://followagents.com/en/agents/a-evolve"><img src="https://followagents.com/badge/a-evolve.svg" alt="FARS review"></a>

FAQ

Does it directly train or fine-tune my language model?
The documented core loop changes agent workspace files such as prompts, skills, tool configuration, and memory; model-weight training is not described as a core A-Evolve API.
What happens when an evolved change performs worse?
The Gate phase evaluates candidate changes on holdout tasks. Regressions are rolled back through Git, while accepted changes are recorded with evo-* tags.
Can I use my own agent and benchmark?
Yes. A custom agent implements BaseAgent.solve(), and a custom benchmark implements BenchmarkAdapter.get_tasks() and .evaluate().
Which model provider do I need?
The README presents the LLM Provider as pluggable and lists Anthropic, OpenAI, and AWS Bedrock examples. Exact authentication setup is not provided in the supplied material.
What will it cost to run?
The supplied material provides no pricing, token-use estimate, or recommended iteration budget. Cost depends on the chosen model provider and number of cycles.
Was this page helpful?
View on GitHub ↗ Install ↓