optim-agent

Agentische Systemoptimierung mit Coding Agents.
Automatisiert die iterative Parameterabstimmung eines Algorithmus-Engineers.

English | 简体中文 | 日本語 | 한국어 | Français | Deutsch | Español | Português | Русский

optim-agent lässt Claude Code / Codex / OpenCode echte Systemparameter abstimmen, indem es Code liest, Trials vorschlägt und gemessene Objective-Ergebnisse aufzeichnet. Nutzen Sie es, wenn Ihr System konfigurierbare Parameter und ein messbares Objective bietet. Es verbindet die Bedeutung jedes Parameters mit den Signalen aus der Trial-Historie und schlägt die nächste zu bewertende Konfiguration vor. Objective-Auswertungen bleiben maßgeblich: optim-agent schlägt Werte vor, validiert sie gegen den deklarierten Raum, zeichnet Ergebnisse auf und fällt bei ungültigen Agent-Antworten auf sicheres Sampling zurück.

Modelle	Systeme	Forschung
Training, Architekturen und RL-Experimente	Inferenz, Latenz, Kosten, Steuerung und Entscheidungsregeln	Quant-Signale, Simulationen und wissenschaftliche Workflows

Warum optim-agent

• Semantische Vorschläge - Coding Agents nutzen Parameterbedeutungen, Kontext und beobachtete Ergebnisse, statt jede Dimension als anonyme Koordinate zu behandeln.
• Hebel bei kleinem Budget - hilfreich, wenn Evaluierungen teuer sind und klassische Surrogate noch zu wenig Daten haben.
• Agent-CLI-Potenzial - die Vorschlagsqualität kann mit besseren Coding Agents steigen, etwa von GPT-5.5 zu GPT-5.6, ohne Optimierungscode zu ändern.
• Auditierbare Entscheidungen - JSON/SQLite-Studies behalten Konfigurationen, Ergebnisse, Zustände, Kontext und optionale Agent-Begründungen.
• Begrenzte Ausführung - der Agent schlägt nur Werte vor; optim-agent validiert sie gegen den Suchraum, ungültige Ausgaben fallen auf sicheres Sampling zurück.

Installation

Codex Skill installieren:

$skill-installer install https://github.com/Optim-Agent/optim-agent

Claude Code Plugin installieren:

claude plugin marketplace add Optim-Agent/optim-agent && claude plugin install optim-agent@optim-agent

Python-Paket installieren:

# Stabile Version von PyPI
python -m pip install optim-agent

# Neuester Quellstand von GitHub
python -m pip install "optim-agent @ git+https://github.com/Optim-Agent/optim-agent.git"

Erfordert mindestens eine authentifizierte Agent CLI in PATH: claude, codex oder OpenCode.

Schnellstart

import optim_agent as oa

def objective(trial):
    threshold = trial.suggest_float(
        "threshold", 0.05, 0.95,
        context="decision threshold; higher values trade recall for precision",
    )
    budget = trial.suggest_int(
        "budget", 10, 200, log=True,
        context="compute or operating budget; larger values may improve quality",
    )
    return evaluate_system(threshold=threshold, budget=budget)  # domain code

study = oa.create_study(
    direction="maximize",
    sampler=oa.AgentSampler(
        backend="claude",  # or "codex" / "opencode"
        effort="high",
        context="maximize system quality under a strict operating-cost budget",
        history=5,
        explicit_reasoning=True,
        qualitative_notes=True,
    ),
    storage="study.json",  # optional: persist and resume
    summarize=True,  # optional: agent-written result summary after the last trial
)
study.optimize(objective, n_trials=20)
print(study.best_value, study.best_params)
print(study.summary)  # the summary agent's narration of the finished study

Optionaler context gibt Study und Parametern fachliche Bedeutung. Setzen Sie ihn auf Study-Ebene mit AgentSampler(context=...), pro Parameter mit suggest_*(..., context=...) oder beides.

Sie können auch examples/quickstart.py ausführen oder tutorials/quickstart.ipynb nutzen.

Einsatzgebiete

Bereich	Parameter, die optim-agent abstimmen kann	Beispiel-Objective
Modelltraining	Lernraten, Architekturen, Augmentation, Regularisierung	Validierungsqualität, Rechenaufwand, Robustheit
Inferenz und Serving	Quantisierung, Batching, Decoding, Caching, Routing	Qualität, Latenz, Durchsatz, Kosten
Quantitative Forschung	Signal-Fenster, Schwellen, Rebalancing-Regeln, Risikokontrollen	Walk-forward Return, Drawdown, Turnover
RL und Entscheidungen	Objective-Gewichte, Explorationspläne, Umgebungssettings, Policy-Schwellen	Return, Sicherheit, Sample Efficiency
Wissenschaftliche Workflows	Simulationseingaben, Solver-Settings, Experimentkontrollen	Fit, Fehler, Laufzeit, Ressourcen
Black-box-Systeme	jede begrenzte kategoriale, ganzzahlige oder kontinuierliche Konfiguration	skalarer Objective-Score

Weitere Beispiele: examples/sklearn_tuning.py und examples/inference_tuning.py.

Bei Reinforcement Learning stimmt optim-agent das System um den Lernloop herum ab; es ersetzt nicht den Policy-Learning-Algorithmus.

Optimierungstrajektorie

Diese Seed-0-Branin-Trajektorie vergleicht TPE und GPT-5.5 mit demselben 10-Trial-Budget und zeigt die incumbent Objective-Werte nach jedem Trial. Sie ist eine Trajektorien-Illustration; aggregierte Benchmark-Ergebnisse und Reproduktionsbefehle folgen.

Mathematische Funktionen ohne Kontext optimieren: Branin-2D und Ackley-5D

Hard-function Agents erhalten keinen bereitgestellten Task-Kontext: nur generische Parameternamen x1...x5, numerische Grenzen und Trial-Historie. Runs verwenden 10 Trials über fünf Seeds; Random und TPE sind unveränderte Baselines.

Top-tier Agents

Methode	mean best Branin ↓	mean best Ackley-5D ↓
Random	5.008	19.639
TPE	11.395	18.843
GPT-5.5	1.326	3.960
Opus-4.8	0.398	0.061
Sonnet-5	3.850	0.143
Kimi-K3	2.082	0.907
Minimax-M3	0.970	0.574
GLM-5.2	3.609	15.023

Die fixierten Modelle sind gpt-5.5, claude-opus-4-8, claude-sonnet-5, kimi-k3, MiniMax-M3 und glm-5.2. Opus-4.8 erreicht den Branin-Optimumbereich im Mittel und hat den stärksten fünf-Seed-Ackley-Mittelwert.

OpenCode Agents (Free)

Methode	mean best Branin ↓	mean best Ackley-5D ↓
Random	5.008	19.639
TPE	11.395	18.843
Big-pickle	4.734	15.951
DeepSeek-V4-Flash	4.410	4.608
Nemotron-3-Ultra	16.051	18.459
MiMo-v2.5	3.682	15.597

OpenCode-gehostete Modelle benötigen keine kostenpflichtige Modell-API. Der kostenlose Pool rotiert; dieser Refresh pinnt opencode/big-pickle, opencode/deepseek-v4-flash-free, opencode/nemotron-3-ultra-free und opencode/mimo-v2.5-free. DeepSeek V4 Flash hat den stärksten Free-model-Ackley-Mittelwert, MiMo-v2.5 den stärksten Free-model-Branin-Mittelwert.

ResNet-Bildklassifikatoren tunen: MNIST und CIFAR-10

Der Klassifikationsbenchmark vergleicht Random, Optuna TPE, GPT-5.5 w/ context und GPT-5.5 w/o context über fünf Seeds (0..4) und 10 Trials. Die Kontextbedingung erhält natürlichsprachliche Study- und Parameterbeschreibungen; die No-context-Bedingung nur Grenzen und Trial-Historie.

Die Hauptmetrik betont schnelle Verbesserung:

cumulative_best_so_far_error = sum(best_test_error_so_far_at_i for i in 1..10)

Niedriger ist besser.

Methode	MNIST cumulative error ↓	MNIST final error ↓	CIFAR-10 cumulative error ↓	CIFAR-10 final error ↓
Random	9.174	0.648%	278.920	25.072%
TPE	7.166	0.580%	279.936	25.596%
GPT-5.5 w/ context	5.668	0.506%	220.994	21.322%
GPT-5.5 w/o context	8.910	0.632%	281.466	25.960%

GPT-5.5 w/ context senkt den cumulative best-so-far error um 20.9% gegenüber TPE auf MNIST und um 20.8% gegenüber Random auf CIFAR-10. Ohne Kontext ist es auf MNIST 24.3% schlechter als TPE und auf CIFAR-10 0.9% schlechter als Random.

examples/mnist.py und examples/cifar10.py tunen Lernrate, Batchgröße, Weight Decay, Label Smoothing, drei Stage-Breiten, drei Stage-Tiefen und vier Dropout-Kontrollen. MNIST ergänzt Translation und Rotation; CIFAR-10 nutzt Crop Padding und Flip Probability.

Q-learning Controller tunen: Acrobot-v1 und LunarLander-v3

Dieser CPU-only Gymnasium Benchmark tuned einen diskretisierten Q-learning Controller für Acrobot-v1 und LunarLander-v3. Jede Methode läuft 20 Trials über fünf Seeds (0..4); das Objective ist der mittlere Evaluierungs-Return, also ist höher besser. Der Runner parallelisiert über Seeds und innerhalb jeder HPO-Study via --workers. Die GPT-5.5-Arme nutzen high modeling effort und die letzten 5 Trials Historie.

Methode	Acrobot-v1 Return ↑	LunarLander-v3 Return ↑
Random	-200.000	-62.139
TPE	-199.900	-72.088
GPT-5.5 w/ context	-199.700	-50.825
GPT-5.5 w/o context	-199.100	-59.751

Mit 20 Trials und fünf Trial-Historie im Prompt hat GPT-5.5 w/ context den stärksten mittleren Return in beiden Umgebungen: 0.2 über TPE auf Acrobot-v1 und 11.3 über Random auf LunarLander-v3. Behandeln Sie dies als CPU-HPO-Stresstest, nicht als universelles Ranking.

Für die Animation tuned optim-agent sieben Gains eines deterministischen LunarLander Controllers mit einem HPO-Seed. Jeder Trial läuft auf denselben 20 Rollout-Seeds, priorisiert erfolgreiche Landungen und danach mittleren Return. Der ausgewählte Trial landete in allen 20 Rollouts; das GIF zeigt seinen Rollout mit dem höchsten Return.

Gradient-Boosting-Klassifikator tunen: Kreditausfallwahrscheinlichkeiten

Dieser CPU-only Benchmark tuned acht Trainingsparameter eines HistGradientBoostingClassifier auf dem UCI-Datensatz Default of Credit Card Clients: 30.000 Zeilen, 23 Merkmale und Ziel "Default im nächsten Monat". Das offizielle Archiv ist per SHA-256 gepinnt, CC BY 4.0 lizenziert und einmal in 60% Train, 20% Validation und 20% untouched Test aufgeteilt. Alle Methoden nutzen dieselbe Aufteilung, 20 Trials und Seeds 0..4. Beide GPT-5.5-Arme verwenden high modeling effort, 20 Trials Prompt-Historie, explicit reasoning und qualitative notes.

Methode	finaler Validierungs-Log-Loss ↓	held-out Test-Log-Loss ↓
Random	0.433	0.425
TPE	0.430	0.422
GP-BO	0.430	0.423
GPT-5.5 w/ context	0.428	0.422
GPT-5.5 w/o context	0.433	0.427

Kontext senkt den finalen Validierungs-Log-Loss um 1,13% und den Test-Log-Loss um 1,23% gegenüber der passenden No-context-Kontrolle. GPT-5.5 hat auch niedrigeren mittleren Validierungs- und Test-Loss als Random, TPE und GP-BO. Da die behaltene Konfiguration mit Validation und Test Loss gewählt wurde, ist das Testergebnis ein Benchmarkvergleich und keine unberührte Generalisierungsschätzung.

Dies ist ein methodischer Benchmark, kein produktives Kreditentscheidungssystem. Deployment bräuchte Fairness, Kalibrierung, Drift, Governance und juristische Prüfung.

Benchmark-Artefakte reproduzieren:

pip install -e ".[examples]"

# Classification
python scripts/verify_classification_cumulative_error.py run-no-context
python scripts/verify_classification_cumulative_error.py

# Hard functions
python examples/hard_functions.py distributed \
  --agents Random TPE GPT-5.5 Opus-4.8 Sonnet-5 GLM-5.2 Big-pickle \
  DeepSeek-V4-Flash Nemotron-3-Ultra MiMo-v2.5 \
  --trials 10 --seeds 0 1 2 3 4
cp ~/.claude/settings-kimi.json ~/.claude/settings.json
python examples/hard_functions.py distributed --agents Kimi-K3 --trials 10 --seeds 0 1 2 3 4
cp ~/.claude/settings-minimax.json ~/.claude/settings.json
python examples/hard_functions.py distributed --agents Minimax-M3 --trials 10 --seeds 0 1 2 3 4
python examples/hard_functions.py plot

# Credit-card HGB
pip install -e ".[ml,examples]"
python examples/credit_card.py download
python examples/credit_card.py preflight
python examples/credit_card.py run
python examples/credit_card.py selfcheck
python examples/credit_card.py summary
python examples/credit_card.py plot

# RL control
pip install -e ".[rl,examples]"
python examples/rl_control.py preflight
python examples/rl_control.py run --seeds 0 1 2 3 4 --workers 10
python examples/rl_control.py selfcheck
python examples/rl_control.py summary
python examples/rl_control.py plot
python examples/rl_control.py gif

Nutzungsleitfaden

Sampler Prompt Controls

effort wird an das reasoning-effort-Flag der Backend-CLI weitergereicht. Der Harness-Prompt wird separat gesteuert:

oa.AgentSampler(
    backend="codex",
    effort="medium",
    history=5,
    explicit_reasoning=True,
    qualitative_notes=True,
)

Setzen Sie history=None, um alle abgeschlossenen/geprunten Trials zu zeigen. Nutzen Sie explicit_reasoning=False oder qualitative_notes=False für kürzere Agent-Antworten.

Trial-Logging

study.optimize(..., verbose=...) steuert die Ausgabe pro Trial:

• verbose=True (Standard) zeigt auf einem interaktiven Terminal eine Tabelle: eine Zeile pro Trial mit den Spalten trial, value, best, state sowie je einer Spalte pro Suchraum-Parameter in Reihenfolge des ersten Auftretens. Lange Zeilen werden mit Ellipse auf die Terminalbreite gekürzt; fehlende Werte (z. B. fehlgeschlagene Trials) erscheinen als -.
• Ist stdout kein TTY (gepipe­te Ausgabe, CI-Logs), fallen verbose=True / "table" automatisch auf das greppbare Einzeilenformat zurück ([optim-agent] trial 3: value=0.91 state=complete best=0.91).
• verbose="line" nutzt immer das Einzeilenformat, auch auf einem TTY.
• verbose="table" nutzt die Tabelle auf einem TTY und das Einzeilenformat bei gepipe­ter Ausgabe.
• verbose=False deaktiviert die Trial-Ausgabe.

Bei define-by-run-Suchräumen druckt ein Trial mit einem neuen Parameter-Schlüssel den Header mit der Obermenge der Spalten erneut.

Summary Agent

Übergeben Sie summarize=True an create_study, damit der Agent die abgeschlossene Study einmal nach dem letzten Trial zusammenfasst:

study = oa.create_study(
    sampler=oa.AgentSampler(backend="claude"),
    storage="study.json",
    summarize=True,
)
study.optimize(objective, n_trials=20)
print(study.summary)  # wird auch in JSON-/SQLite-Storage persistiert

Die Zusammenfassung ist in vier Abschnitte gegliedert — beste Konfiguration, Suchraum-Erkenntnisse, Trajektorien-Highlights und empfohlene nächste Schritte. Sie wird im Terminal ausgegeben und auf study.summary persistiert (additiver Schlüssel im JSON-Storage und in der SQLite-meta-Tabelle; alte gespeicherte Studies laden mit summary=None).

Backend-Auflösung: Ein explizites summary_backend= hat Vorrang; sonst wird das Backend des Samplers wiederverwendet, wenn der Sampler ein AgentSampler ist. Bei jedem anderen Sampler übergeben Sie summary_backend=, sonst wirft create_study einen ValueError mit dem Hinweis auf die Lösung. summary_model= / summary_effort= überschreiben Modell/Effort des Samplers für die Zusammenfassung. Agent-Antworten, die nicht in alle vier Abschnitte geparst werden können, fallen auf die Ausgabe des Rohtexts zurück — eine Zusammenfassung lässt die Study nie fehlschlagen, und Studies ohne abgeschlossene Trials überspringen sie mit einem einzeiligen Hinweis. backend="mock" funktioniert auch für den Summarizer, sodass Demos und Tests ohne echte Agent-CLI laufen.

Pruning

study = oa.create_study(
    sampler=oa.AgentSampler(backend="codex"),
    pruner=oa.AgentPruner(
        backend="codex", level="medium", effort="medium",
    ),  # level: loose | medium | tight
)

def objective(trial):
    lr = trial.suggest_float("lr", 1e-5, 1e-1, log=True,
                             context="learning rate for training an image classifier")
    for epoch in range(20):
        loss = train_one_epoch(lr)
        trial.report(loss, epoch)
        if trial.should_prune():
            raise oa.TrialPruned()
    return loss

Der Pruner-Agent vergleicht die aktuelle Lernkurve mit abgeschlossenen Trials und antwortet prune/keep; loose pruned nur klar schwache Runs, tight pruned aggressiver. Agent-Fehler prunen nie einen Trial.

Nebenläufige und verteilte Studies

Setzen Sie max_concurrency (Standard 1), um mehrere Trials gleichzeitig zu evaluieren, und nutzen Sie eine SQLite-storage-Datei (.db / .sqlite) als nebenläufigkeitssichere gemeinsame Historie:

study = oa.create_study(
    sampler=oa.AgentSampler(backend="claude"),
    storage="study.db",        # SQLite -> safe for many workers; .json stays single-writer
    max_concurrency=8,         # up to 8 objectives run at once
)
study.optimize(objective, n_trials=100)

• Innerhalb eines Prozesses führt max_concurrency Objectives in einem Threadpool aus. Agent-Sampling-Queries werden seriell in eine Queue gelegt, damit jeder Vorschlag die Prozesshistorie sieht; nur Objective-Aufrufe laufen parallel.
• Über Prozesse/Maschinen hinweg zeigen alle Worker auf dieselbe SQLite-storage. Die Datenbank ist der Kommunikationskanal: WAL-Modus lässt Worker Ergebnisse anhängen und Historie lesen, ohne Schreibkonflikte.

Einschränkungen: Threads teilen den GIL, daher laufen pure-Python CPU-bound Objectives am besten in getrennten Prozessen mit geteilter SQLite Storage. Nebenläufige Worker sehen die in-flight Punkte der anderen nicht und können gelegentlich nahe Regionen prüfen.

Skill-Modus (Agent liest Projektcode)

Das pip-Paket behandelt das Objective als Black Box. Der optim-agent Skill geht weiter: In einer Coding-Agent-Session liest der Agent zuerst das Projekt, versteht die Rolle jedes Parameters und steuert denselben Study-Loop über study.ask(params) / study.tell(trial, value), wobei das Study-JSON Historie über Sessions hält.

$skill-installer install https://github.com/Optim-Agent/optim-agent

Claude Code Plugin:

claude plugin marketplace add Optim-Agent/optim-agent
claude plugin install optim-agent@optim-agent

Codex Plugin:

codex plugin marketplace add Optim-Agent/optim-agent
codex plugin add optim-agent@optim-agent

trial = study.ask({"threshold": 0.72, "budget": 80})
study.tell(trial, evaluate_system(**trial.params))

Offline Testing

AgentSampler(backend="mock") ist ein tokenfreier Ersatz, der um den besten Punkt hill-climbt, um Integrationen vor echten Agent Calls zu testen.

Fehlerbehebung

• claude gibt 401 in einer Agent-Session zurück - verschachtelte Sessions erben ANTHROPIC_API_KEY; starten Sie mit env -u ANTHROPIC_API_KEY oder aus einer sauberen Shell.
• Ein Backend Call läuft in ein Timeout oder liefert ungültige Ausgabe - der Sampler warnt und fällt für diesen Trial auf einen Random Point zurück; die Study läuft weiter.
• OpenCode mit verteilten Studies - OpenCode currently does not support distributed computing in optim-agent; nutzen Sie den Single-Process-Workflow oder ein anderes Backend.

Mitwirken

Lokale Entwicklung:

pip install -e ".[examples]"
pytest                     # runs tests/test_optim_agent.py

Bitte größere Änderungen vor einem PR in einem Issue besprechen. Einen neuen Agent Backend hinzuzufügen heißt meist: eine kleine Funktion in optim_agent/agent.py.

Die englische README.md bleibt die maßgebliche Quelle für Versionen, Benchmarkwerte und Backends.

Danksagung

• Optuna für die Verbreitung der Study/Trial-Schnittstelle, die TPE-Baseline in Beispielen und Benchmarks und den hohen Standard für praktische Optimierungstools.
• OpenCode für den Zugang zu den kostenlosen Modellen in den Hard-function Benchmarks.

Lizenz

MIT