AVO — Agentische Variationsoperatoren

Eine offene Reproduktion von AVO: Agentic Variation Operators for Autonomous Evolutionary Search (Chen, Ye, Xu et al., NVIDIA, 2026), lauffähig auf einem Laptop.

Klassische evolutionäre Suche und die darauf folgenden LLM-erweiterten Systeme zerlegen den Variationsoperator in eine feste Pipeline:

Vary(P_t) = Generate(Sample(P_t))

Das Framework sampelt Eltern; das Modell erzeugt einen Kandidaten aus ihnen. AVO ersetzt diese gesamte Zerlegung durch einen einzigen autonomen Agentenlauf:

Vary(P_t) = Agent(P_t, K, f)

Der Agent sieht die vollständige Linie P_t, eine Wissensbasis K und die Bewertungsfunktion f — und entscheidet selbst, was er liest, was er ändert und wann er misst. Er ist kein Kandidatengenerator mehr, sondern wird zum Variationsoperator.

Dieses Repository implementiert dieses Framework sowie die dazugehörige Infrastruktur, die das Papier beschreibt: eine git-gestützte Linie, einen korrektheitsgeprüften Bewertungsvektor, die Commit-Policy „matches-or-improves“, einen Supervisor, der bei Stagnation eingreift, und Trajektorien-Plots. Zwei Optimierungsziele sind enthalten.

Der entscheidende Teil: Es läuft in der Sitzung, die du bereits hast

Der Standard-Treiber startet keinen Agenten und ruft keine API auf. Er übergibt den Variations-Prompt an die Claude-Code-Sitzung, mit der du bereits sprichst, und diese Sitzung erledigt die Arbeit. Es wird nichts extra abgerechnet, kein ANTHROPIC_API_KEY wird benötigt, und der Agent, der optimiert, ist ein echter Allzweck-Code-Agent — genau das, was das Papier verwendet hat.

Der unbeaufsichtigte Modus (einen Agenten pro Schritt starten und tagelang laufen lassen, wie das 7-Tage-Experiment des Papiers) ist ebenfalls verfügbar und ist genau deshalb opt-in, weil er Kontingent verbraucht.

Related MCP server: AgentPrism Workflows

Installation

git clone https://github.com/gatordevin/avo
cd avo
pip install -e ".[all]"     # or: pip install -e .  for the core only
avo doctor

Auf einem System mit extern verwaltetem Python (Homebrew, die meisten Linux-Distributionen) verwende eine virtuelle Umgebung — das Flag --system-site-packages nutzt ein bereits vorhandenes NumPy und Matplotlib wieder:

python3 -m venv --system-site-packages .venv
.venv/bin/pip install -e ".[all]"
.venv/bin/avo doctor

Anforderungen: Python 3.10+, git und ein C-Compiler, falls du das Ziel attention_c verwenden möchtest. numpy wird von den gebündelten Zielen benötigt, matplotlib für Plots. Das Kernframework hängt nur von PyYAML ab.

Schnellstart — steuere es über den Agenten, den du bereits hast

Das vollständige Protokoll, einschließlich Codex und reiner CLI-Nutzung, findest du in docs/DRIVING.md.

Claude Code

Registriere den MCP-Server einmal auf Benutzerebene, damit er in jedem Ordner verfügbar ist:

claude mcp add avo -s user -- python3 -m avo.mcp_server
# from a virtualenv, point at its interpreter:
claude mcp add avo -s user -- /path/to/avo/.venv/bin/python -m avo.mcp_server

claude mcp list sollte avo — ✔ Connected anzeigen. Optional kannst du die gebündelte Fähigkeit installieren, damit /avo überall funktioniert:

cp -r .claude/skills/avo ~/.claude/skills/avo

Dann in einer Claude-Code-Sitzung in einem beliebigen Verzeichnis:

Verwende die avo-Tools, um das game2048-Ziel für 10 Schritte zu evolvieren. Rufe avo_start_run auf, dann die Schleife: avo_next_step, erledige die Arbeit, die es verlangt, avo_evaluate, bis du zufrieden bist, dann avo_submit. Wenn es einen Stillstand meldet, rufe avo_supervisor_brief auf, beantworte es und lege es mit avo_record_supervisor ab.

Die elf Tools sind die gesamte Schleife:

Codex

Codex CLI spricht MCP und liest AGENTS.md, also funktionieren beide Teile:

codex mcp add avo -- python3 -m avo.mcp_server

AGENTS.md im Repository-Stamm dokumentiert die Schleife und die Regeln, die einen Lauf ehrlich halten; Codex übernimmt sie automatisch, wenn es in diesem Verzeichnis arbeitet.

Ohne MCP

Jedes Tool hat einen CLI-Zwilling, sodass eine einfache Shell genauso gut funktioniert — das ist die portabelste Option und funktioniert mit jedem Agenten oder von Hand:

avo start --target game2048          # seeds x0 and prints the first prompt
# ... edit runs/<id>/work/, run runs/<id>/avo-eval as often as you like ...
avo submit -m "expectimax depth 2 with a positional weight matrix"
avo prompt                           # the next step's prompt
avo status
avo plot -o trajectory.png

Durchgeführte Läufe

Zwei vollständige Läufe sind im Repository enthalten, beide im Sitzungsmodus von einer Claude-Code-Sitzung gesteuert, beide einschließlich ihrer Sackgassen.

attention_decode — den Vendor-Kernel schlagen

examples/attention-decode-run/ evolviert den Dekodierschritt der Aufmerksamkeit: ein Query-Token gegen einen langen KV-Cache, die Berechnung, die ein LLM für jedes generierte Token ausführt. Bewertet gegen mx.fast.scaled_dot_product_attention — Apples eigenen fusionierten Metal-Kernel.

0,05 → 1,14× MLX in drei Schritten. Das ist der Lauf, bei dem der evolvierte Kernel tatsächlich die Vendor-Implementierung schlägt, und das Interessante ist wie:

• Schritt 1 war Implementierung — Split-K-Flash-Decoding brachte den Kernel von 1,6 GB/s auf 106 GB/s, etwa 95 % des Streaming-Limits der Maschine. Das erreichte 0,95× MLX und erschöpfte den Hebel: Man kann Bytes nicht schneller lesen, als der Speichercontroller sie liefert.

• Schritt 2 war Mathematik. Das Tor des Ziels ist ein Ausgabefehlerbudget und keine exakte Gleichheit, sodass die Suche die Berechnung ändern konnte. Messungen zeigten, dass 99,9 % der Softmax-Masse in ~11 % der Schlüssel sitzt, also bewertet der Kernel jetzt jeden Schlüssel, liest aber V nur oberhalb eines Schwellenwerts, der so abgeleitet ist, dass die verworfenen Masse nachweislich unter 0,3 % liegt. Das überschritt 1,0 und verbrauchte 2 % des Fehlerbudgets.

Die Lektion verallgemeinert sich: Sobald ein bandbreitenbegrenzter Kernel an der Roofline ist, bleibt nur noch der Hebel, weniger Bytes zu lesen, und das ist eine algorithmische Änderung.

Lies den vollständigen Bericht →

attention_c — die eigene Domäne des Papiers

examples/attention-c-run/ evolviert einen Forward-Attention-Kernel in C und erreicht 2,2× eine einfache NumPy/BLAS-Implementierung und nahe der NEON-Roofline. Beachte die ehrliche Einordnung: Diese Baseline ist keine getunte Attention-Bibliothek, und dieser Kernel ist langsamer als torchs CPU-SDPA und MLX — Apples AMX-Matrixeinheiten sind aus portablem C nicht erreichbar. Der Bericht gibt den vollständigen Vergleich.

Drei Erkenntnisse daraus sind einen Klick wert:

• Der eigene Algorithmus des Papiers war hier die falsche Antwort. Ein FlashAttention-artiger getilter Kernel mit einem Streaming-Online-Softmax maß schlechter, zweimal. Bei diesen Größen passt ein ganzer Kopf in L2, also bringt Blockierung für Lokalität nichts, während die Pro-Block-Reskalierung reine Zusatzarbeit ist. Die Kosten sind arithmetisch, nicht speicherbezogen.

• -ffast-math bricht stillschweigend das Standard-Fast-exp, indem es algebraisch den Add-Magic-Konstanten-Rundungstrick aufhebt, von dem es abhängt. Das Korrektheitstor hat es bei einer N=3-Form erwischt; die Durchsatzzahl hätte es nie getan.

• Der Lauf erzwang eine Zielkorrektur. Rohe GFLOP/s auf einem Laptop zu bewerten, der andere Arbeit erledigt, ist keine Messung — identischer Code schwankte in zwanzig Minuten zwischen 44 und 76 GFLOP/s. eval.py misst jetzt eine NumPy/BLAS-Referenz im selben Prozess, verschachtelt mit dem Kandidaten, und bewertet das Verhältnis.

Lies den vollständigen Bericht →

game2048 — eine Spielstrategie evolvieren

examples/game2048-run/ ist ein vollständiger 8-Schritte-Lauf des Ziels game2048, im Sitzungsmodus von einer Claude-Code-Sitzung gesteuert. Das Verzeichnis enthält die unredigierte Ausgabe: die evolvierte Strategie, die Arbeitsnotizen des Operators, die vollständige Trajektorie, die Screening-Tools, die es gebaut hat, und seine Sackgassen.

876 → 43 826 — 50× der Startwert, 14× die stärkste Baseline. Spiele, die 2048 erreichen: 0 % → 77 %. Bestes Plättchen: 512 → 8192. Apple M5, einthreadig, nur Standardbibliothek.

Verbesserungen kommen in diskreten Sprüngen, getrennt durch Plateaus, was Abbildung 5 des Papiers entspricht. Die beiden flachen Versionen sind reine Durchsatzarbeit, die das Budget kaufte, das der nächste Schritt ausgab — dieselbe Rolle, die die v19→v20-Änderung ohne Verzweigung im Papier spielt.

Der größte einzelne Gewinn (+50,5 %) war keine Optimierung. Der Benchmark bewertete akkumulierte Spielpunkte; die Heuristik maß nur, wie überlebensfähig ein Brett aussah, also wusste nichts in der Suche, dass das Verschmelzen zweier 256er 512 Punkte einbringt. Vier Schritte Durchsatzarbeit waren zusammen +27 % wert; ein Schritt, der prüfte, was tatsächlich optimiert wurde, war +50 % wert.

Lies den vollständigen Bericht →

Was enthalten ist

game2048 — eine Spielstrategie evolvieren

Evolviere agent.py zum stärksten 2048-Spieler, den du kannst, unter einem harten Denkzeitbudget. Bewertet als geometrisches Mittel der mittleren Spielpunktzahl über vier Banken von zwölf deterministischen Seeds. Das Überschreiten des 120-s-Budgets ergibt null Punkte, nicht „etwas weniger“ — also stehen Suchtiefe, Bewertungsfunktionskosten und Beschneidung in Konkurrenz zueinander, und dieser Kompromiss ist das Problem.

Gemessen auf einem Apple M5:

Starke Expectimax-Spieler erreichen Punktzahlen in den Zehntausenden. Der oben durchgeführte Lauf erreichte 43 826.

attention_c — einen Kernel evolvieren, die eigene Domäne des Papiers

Evolviere einen Single-Precision-Forward-Attention-Kernel in C: O = softmax(QKᵀ/√D)V, kausal und nicht-kausal, D = 64. Geprüft auf Übereinstimmung mit einer Float64-Referenz über achtzehn Formen — einschließlich Primzahl- und Off-by-One-Sequenzlängen, sodass ein Kernel, der seinen Schwanz falsch behandelt, fehlschlägt, anstatt stillschweigend gut abzuschneiden.

Bewertet als Beschleunigung gegenüber einer NumPy/BLAS-Referenz, die im selben Prozess gemessen wird, geometrisches Mittel über vier Sequenzlängen × zwei Maskierungsmodi. 1,0 ist Parität mit der Bibliothek. Die Bewertung eines Verhältnisses anstelle roher GFLOP/s macht den Benchmark immun gegen alles, was die Maschine sonst tut — der absolute Durchsatz auf einem geteilten Laptop bewegt sich um mehr, als die meisten Optimierungen wert sind.

Die Wissensbasis deckt die Online-Softmax-Formulierung, Tiling und Blockgrößenauswahl, CPU-Vektorisierung, Threading und ab, wie man die Host-Maschine befragt, anstatt eine ISA anzunehmen. Um BLAS zu schlagen, braucht man die meisten davon.

So funktioniert es

Das Laufverzeichnis

runs/<run-id>/
  work/              the candidate x_t — a standalone git repo whose history IS the lineage
    .avo/scores.jsonl    every committed version's full score vector
  kb/                the knowledge base K, copied in so paths are stable
  avo-eval           f, as a zero-argument shim the agent can call at will
  NOTES.md           scratch space that survives across steps
  trajectory.jsonl   every step, accepted or rejected
  rejected/          the diff of each rejected candidate, kept for the record
  logs/              evaluator and agent logs

Die Linie als Git-Repository zu führen bedeutet, dass der Agent P_t mit Tools inspiziert, die er bereits kennt — git log, git show v7:attention.c, git diff v6 v7 — anstatt einer maßgeschneiderten API. Jede akzeptierte Version ist ein Commit mit dem Tag vN, dessen Nachricht den Bewertungsvektor trägt.

Die Commit-Policy

Papier §3.2: Ein Kandidat wird nur dann committet, wenn er das Korrektheitstor besteht und die beste bisher committete Punktzahl erreicht oder verbessert. Alles andere wird zurückgesetzt und sein Diff archiviert — es bleibt Teil der internen Suchtrajektorie des Agenten, gelangt aber nie in die Linie.

Korrektheit ist ein Tor, keine Dimension. Ein Kandidat, der es nicht besteht, erhält null Punkte, unabhängig davon, was er gemessen hat (§3.1). In attention_c bedeutet das, dass ein Kernel, der 10× schneller und numerisch falsch ist, genau so viel wert ist wie einer, der nicht kompiliert.

Der Bewertungsvektor

f(x) = (f_1(x), …, f_n(x)) — eine Zahl pro Benchmark-Konfiguration, mit dem geometrischen Mittel als dem zu maximierenden Skalar. Das macht die Bewegung pro Konfiguration diagnostisch: Eine Änderung, die n1024 hilft und n128 schadet, ist ein blockierendes Problem, kein Gewinn, und das Aggregat allein würde es verbergen.

Der Supervisor

Paper §3.3: Lange autonome Läufe scheitern auf zwei Arten — der Agent stagniert, wenn er seine aktuelle Angriffslinie erschöpft hat, oder er gerät in unproduktive Zyklen von Bearbeitungen, die weiterhin fehlschlagen. Nach N Schritten ohne neues Bestes (Standard: 3) stoppt AVO und bittet um eine Umleitung: eine Überprüfung der gesamten Trajektorie, die mehrere konkrete, unterschiedliche Optimierungsrichtungen vorschlägt. Die Umleitung wird als starker Prior in den nächsten Variations-Prompt injiziert und von genau einem Schritt verbraucht.

Im Sitzungsmodus ist der Supervisor dieselbe Sitzung mit einem anderen Hut, was billig genug ist, um es tatsächlich zu nutzen. Im unbeaufsichtigten Modus ist es ein separater Agentenlauf mit Nur-Lese-Absicht.

Die Trajektorie

avo plot rendert die Abbildung 5/6 des Papers: das laufende beste geometrische Mittel als Treppenfunktion, gefüllte Kreise bei jedem neuen Bestwert, gepunktete Kurven pro Konfiguration und die Basislinien als horizontale Linien. Gleiche Einschränkung wie im Paper — es zeigt die committete Sequenz, nicht den internen Suchbaum, der zwischen Commits erkundet wird.

Unbeaufsichtigter Modus

Um das Setup des Papers zu reproduzieren, bei dem der Operator ein erzeugter Agent ist und niemand zusieht:

avo run --target attention_c --backend claude_cli --max-steps 40 --time 12h
avo run --resume runs/attention_c-20260321-091500 --time 24h

Backends: claude_cli (Claude Code headless — das nächste Analogon zum Agenten des Papers), api (eine eigenständige Agentenschleife auf der Messages API, für Leute mit nur einem API-Schlüssel), agent_sdk (in-process über claude-agent-sdk) und mock (ein Shell-Befehl, um die Maschinerie ohne Modell zu testen).

Dies verbraucht bei jedem Schritt Kontingent oder Guthaben. Der Sitzungsmodus tut das nicht.

Hinzufügen eines eigenen Ziels

Ein Ziel ist ein Verzeichnis mit einer target.yaml, einem Seed-Programm, einer Wissensbasis und einem Evaluator. Der Evaluator ist eine beliebige ausführbare Datei in beliebiger Sprache; der gesamte Vertrag ist ein JSON-Objekt auf stdout:

{"correct": true,
 "metrics": {"config_a": 1520.3, "config_b": 1477.0},
 "error": null,
 "notes": "shown to the agent"}

correct ist das Tor. metrics ist der Score-Vektor. Der zu optimierende Skalar ist ihr geometrisches Mittel, es sei denn, Sie liefern ein explizites primary.

name: my_target
description: One line, shown in `avo targets`.
seed: seed                 # copied to work/ as x_0
knowledge_base: kb         # copied to the run dir as K
entrypoint: kernel.c       # informational, used in prompts

evaluate:
  command: ["python3", "{target}/eval.py", "--workdir", "{workdir}"]
  timeout: 30m

baselines:                 # optional, measured once before evolution starts
  command: ["python3", "{target}/eval.py", "--baselines"]

score:
  direction: maximize

agent:
  goal: |
    What the agent is actually trying to do, and what the trade-offs are.

Siehe docs/TARGETS.md für den vollständigen Vertrag und tests/fixtures/toy/ für ein minimales funktionierendes Beispiel.

Die Wissensbasis ist echte Mühe wert. Sie ist das K in Agent(P_t, K, f), und der Unterschied zwischen einem Agenten, der Tiling aus ersten Prinzipien über zehn Schritte neu entdeckt, und einem, der in zwei Schritten dorthin gelangt.

Was originalgetreu ist und was nicht

Originalgetreu:

• die Operator-Formulierung Vary(P_t) = Agent(P_t, K, f) — ein echter Codier-Agent mit Dateibearbeitung, Shell-Zugriff und persistentem Speicher, ohne aufgabenspezifische Modifikationen

• einlinige kontinuierliche Evolution mit git-gestütztem Zustand (§3.3)

• das Korrektheits-Tor und der n-dimensionale Score-Vektor (§3.1)

• die Commit-Richtlinie „matches-or-improves“ (entspricht oder verbessert), wobei fehlgeschlagene Versuche von der Linie ausgeschlossen sind (§3.2)

• Supervisor-Eingriff bei Stagnation und unproduktiven Zyklen (§3.3)

• geometrische Mittelwert-Aggregation über Benchmark-Konfigurationen und Trajektorien-Diagramme aus Abbildung 5/6

Nicht originalgetreu, und das bewusst:

• Die Hardware. Das Paper evolviert Aufmerksamkeits-Kernel auf B200 GPUs gegen cuDNN und FlashAttention-4. attention_c ist dasselbe Problem auf einer CPU gegen NumPy/BLAS. Die Optimierungen übertragen sich in der Art (Tiling, Online-Softmax, Vektorisierung, Scheduling), nicht im Ausmaß.

• Der Umfang. Das Paper lief 7 Tage, 40 committete Versionen, 500+ erkundete Richtungen. Ein Lauf im Sitzungsmodus mit 10–20 Schritten ist eine Demonstration, keine Replikation.

• Populationsstruktur. Wie im Paper wird hier der Einlinien-Fall implementiert, um den Operator zu isolieren. Archiv- und inselbasierte Regime sind mit der Formulierung kompatibel, aber nicht implementiert.

Repo-Struktur

src/avo/
  types.py        Score, LineageEntry, the correctness gate, geomean
  config.py       target specs and run configuration
  lineage.py      P_t as git history
  scoring.py      f as an external process
  knowledge.py    K
  prompts.py      the variation and supervisor prompts — the whole framework/agent interface
  run.py          run state: seed, evaluate, commit policy, trajectory
  session.py      driver: the session you already have is the operator
  loop.py         driver: unattended, spawns an agent per step
  mcp_server.py   the same operations as MCP tools (no dependencies)
  cli.py          the same operations as subcommands
  plot.py         Figure 5/6
  agents/         backends for unattended mode
targets/
  game2048/       policy evolution under a time budget
  attention_c/    kernel evolution — the paper's domain, on a CPU
examples/
  attention-decode-run/  beats Apple's own fused kernel by changing the maths
  attention-c-run/       CPU kernel evolution, with an honest baseline caveat
  attention-metal-run/   GPU prefill — every CUDA instinct measured worse
  game2048-run/          policy evolution — 50x the seed
docs/
  PAPER_MAP.md    every section of the paper, and where it lives in the code
  TARGETS.md      the evaluator contract
  DRIVING.md      how to drive a run from Claude Code, Codex, or a shell
AGENTS.md         cross-agent instructions (read automatically by Codex)
.claude/skills/   the `/avo` skill for Claude Code

Zitieren

Dies ist eine unabhängige Reproduktion. Zitieren Sie das Originalwerk:

@article{chen2026avo,
  title  = {AVO: Agentic Variation Operators for Autonomous Evolutionary Search},
  author = {Chen, Terry and Ye, Zhifan and Xu, Bing and Ye, Zihao and Liu, Timmy
            and Hassani, Ali and Chen, Tianqi and Kerr, Andrew and Wu, Haicheng
            and Xu, Yang and Chen, Yu-Jung and Chen, Hanfeng and Kane, Aditya
            and Krashinsky, Ronny and Liu, Ming-Yu and Grover, Vinod and Ceze, Luis
            and Bringmann, Roger and Tran, John and Liu, Wei and Xie, Fung
            and Lightstone, Michael and Shi, Humphrey},
  journal = {arXiv preprint arXiv:2603.24517},
  year    = {2026}
}

Lizenziert unter Apache-2.0. Nicht verbunden mit oder unterstützt von NVIDIA.