optim-agent

Optimisation agentique de systèmes avec des agents de code.
Automatise le travail itératif de réglage de paramètres d'un ingénieur algorithme.

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

optim-agent permet à Claude Code / Codex / OpenCode de régler de vrais paramètres système en lisant votre code, en proposant des trials et en enregistrant les résultats objectifs mesurés. Utilisez-le quand votre système expose des paramètres configurables et un objectif mesurable. Il combine ce que chaque paramètre signifie avec ce que l'historique des trials montre, puis propose la configuration suivante à évaluer. Les évaluations objectives restent l'autorité : optim-agent propose des valeurs, les valide contre l'espace déclaré, enregistre les résultats et revient à un échantillonnage sûr quand une réponse d'agent est invalide.

Modèles	Systèmes	Recherche
Entraînement, architectures et expériences RL	Inférence, latence, coût, contrôle et règles de décision	Signaux quantitatifs, simulations et workflows scientifiques

Pourquoi optim-agent

• Propositions sémantiques - les agents de code raisonnent sur le sens des paramètres, le contexte et les résultats observés au lieu de traiter chaque dimension comme une coordonnée anonyme.
• Effet de levier avec petit budget - utile quand les évaluations sont coûteuses et que les surrogates classiques manquent encore de données.
• Potentiel des Agent CLI - la qualité des propositions peut progresser avec les agents de code sous-jacents, par exemple de GPT-5.5 à GPT-5.6, sans changer le code d'optimisation.
• Décisions auditables - les studies JSON/SQLite conservent configurations, résultats, états, contexte et justification optionnelle de l'agent.
• Exécution bornée - l'agent ne propose que des valeurs ; optim-agent les valide contre l'espace déclaré et revient à un échantillonnage sûr si la sortie est invalide.

Installation

Installer le Codex skill :

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

Installer le plugin Claude Code :

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

Installer le package Python :

# Version stable sur PyPI
python -m pip install optim-agent

# Dernière version source sur GitHub
python -m pip install "optim-agent @ git+https://github.com/Optim-Agent/optim-agent.git"

Nécessite un agent CLI authentifié dans PATH : claude, codex ou OpenCode.

Démarrage rapide

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

Le context optionnel donne un sens métier à la study et aux paramètres. Fournissez-le au niveau study avec AgentSampler(context=...), au niveau paramètre avec suggest_*(..., context=...), ou les deux.

Vous pouvez aussi lancer examples/quickstart.py ou suivre tutorials/quickstart.ipynb.

Domaines d'application

Domaine	Paramètres que optim-agent peut régler	Objectif exemple
Entraînement de modèles	taux d'apprentissage, architectures, augmentation, régularisation	qualité de validation, calcul, robustesse
Inférence et serving	quantification, batching, décodage, cache, routage	qualité, latence, débit, coût
Recherche quantitative	fenêtres de signal, seuils, règles de rééquilibrage, contrôles de risque	rendement walk-forward, drawdown, turnover
RL et décisions	poids d'objectif, calendriers d'exploration, paramètres d'environnement, seuils de politique	retour, sûreté, efficacité échantillon
Workflows scientifiques	entrées de simulation, paramètres solveur, contrôles expérimentaux	ajustement, erreur, temps, ressources
Systèmes boîte noire	toute configuration catégorielle, entière ou continue bornée	score objectif scalaire

Voir aussi examples/sklearn_tuning.py et examples/inference_tuning.py.

Pour le reinforcement learning, optim-agent règle le système autour de la boucle d'apprentissage ; il ne remplace pas l'algorithme d'apprentissage de politique.

Trajectoire d'optimisation

Cette trace Branin seed-0 compare TPE et GPT-5.5 avec le même budget de 10 trials, en montrant la valeur objective incumbent après chaque trial. C'est une illustration de trajectoire ; les résultats agrégés et les commandes de reproduction suivent.

Optimisation de fonctions mathématiques sans contexte : Branin-2D et Ackley-5D

Les agents de fonctions difficiles ne reçoivent aucun contexte de tâche fourni : seulement les noms génériques x1...x5, les bornes numériques et l'historique des trials. Les runs utilisent 10 trials sur cinq seeds ; Random et TPE sont des baselines inchangées.

Agents haut de gamme

méthode	meilleur Branin moyen ↓	meilleur Ackley-5D moyen ↓
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

Les modèles épinglés sont gpt-5.5, claude-opus-4-8, claude-sonnet-5, kimi-k3, MiniMax-M3 et glm-5.2. Opus-4.8 atteint l'optimum Branin en moyenne et obtient la meilleure moyenne Ackley sur cinq seeds.

Agents OpenCode (gratuits)

méthode	meilleur Branin moyen ↓	meilleur Ackley-5D moyen ↓
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

Les modèles hébergés par OpenCode ne demandent pas d'API de modèle payante. Le pool gratuit tourne ; cette mise à jour épingle opencode/big-pickle, opencode/deepseek-v4-flash-free, opencode/nemotron-3-ultra-free et opencode/mimo-v2.5-free. DeepSeek V4 Flash a la meilleure moyenne Ackley gratuite, tandis que MiMo-v2.5 a la meilleure moyenne Branin gratuite.

Réglage de classificateurs d'images ResNet : MNIST et CIFAR-10

Le benchmark de classification compare Random, Optuna TPE, GPT-5.5 w/ context et GPT-5.5 w/o context sur cinq seeds (0..4) et 10 trials. La condition avec contexte reçoit des descriptions naturelles de la study et des paramètres ; la condition sans contexte ne reçoit que les bornes et l'historique.

La métrique principale favorise l'amélioration rapide :

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

Plus bas est meilleur.

méthode	erreur cumulative MNIST ↓	erreur finale MNIST ↓	erreur cumulative CIFAR-10 ↓	erreur finale CIFAR-10 ↓
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 réduit l'erreur cumulative best-so-far de 20.9% par rapport à TPE sur MNIST et de 20.8% par rapport à Random sur CIFAR-10. Sans contexte, il est 24.3% pire que TPE sur MNIST et 0.9% pire que Random sur CIFAR-10.

examples/mnist.py et examples/cifar10.py règlent le learning rate, la batch size, le weight decay, le label smoothing, trois largeurs de stage, trois profondeurs de stage et quatre contrôles de dropout. MNIST ajoute translation et rotation ; CIFAR-10 utilise crop padding et flip probability.

Réglage de contrôleurs Q-learning : Acrobot-v1 et LunarLander-v3

Ce benchmark CPU-only Gymnasium règle un contrôleur Q-learning discrétisé pour Acrobot-v1 et LunarLander-v3. Chaque méthode exécute 20 trials sur cinq seeds (0..4) ; l'objectif est le retour d'évaluation moyen, donc plus haut est meilleur. Le runner parallélise entre seeds et dans chaque study HPO via --workers. Les bras GPT-5.5 utilisent high modeling effort et les 5 derniers trials d'historique.

méthode	retour Acrobot-v1 ↑	retour LunarLander-v3 ↑
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

Avec 20 trials et cinq trials d'historique de prompt, GPT-5.5 w/ context a le meilleur retour moyen sur les deux environnements : 0.2 au-dessus de TPE sur Acrobot-v1 et 11.3 au-dessus de Random sur LunarLander-v3. Considérez cela comme un stress test CPU HPO, pas comme un classement universel.

Pour l'animation, optim-agent règle sept gains d'un contrôleur LunarLander déterministe avec un seed HPO. Chaque trial utilise les mêmes 20 seeds de rollout, en priorisant le nombre d'atterrissages réussis puis le retour moyen. Le trial retenu atterrit dans les 20 rollouts ; le GIF montre son rollout au meilleur retour.

Réglage d'un classificateur gradient boosting : probabilités de défaut de crédit

Ce benchmark CPU-only règle huit paramètres d'entraînement d'un HistGradientBoostingClassifier sur le jeu UCI Default of Credit Card Clients : 30 000 lignes, 23 variables et une cible de défaut le mois suivant. L'archive officielle est épinglée par SHA-256, licenciée CC BY 4.0, et divisée une seule fois en 60% train, 20% validation et 20% test intact. Toutes les méthodes utilisent la même partition, 20 trials et les seeds 0..4. Les deux bras GPT-5.5 utilisent high modeling effort, 20 trials d'historique de prompt, explicit reasoning et qualitative notes.

méthode	log loss validation finale ↓	log loss test retenu ↓
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

Le contexte réduit la log loss validation finale de 1.13% et la log loss test de 1.23% par rapport au contrôle no-context. GPT-5.5 a aussi une perte moyenne validation et test inférieure à Random, TPE et GP-BO. Comme la configuration retenue a été choisie avec la validation et le test, le résultat test est une comparaison benchmark et non une estimation intacte de généralisation.

C'est un benchmark méthodologique, pas un système de décision de crédit en production. Le déploiement demanderait équité, calibration, dérive, gouvernance et revue juridique.

Reproduire les artefacts benchmark :

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

Guide d'utilisation

Contrôles du prompt sampler

effort est transmis au flag reasoning-effort du backend CLI. Le prompt du harness est contrôlé séparément :

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

Définissez history=None pour montrer tous les trials complétés/pruned. Utilisez explicit_reasoning=False ou qualitative_notes=False pour raccourcir les réponses de l'agent.

Journalisation des trials

study.optimize(..., verbose=...) contrôle la sortie par trial :

• verbose=True (défaut) affiche un tableau sur un terminal interactif : une ligne par trial avec les colonnes trial, value, best, state, plus une colonne par paramètre de l'espace de recherche dans l'ordre de première apparition. Les lignes longues sont tronquées avec une ellipse pour tenir dans la largeur du terminal ; les valeurs manquantes (p. ex. trials échoués) s'affichent comme -.
• Quand stdout n'est pas un TTY (sortie redirigée, logs CI), verbose=True / "table" bascule automatiquement vers le format une ligne, compatible grep ([optim-agent] trial 3: value=0.91 state=complete best=0.91).
• verbose="line" utilise toujours le format une ligne, même sur un TTY.
• verbose="table" utilise le tableau sur un TTY et le format une ligne en redirection.
• verbose=False désactive la sortie par trial.

Avec les espaces define-by-run, un trial qui introduit une nouvelle clé de paramètre réimprime l'en-tête avec le sur-ensemble de colonnes.

Agent de résumé

Passez summarize=True à create_study pour que l'agent narre la study terminée une fois, après le dernier trial :

study = oa.create_study(
    sampler=oa.AgentSampler(backend="claude"),
    storage="study.json",
    summarize=True,
)
study.optimize(objective, n_trials=20)
print(study.summary)  # également persisté dans le stockage JSON / SQLite

Le résumé est structuré en quatre sections — meilleure configuration, enseignements sur l'espace de recherche, points saillants de la trajectoire et prochaines étapes suggérées. Il est imprimé dans le terminal et persisté sur study.summary (clé additive dans le stockage JSON et dans la table meta SQLite ; les anciennes studies se chargent avec summary=None).

Résolution du backend : un summary_backend= explicite l'emporte ; sinon le backend du sampler est réutilisé quand le sampler est un AgentSampler. Avec tout autre sampler, passez summary_backend= ou create_study lève un ValueError qui nomme la solution. summary_model= / summary_effort= remplacent le model/effort du sampler pour le résumé. Les réponses de l'agent impossibles à parser en quatre sections retombent sur l'impression du texte brut — un résumé ne fait jamais échouer la study, et les studies sans trial complété l'ignorent avec une notice d'une ligne. backend="mock" fonctionne aussi pour le summarizer, donc les démos et tests tournent sans CLI d'agent réel.

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

L'agent pruner compare la courbe courante aux trials terminés et répond prune/keep ; loose ne prune que les runs clairement faibles, tandis que tight prune plus agressivement. Les erreurs d'agent ne prunent jamais un trial.

Concurrence et studies distribuées

Définissez max_concurrency (défaut 1) pour évaluer plusieurs trials à la fois, et utilisez un fichier SQLite storage (.db / .sqlite) comme historique partagé sûr en concurrence :

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)

• Dans un processus, max_concurrency lance les objectifs dans un pool de threads. Les requêtes de sampling agent sont mises en file et sérialisées pour que chaque proposition voie l'historique du processus ; seuls les appels objectif sont parallèles.
• Entre processus / machines, pointez tous les workers vers le même storage SQLite. La base est le canal de communication : le mode WAL laisse chaque worker ajouter des résultats et lire l'historique sans conflit d'écriture.

Limites : les threads partagent le GIL, donc les objectifs pure-Python CPU-bound fonctionnent mieux dans des processus séparés avec SQLite partagé. Les workers concurrents ne voient pas les points in-flight des autres et peuvent parfois explorer des régions proches.

Mode skill (l'agent lit le code du projet)

Le package pip traite l'objectif comme une boîte noire. Le skill optim-agent va plus loin : chargé dans une session d'agent de code, l'agent lit d'abord le projet pour comprendre le rôle de chaque paramètre, puis pilote la même boucle study via study.ask(params) / study.tell(trial, value), avec le JSON de study comme historique.

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

Plugin Claude Code :

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

Plugin Codex :

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))

Tests hors ligne

AgentSampler(backend="mock") est un substitut sans tokens qui fait un hill climbing autour du meilleur point, utile pour tester les intégrations avant les appels agent.

Dépannage

• claude renvoie 401 dans une session agent - les sessions imbriquées héritent de ANTHROPIC_API_KEY ; lancez avec env -u ANTHROPIC_API_KEY ou depuis un shell propre.
• Un appel backend expire ou émet une sortie invalide - le sampler avertit et revient à un point aléatoire pour ce trial ; la study continue.
• OpenCode avec studies distribuées - OpenCode currently does not support distributed computing in optim-agent ; utilisez le flux mono-processus ou un autre backend.

Contribution

Développement local :

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

Ouvrez une issue pour discuter des changements importants avant un PR. Ajouter un nouveau backend agent signifie généralement une petite fonction dans optim_agent/agent.py.

Le README.md anglais reste la source d'autorité pour les versions, valeurs benchmark et backends.

Remerciements

• Optuna pour avoir popularisé l'interface Study/Trial, fourni la baseline TPE utilisée dans les exemples et benchmarks, et fixé un haut niveau pour les outils d'optimisation pratiques.
• OpenCode pour l'accès aux modèles gratuits évalués dans les benchmarks de fonctions difficiles.

Licence

MIT