AgentDescent
Evolve prompts, skills, and agent implementations in parallel by merging evidence-backed diffs.
- Source repo
- Birfy/agentdescent
- Stars
- ★ 198
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 83/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A model engineer with labeled examples can evolve a system prompt or single-slot skill against a held-out reward set and inspect the resulting accuracy.
- Not a fit if
- Teams needing production-grade reliability or operational guarantees
- Users expecting numeric-gradient-style averaging of concurrent edits
- Researchers needing archives, per-instance score rows, or island pools, which the policy slots cannot express
- Source review
- 83/100 · Good
What does this agent do, and when should you use it?
AgentDescent is a research framework for evolving prompts, skills, agent directories, and agent code, treating proposed diffs as gradients and the aggregator as an optimizer. Multiple workers run tasks against snapshots of a versioned ledger and emit diffs with evidence cards, while one aggregator thread handles staleness, conflicts, fusion, acceptance, and transactional commits. Its primary Python entry point is evolve(), supported by Strategy implementations, eight Policies slots, LLMAgent, dataset and scoring helpers, and an aggregator_factory escape hatch. A run produces a rendered artifact, held-out reward, outcome records, and aggregator counters, with accepted changes stored in a Git-backed ledger. It can be used as a Python library or through a CLI, MCP server, and host plugins for Claude Code, Codex, OpenCode, and DeepSeek Harness. The repository explicitly describes itself as a research reference implementation rather than a production system.
The user converts data into Task objects, supplies a reward function, and defines run for executing the current artifact plus propose for suggesting a change after a failure; these roles can instead be packaged in an LLMAgent. evolve() distributes tasks to workers, which read ledger snapshots, perform rollouts, and place evidence-backed diffs into a buffer. The aggregator continuously processes those results under selection, task-sampling, proposal, staleness, conflict, fusion, acceptance, and promotion policies, then commits accepted changes transactionally to a Git-backed ledger. AppendRules, KeyedRules, FileTree, and SingleSlot map artifacts into different key spaces, determining whether concurrent edits can fuse or must conflict. Callers inspect result.rendered, result.final_reward, and result.outcomes() after a run. Through the agent plugin, the same engine is exposed by MCP and matching CLI operations named doctor, plan, start, status, show, apply, cancel, and resume.
- A model engineer with labeled examples can evolve a system prompt or single-slot skill against a held-out reward set and inspect the resulting accuracy.
- An agent developer maintaining a lesson library can use
AppendRulesorKeyedRulesso several workers propose rules concurrently and fuse edits made to separate keys. - A researcher maintaining a multi-file skill or agent implementation can use
FileTreeto evolve a directory while containing conflicts to individual file paths. - A self-improvement research team can run ports such as ACE, GEPA, and EvoSkill under serial, synchronous, or barrier-free scheduling and treat scheduling as a controlled variable.
- A developer working in Claude Code, Codex, OpenCode, or DeepSeek Harness can start evolution through a host plugin and inspect the detached run from the CLI.
- A framework author can replace individual
Policiesslots or useaggregator_factorywhen an algorithm requires state such as archives, per-instance score rows, or island pools.
How do you install or deploy this agent?
The core package requires Python 3.9 or newer and has no required third-party dependencies. Install the published package with:
pip install agentdescentThe repository examples and development tests are kept outside the installed package. Clone the project and install its development extras to run them:
git clone https://github.com/Birfy/agentdescent && cd agentdescent
pip install -e ".[dev]"
python -m examples.run_demoThat demo requires neither an API key nor network access. For an OpenAI-compatible endpoint, provide credentials through the environment at call time; the base URL selects the provider:
export OPENAI_BASE_URL=https://api.deepseek.com
export OPENAI_API_KEY=sk-...To wire the plugin and MCP interface into detected agent CLIs, run these commands from the repository:
bash scripts/setup-hosts.sh
agentdescent demo
agentdescent doctorHow do you use this agent?
This minimal example needs no API key or external dependency. It creates tasks, defines a reward in the [0, 1] range, supplies execution and proposal functions, and evolves the shared artifact with three workers:
from agentdescent import Task, evolve
tasks = [Task(id=f"t{i}", prompt=f"item {i}") for i in range(12)]
def reward(task, output):
return 1.0 if "2026" in output else 0.0
def run(rendered, task):
return "answer" + (" 2026" if "year" in rendered else "")
def propose(rendered, task, output, reward):
return "always state the year"
result = evolve(tasks, reward, run=run, propose=propose,
rounds=6, n_workers=3, max_concurrency=3)
print(result.rendered, result.final_reward, result.error)For a real model or agent, use LLMAgent with a documented adapter. Barrier-free execution is enabled with asynchronous=True:
from agentdescent import LLMAgent, claude, openai_compatible, claude_code
evolve(tasks, reward, agent=LLMAgent(claude(model="claude-haiku-4-5")))
evolve(tasks, reward, agent=LLMAgent(openai_compatible(model="deepseek-v4-flash")))
evolve(tasks, reward, agent=LLMAgent(claude_code()))
# Or: evolve(..., asynchronous=True, async_ratio=3)From the command line, inspect available CLIs and credentials, then run the offline demonstration:
agentdescent doctor
agentdescent demoWhat are this agent's strengths and limitations?
- Parallel workers and a barrier-free aggregator can accept several compatible edits in one iteration instead of imposing a one-change serial limit.
- Strategies, eight independent policy slots, and
aggregator_factoryprovide layered extension points; a driver rejects policy fields it cannot honor rather than silently ignoring them. - The same engine supports serial, synchronous, and asynchronous scheduling and includes 20 self-evolution algorithm ports for controlled scheduler comparisons.
- The core supports Python 3.9 and newer with zero required dependencies, while the demo and deterministic test suite run offline without credentials.
- Python, CLI, MCP, and multi-host plugin surfaces let users initiate a run from an agent and inspect it from a shell.
- The project is explicitly a research reference implementation, not a production system, and the supplied material does not establish production availability or operational guarantees.
- Diffs cannot be added like numeric gradients; same-key edits conflict, so useful parallelism depends heavily on the chosen strategy's key space and the quality of aggregation.
- Runs against real models require network access and incur provider call costs, which is why the plugin workflow quotes call counts before starting.
- The reported quality and speed results use specific tasks, models, seed counts, and rollout budgets and do not establish general performance on other workloads.
- Per-run data was not retained for the merge-versus-selection sweeps, so those results can be re-measured from the named command but not recomputed from preserved raw runs.
- Algorithms requiring archives, per-instance score rows, or island pools cannot be implemented solely through the policy slots and must use the lower-level
aggregator_factorypath.
How does this agent compare with similar options?
Compared with a serial self-improvement loop limited to one accepted change per iteration, AgentDescent runs several proposal workers and attempts to merge non-conflicting diffs. The repository reports a median 6.8× wall-clock improvement over a faithful serial control for one GEPA-on-HotpotQA configuration; that measurement covers three seeds, four workers, and a fixed budget of 16 rollouts rather than a universal speed claim. It also packages ACE, GEPA, EvoSkill, SkillOpt, ADAS, DGM, OpenEvolve, and ERA as benchmark-faithful ports that can run under serial, synchronous, or barrier-free schedules. Twelve additional implementations are labeled microports or analogues and are explicitly not presented as benchmark reproductions.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| AgentDescent This agent | 83 · Good | Library / SDKFree + model costs | ★ 198 | today | Python | Codex · Claude Code · OpenAI API · Claude API |
| SkillLite | 60 · Some gaps | CLIFree + model costs | ★ 150 | 1mo ago | Rust | — |
| LLMSlim Context and Memory | 70 · Some gaps | MCP serverFree + model costs | ★ 22 | 2d ago | Python | Codex · Claude Code |
| Trace Generative Optimizer | 67 · Some gaps | Library / SDKFree + model costs | ★ 763 | 1y ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows a dependency-free core, isolated plugin copies, frozen permission configuration, a recursion guard, a version-controlled ledger, and explicit confirmation before starting or writing changes back. Publishing workflows use scoped permissions and OIDC, while the fixed data path and sole feedback path are described clearly. Deductions apply because no complete policy is shown for key storage, redaction, log scrubbing, or data retention; workflow dependencies use version tags rather than commit digests; and cancel, resume, and git history do not amount to a fully documented user-facing rollback procedure. The paper author, DOI, and code origin are attributed, but package authorship is generic and publisher identity remains unknown.
The README, package metadata, and test utilities are strongly consistent about Python support, offline operation, entry points, and the merge model. Golden traces deliberately exercise both fusion and conflict decisions. The dependency surface is small and the Python 3.9 versus MCP constraint is handled explicitly, but optional dependencies have only lower bounds and real runs still depend on external models, datasets, CLIs, and git. Fault fixtures cover authentication errors, throttling, permanent and transient outages, wedged work, empty responses, and ledger failures, with an explicit expectation of prompt and visible failure reporting.
The material identifies research users, agent-host users, and algorithm implementers, with scenarios spanning prompts, skills, directories, agent code, and plugins. Strategy, policy slots, aggregator factories, and serial, synchronous, and asynchronous scheduling provide substantial adaptation points. Boundaries are unusually explicit: this is a research reference rather than a production system, governance cannot be replaced, key spaces constrain fusion, and unsupported policy fields are rejected. Trigger phrases and the doctor/plan/start/status/apply procedure are described, but the actual shared skill and its trigger rules are absent, so trigger precision is not fully evidenced. Python compatibility, offline demos, multiple host CLIs, optional MCP support, and version markers support strong environment fit.
The README is well organized around installation, quickstarts, architecture, extension seams, results, documentation, citation, and scope. It distinguishes the core install, development setup, MCP option, and repository-only examples, and includes both offline and model-backed examples. Limitations are candidly documented, including research status, non-additive diffs, key-space constraints, statistical limits, and unretained raw data. MIT licensing is complete and consistent with metadata. Deductions apply because the source acknowledges historical version drift and does not include the current version file, while no changelog, release history, or migration policy is supplied. A contribution route and automated publishing exist, but named maintenance ownership, support channels, and response expectations are unclear.
The result exposes the evolved artifact, final reward, and outcome reasons, while CLI and MCP surfaces provide inspection, status, display, application, cancellation, and resumption. Parallel conflict-aware merging, configurable strategies and policies, and nineteen algorithm ports offer clear marginal value over a basic serial self-improvement loop. Model-call reduction, wall-clock speedup, accuracy change, confidence intervals, and pre-run call-count quotation provide substantial cost-benefit evidence. These scores assess the quality of the static evidence only and do not imply independent reproduction.
Major empirical claims identify tasks, models, worker counts, seeds, budgets, sample sizes, intervals, or raw-data locations. The architecture is said to derive from paper source, and test utilities explain exactly which merge decisions and fault classes they guard, providing strong traceability. README statements are corroborated in places by project metadata, workflows, and test code, but the paper, main test bodies, result files, and core implementation are not included in the supplied evidence, preventing full cross-source corroboration. The material clearly separates benchmark-faithful ports from analogues, measurements from hypotheses, confidence intervals from unavailable significance, and retained from unretained data.
- This is a low-confidence static review: no code, tests, demos, or benchmarks were executed, and linked papers, documentation, package registries, and result data were not verified.
- The project explicitly describes itself as a research reference implementation rather than a production system. Use isolated repositories, least-privilege credentials, human review, and verified backups before allowing it to modify skills, prompts, code, or plugins.
- Runs against real models or datasets may send prompts, task content, and outputs to external providers. The supplied material does not fully specify credential, sensitive-data, logging, or retention controls.
- Some per-run benchmark data was not retained, and the fidelity and performance of the nineteen algorithm ports cannot be independently established from the supplied files alone.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.7.0 0.7.0 — named algorithm registry, self-improvement and verifier tooling
Release notes excerpt
Added - A persistent-island population run now returns EvolutionResult.lineages (#150, semantics C): a read-only row per lineage (dev plus each island) with its candidate count, best archived version/score, selection count and lineage tip. It is read from the archive the gate already scored, survives finalize, and is None on a single-head run; the official artifact is unchanged. - ACE's grow-and-refine playbook is now a named algorithm ("algorithm": "ace", kind: text) in the in-package registry (#384). ACEPlaybook, its …View on GitHub ↗ -
v0.6.0 0.6.0 — multi-head, allocator, trajectories, governance
Release notes excerpt
Everything merged since 0.5.1: multi-head ledger forks, value-directed allocation, L-traj resume, trajectory ledger, governance contracts, CladeThompson, skill_dir structural gates, RRSI building blocks, changelog fragments, and a large set of crash-safety / overflow / parser fixes. Highlights - Multiple live heads — Ledger.fork / live_heads / discard_head so workers can expand different candidates in parallel without serialising on dev. - Value-directed budget allocation — evolve(allocator=...) learns which candidates are worth the expensive self-verify rollout. …View on GitHub ↗ -
v0.5.1 0.5.1 — reliable host installs and a clearer first run
Release notes excerpt
Everything merged since 0.5.0, including the host-launch repair and the updated website, quickstart and documentation. Highlights - Machine-local MCP launchers and session hooks use the installing Python, so a later agent process does not need the pip scripts directory on PATH. Reinstalling repairs stock legacy and stale pinned Codex/OpenCode entries while preserving custom configurations and wrappers. …View on GitHub ↗
FAQ
Do I need a paid model or API key?
python -m examples.run_demo, agentdescent demo, and pytest -q, all of which can run offline. Connecting to an OpenAI-compatible service, Claude, or another real model requires the relevant credentials, network access, and provider calls.Does parallel proposal generation always improve speed or quality?
Will it overwrite my prompt or code automatically?
Can it use providers other than OpenAI?
openai_compatible(), claude(), and claude_code(), and the base-URL configuration names DeepSeek, GLM, local vLLM, and OpenAI endpoints.What can I inspect when a run stalls, conflicts, or stops improving?
result.error and result.outcomes(). Plugin users can additionally use status, show, cancel, and resume; the acceptance gate can stop committing when there is nothing left to improve.