Website & interactive demo · Get started · Documentation
Gradient descent — but the parameters are agents. AgentDescent evolves prompts, skills, agent directories, agent code and host plugins against your own examples. N workers propose edits in parallel, one aggregator merges them into a version-controlled artifact, and a held-out gate decides what is kept. Use it from Python with one
evolve()call, from the CLI, or from inside Claude Code, Codex, OpenCode, DeepSeek Harness or Grok Bot.
pip install "agentdescent[mcp]>=0.10.0"
agentdescent demo # a complete evolution, offline, no API key, ~10 s
agentdescent doctor # which agent CLIs and provider keys this machine hasThe default host / MCP loop is Path A (doctor → plan → start → apply).
Advanced MCP tools need agentdescent mcp --advanced — see
MCP / CLI Path A.
[mcp] adds the agent-facing MCP server and needs Python ≥ 3.10; the library
itself supports 3.9, where you drop [mcp] and drive it with the CLI. Research
examples are outside the wheel: to run python -m examples.run_demo or any
algorithm port, clone the repo and follow
Install and first run:
git clone https://github.com/ThinkFlowLab/agentdescent && cd agentdescent
pip install -e ".[dev,mcp]"agentdescent demo builds a skill whose rules name the wrong CSV column, twelve
cases with known totals and a local program as the agent, then runs the real
loop — only the model is replaced — and ends with:
held-out reward: 1.000 outcomes: {'committed': 1}
what it learned: rules.md -> 'COLUMN: amount'
Skill evolution here means a multi-file skill library, not a single prompt:
agentdescent demo --kind skill_library.
Runnable as-is — no API key, no dependencies. Three functions are the whole contract: how to run a task, how to score it, and what to propose on a failure.
from agentdescent import Task, evolve
tasks = [Task(id=f"t{i}", prompt=f"item {i}") for i in range(12)]
def reward(task, output): # must return [0, 1]
return 1.0 if "2026" in output else 0.0
def run(rendered, task): # your solver
return "answer" + (" 2026" if "year" in rendered else "")
def propose(rendered, task, output, reward): # what to add on a failure
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)To point the same loop at a file or directory:
agentdescent init ./my-skill --data cases.jsonl --out spec.json
agentdescent plan spec.json # validates and prices it; runs nothing
agentdescent evolve spec.json --detach
agentdescent status # then: show, apply --dry-run, applyCredentials are read from the environment at call time — never from code.
Nothing is written back until apply, which backs up first.
Install and first run has
the real-model path, host setup, and the cost and permission notes. A
dataset-to-skill walkthrough is in
Quickstart — dataset to skill.
| If you want to… | Start here |
|---|---|
| Install and run it once | Install and first run |
| Use it from an agent | The plugin, step by step · Every host · Set it up and test it |
| Evolve a skill, a directory, or agent code | Dataset to skill · Directory · Agent code |
| Call or add an algorithm | Named algorithms · Twenty-three ports · Register a card |
| Understand the engine | Architecture · evolve() · API |
| Read the measurements | Results · Efficiency |
On 40 HotpotQA items (12 held out) a one-call evolve() run took held-out exact
match from 0.167 to 0.583. The results page
records the setting, the caveats, and the runs where there was nothing left to
learn.
N workers roll out in parallel; one aggregator merges diffs; a held-out gate decides what is kept. The long form — strategies, policy slots, and why governance is not a seam — is in Architecture and Concepts.
Use GitHub's Cite this repository button (CITATION.cff);
per-result raw data is in bench/results/.
A research reference implementation, not a production system. The novelty is
a narrow engineering synthesis — concurrent, staleness-bounded,
conflict-resolved diff-level merge over a git-backed versioned ledger — and its
throughput premise is a testable hypothesis rather than community consensus.
Contributions welcome: CONTRIBUTING.md. The suite is offline
and deterministic, so pytest -q needs no API key.
