AntOmniEvo: improving an agent system by editing its files

The division of labor that defines the framework

AntOmniEvo is built around one sentence: you define your system's tunable artifacts and what good means, the framework controls the loop, AI agents do the work. That division is the design, and every other part of the project follows from it.

The framework's own README spells out who does what. You define five things, once: a System, meaning how to run your system on one evaluation instance; an Evaluator, meaning how to score its output from 0 to 1, whose scoring criteria is the optimization objective; the evaluation data, meaning the train and validation instances that define good; a TunableArtifactSchema that maps your tunable artifacts onto a directory, giving the file tree and what each file is for; and the initial tunable artifacts, the starting point. The framework controls the loop and all the engineering inside it, including scheduling, budgets, selection and elimination, and persistence. The AI works, meaning a coding-agent Proposer does the changing. The delivery is the best candidate's tunable artifacts, a directory of files you can diff, review, and deploy.

The interesting part is what that excludes. The system under optimization does not need to contain an LLM, although the proposer must be agents. So this is not a prompt-tuning library and not a model trainer. It is a loop that edits files until a number goes up, and the number comes from you.

Tunable artifacts are the genome, and they are plain files

The unit of optimization is what the documentation calls a tunable artifact: a real directory of files. The README gives three concrete shapes for it. An agent's SKILL.md plus references plus scripts. A workflow's pipeline.json plus node scripts, such as a retrieval DAG's configuration and its nodes/*.py files. A single-file algorithm in .py or .ts plus its description. Anything that can be expressed that way, and can be repeatably evaluated, is in scope.

That constraint is what makes the whole approach work. Because the genome is files, a change is a diff, reviewable by a human in the way a pull request is, and deployable by copying a directory. The Proposer reads failure trajectories, locates which file to edit, and lands a structured change as the tunable artifacts of a new candidate, and the README is explicit that it does this the way a human would edit code. A change lineage attributes every edit back to the failure evidence that motivated it.

The category list in the README names the systems this suits: NL2SQL skills, coding-agent skills and harness, agentic-API skills, system prompts and strategy documents, workflow configurations, and single-file algorithms. The recurring precondition is the same in every case. You need a repeatable and reasonably cheap evaluation, because the loop runs many candidates and measures them all.

What the framework runs on your behalf

Inside the loop there is a fair amount of machinery that the README describes as deterministic work you do not have to write: scheduling, budgets, selection and elimination, and persistence, with the strongest candidates kept in the population. The mechanism is a concurrent evolution loop in which a Proposer rewrites the artifacts in response to failure trajectories.

Persistence is treated as a first-class concern rather than an afterthought. Every candidate, run, analysis, and changelog is written to a CandidateStore, and the documentation lists checkpoint resume and crash recovery as its own topic. The wording in the README is that the store makes the run interruptible and resumable. For a loop that can run for hours and consumes a proposer agent on every iteration, that is the difference between a long job and an aborted job, and it is also the difference between inspecting a run afterwards and starting from zero.

The rest of the repository backs up that story. The package lives under antomnievo/, there is a skills/ directory, a visualizer/ directory that ships as a separate package, and a tests/ directory. The docs set includes a system design page, a workspace artifacts and attribution page, and a visualizer page, alongside quickstart, features, extensibility, and a page that states when to use it, which is a rare and welcome thing to find in a repository like this. Ruff is configured through ruff.toml, and the package is a pure Python build with no compiled extensions.

Installing the package and the optional extras

The distribution is named ant-omnievo, and the project version is 0.1.1. It requires Python 3.10 or newer, and the core runtime dependencies are small and specific:

dependencies = [
    "pydantic>=2.0",
    "httpx>=0.24.0",
    "tenacity>=8.0.0",
    "pyyaml>=6.0",
]

The build backend is setuptools with a wheel requirement, and the metadata notes a practical wrinkle worth knowing: the licence is declared in table form rather than the newer PEP 639 string form, because the CI build image caps at setuptools 68. Optional extras cover the rest. A dev extra brings pytest and pytest-asyncio. A rag extra covers the agentic RAG and LangGraph scenario with langchain-core, langchain-openai, langgraph, openai, and httpcore, and the file describes that scenario as experimental. The visualizer is a separate package under ./visualizer, which is not published, so it is installed from the local path:

uv pip install -e ".[visualizer]"
pip install -e ./visualizer

The comment in the metadata explains the split: uv reads the tool.uv.sources entry that points at the local path and installs from there, while pip cannot resolve the unpublished name, so the subpackage has to be installed directly. Whichever route you pick, the visualizer is not on PyPI under that name.

The README points to a quickstart document for the first run rather than printing commands inline, so the exact invocation sequence lives in docs/quickstart.md, with a Chinese version alongside it.

Where the framework stops, and what it refuses to do

Several boundaries are worth stating plainly.

The first is the evaluation requirement. The loop only works if you can run your system on an instance and score the output, cheaply and repeatably. A system that needs a human in the loop to judge quality, or an evaluation that costs more than the run, does not fit the shape the framework assumes. The README states this precondition rather than hiding it.

The second is that the initial artifacts still have to exist and still have to be reasonable. The framework is handed an initial set of tunable artifacts and a starting point, and the first candidate is a rewrite of what you gave it. If the seed is a blank skill file with a vague description, the Proposer has nothing to build on.

The third is maturity. The project version is 0.1.1 and the repository has no GitHub releases, so there is no changelog of published versions to track, and the paper is the primary published artefact, titled Mara Chain: Rethinking Failure as a Stepping Stone for AI System Auto-Evolution. The last push to the repository was on 2026-10-19, so the code is moving, but a 0.1.x package with a single design paper behind it is early by any reasonable measure. The licence is Apache-2.0, and a LEGAL.md carries a legal disclaimer.

Against hand-tuning and against a conventional A/B harness

The obvious alternative is what most teams do today: run the system, read the failure cases, and edit the skill file or the prompt yourself. The difference in approach is where the loop lives. In the manual path, a human reads failures, forms a hypothesis, edits, and re-runs, and the bottleneck is human attention. AntOmniEvo keeps the same edit semantics, since the Proposer lands a change as files the way a human would, but it parallelises the hypothesise, edit, evaluate cycle and keeps a population of candidates rather than a single current version, with selection and elimination handled for you.

The other alternative is a conventional experiment harness: a test suite, a set of candidate prompts or configs, a script that runs each against a fixed dataset, and a dashboard that reports the scores. That is closer in shape to what this framework does than the manual path is, and the differences are about direction and cost. A conventional harness measures variants you thought of. This framework proposes variants from observed failures, which is the part a human does not scale, and it pays for that by needing a proposer agent on every iteration. It also persists a change lineage, so a change can be traced to the failure that motivated it, which most harness setups do not record.

If you only have three candidate prompts, a spreadsheet, and a fixed test set, a harness is the cheaper and more predictable route. The framework pays for itself when the space of possible edits is too large for a person to enumerate and the evaluation is cheap enough to run many times.

Editorial conclusion

Adopt AntOmniEvo if you have a system whose tunable parts are already files, a repeatable evaluation, and a scoring function you trust, because the framework is built around exactly that shape. Do not adopt it for a system you cannot evaluate cheaply, or as a replacement for writing the first version of the artifact yourself. Verify first that your Evaluator output and eval data are stable, since the framework optimizes whatever signal you give it.

Frequently asked questions

Official sources

1. ant-research/AntOmniEvo on GitHub
2. Issues
3. License: Apache-2.0
4. README