Erreurs de modèle LiteLLM dans Agent Zero : authentification, identifiants de modèle et endpoints

Une erreur de modèle LiteLLM dans Agent Zero est plus souvent due à un problème de préfixe ou de rôle qu’à un problème de clé, car Agent Zero n’envoie jamais le nom de modèle que vous avez saisi. Sur agent0ai/agent-zero main, models.py construit f"{provider}/{model}" avant chaque appel LiteLLM — ligne 385 pour le chat, ligne 800 pour l’embedding — et la partie fournisseur provient de conf/model_providers.yaml, et non du libellé de la liste déroulante.

Deux faits de version déterminent le reste. La dernière version est v2.12, publiée le 9 septembre 2026, et l’ancien chemin frdel/agent-zero redirige désormais vers agent0ai/agent-zero ; les anciennes commandes de clonage et les liens vers les issues aboutissent donc à une redirection. De plus, requirements.txt fixe litellm==1.88.1, commenté # CVE-2026-42271 fix: patched floor is 1.83.7. PyPI date cette version du 9 juin 2026, contre une version actuelle 1.102.0 du 20 septembre 2026. Vérifiez les symptômes avec la version 1.88.1, et non avec la documentation actuelle de LiteLLM. Tout a été vérifié le 21 septembre 2026.

Lisez le code de statut avant de toucher à la clé

Lorsque l’exception contient un code de statut entier, _is_transient_litellm_error décide sur cette seule base : vrai pour 408, 429, 500, 502, 503 et 504, vrai pour tout autre 5xx, faux pour tous les autres statuts. Ce n’est qu’en l’absence de code de statut qu’il revient à la correspondance entre les classes d’exception — notamment les expirations de délai et les erreurs de connexion — ; « absence de statut » est donc le seul cas où une nouvelle tentative peut avoir lieu sans 4xx/5xx à invoquer. Toutes les classes du tableau ci-dessous comportent un statut, et elles ont été lues dans l’archive litellm 1.88.1.

Une exception et un angle mort. La ligne 638 de models.py lève une exception plutôt que de réessayer lorsque got_any_chunk est true ; une erreur transitoire survenant au milieu de la diffusion n’est donc pas réessayée — « l’échec a été immédiat » est un indice, pas une preuve. Et configure_litellm() s’exécute à l’importation, en définissant LITELLM_LOG=ERROR et litellm.suppress_debug_info = True. Dans la version 1.88.1, l’indication de la liste des fournisseurs dans get_llm_provider_logic.py est protégée par if litellm.suppress_debug_info is False — la seule ligne que LiteLLM afficherait pour vous orienter vers sa liste de fournisseurs est désactivée par Agent Zero.

L’identifiant que vous avez saisi n’est pas celui qui est envoyé

Deux identifiants existent par fournisseur, comme l’indique l’en-tête provider config : l’identifiant du fournisseur pilote « the settings UI dropdowns » ainsi que la variable d’environnement de la clé API, tandis que litellm_provider est « The corresponding provider name in LiteLLM ». C’est le second qui est ajouté en préfixe. Pour un point de terminaison compatible OpenAI tiers, l’identifiant du fournisseur est other (« Other OpenAI compatible »), dont le litellm_provider est openai, et _adjust_call_args remappe également other vers openai. La valeur transmise est openai/<your-model>, conformément au formulaire LiteLLM documents. Saisissez donc l’identifiant nu : en lisant ces deux emplacements du code, ajouter vous-même le préfixe produirait openai/openai/gpt-4o — c’est un raisonnement fondé sur le code, et non une erreur observée.

Lorsque la résolution échoue, la version 1.88.1 comporte deux chaînes distinctes, toutes deux associées à des erreurs 400. get_llm_provider_logic.py lève BadRequestError avec « LLM Provider NOT provided … You passed model=… » — rien d’utilisable n’a été dérivé de la chaîne. LiteLLMUnknownProvider à exceptions.py ligne 902 contient « Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=… » — un fournisseur a été déduit, mais aucune route ne lui correspond sur ce point de terminaison. C’est le second message auquel s’attendre lorsqu’un fournisseur fonctionne pour un rôle mais pas pour un autre.

Un conflit oriente les utilisateurs vers le mauvais champ. La FAQ d’Agent Zero indique que openai/gpt-5.3 est correct pour OpenRouter mais incorrect pour le fournisseur OpenAI natif, « which goes without prefix », et le tableau de dénomination du guide d’installation répertorie OpenAI comme « Model name only ». Ces indications décrivent la zone de texte ; le code ajoute le préfixe devant son contenu. Les deux sont vrais dès lors que la couche est précisée. Ce tableau comporte également un défaut de documentation — sa ligne OpenAI utilise un identifiant de modèle Anthropic comme exemple — ; ne copiez donc pas cette cellule.

Déterminez lequel des trois rôles a échoué

Agent Zero configure trois rôles indépendamment — chat, utilitaire et embedding — chacun avec son propre fournisseur, nom de modèle et API base. Les sections de paramètres sont chat_model, utility_model et embedding_model, tandis que les anciennes clés plates sont chat_model_*, util_model_* et embed_model_* ; rechercher settings.json selon la mauvaise convention ne donne donc aucun résultat. Il existe une quatrième sélection facultative à connaître : le plugin de navigateur intégré possède son propre model_preset, livré vide et documenté comme « Empty uses the effective Main Model » — sauf si vous le définissez, un échec de l’outil navigateur est donc un échec du rôle chat sous un autre nom. Et une réponse chat réussie prouve qu’un rôle fonctionne, pas les trois.

Le rôle embedding diffère de deux façons qui modifient le diagnostic. LiteLLMEmbeddingWrapper.embed appelle embedding() de LiteLLM sans try/except et sans boucle de tentative, et lève donc une exception dès la première tentative, quelle que soit la classe. De plus, la valeur par défaut livrée est le fournisseur huggingface avec le nom sentence-transformers/all-MiniLM-L6-v2 ; models.py achemine tout nom huggingface commençant par sentence-transformers/ vers un wrapper exécuté en processus, que le code décrit comme évitant les appels à l’API HuggingFace ; une défaillance à cet endroit n’implique donc pas nécessairement un appel réseau.

Kunavo ne propose aucun modèle d’embedding ; les rôles qu’une clé Kunavo peut donc remplir dans Agent Zero sont les rôles chat et utilitaire.

OpenRouter constitue la séparation des rôles confirmée, et c’est ici la seule branche avec une correction du mainteneur plutôt qu’une déduction. L’issue #1597, « OpenRouter embedding models fail due to LiteLLM missing provider route », a été ouverte le 2 mai 2026 et fermée le 27 août 2026, quelques heures avant la publication de v2.11 le même jour. Deux éléments doivent y être distingués, car ils sont faciles à confondre. La configuration achemine bien le fournisseur selon le rôle — chat conserve litellm_provider: openrouter natif, tandis que embedding utilise litellm_provider: openai avec un api_base explicite, sous le TODO des mainteneurs indiquant qu’OpenRouter « not yet supported by LiteLLM » —, mais cette séparation est identique sur le tag v2.10 et sur main ; elle n’est donc pas la cause de la fermeture de l’issue. La modification qui l’a résolue tient en une ligne de models.py : sur v2.10, le wrapper d’embedding construisait f"{provider}/{model}" if provider != "openai" else model, supprimant le préfixe pour chaque embedding acheminé par openai ; à partir de v2.11, il ajoute le préfixe systématiquement, raison pour laquelle la note de clôture du mainteneur indique que les identifiants contenant une barre oblique atteignent désormais le point de terminaison intacts. Dans cette branche, la solution est la mise à niveau, et non une modification des paramètres.

La recherche de clé, et pourquoi « changer la clé » ne suffit souvent pas

get_api_key(service) lit trois noms d’environnement dans un ordre fixe et utilise comme valeur de repli la chaîne littérale "None".

# Provider id `other` ("Other OpenAI compatible"). models.py reads these
# three names in this order and stops at the first non-empty value.
API_KEY_OTHER=sk-...
# OTHER_API_KEY=sk-...
# OTHER_API_TOKEN=sk-...

# A comma in the value is not a syntax error: models.py splits on it
# and rotates the resulting keys round-robin.

Cet espace réservé est filtré — le site d’appel vérifie api_key not in ("None", "NA") avant de le joindre — ; une clé non résolue signifie donc qu’aucun argument api_key n’est envoyé, et LiteLLM applique alors sa propre recherche d’environnement. Un 401 peut provenir d’un identifiant que vous n’avez jamais choisi. Une seconde recherche utilise une valeur service différente : _merge_provider_defaults lit la clé sous l’identifiant de fournisseur d’origine, puis _get_litellm_chat revient à get_api_key(provider_name), auquel moment ce nom est le fournisseur LiteLLM — openai, pour other. Ainsi, un API_KEY_OTHER non défini en présence d’une clé OpenAI dans le même .env envoie la clé OpenAI à votre point de terminaison. Ces informations proviennent de ces deux fonctions sur main ; elles ne sont pas documentées et n’ont pas été testées à l’exécution ici.

Le guide d’installation place la clé sous External Services → Other OpenAI-compatible API keys, puis indique OpenAI Compatible comme fournisseur. Deux symptômes documentés à proximité ne sont pas des problèmes d’identifiant de modèle : lorsque rien ne se passe lors de l’envoi, la FAQ incrimine les clés non définies dans Settings ; et ChatGPT Plus n’inclut aucun crédit API — bien que le plugin OAuth intégré fournisse une connexion codex_oauth qui ouvre une session avec un compte OpenAI ; il serait donc faux d’affirmer qu’« aucun abonnement ne peut faire fonctionner Agent Zero ».

Le point de terminaison, et deux règles qui semblent contradictoires

Le fournisseur other ne fournit aucun api_base par défaut, et ModelConfig.build_kwargs ne transmet ce champ que lorsqu’il n’est pas vide ; une URL API vide n’envoie donc aucune base et la valeur par défaut standard de LiteLLM, openai, s’applique. La destination vers laquelle cette valeur se résout dans la version 1.88.1 n’a pas été vérifiée ici ; considérez un 401 avec une URL vide comme une raison de remplir le champ, et non comme un diagnostic. La page de LiteLLM consacrée aux points de terminaison compatibles contient ensuite deux remarques apparemment opposées : « Do NOT add anything additional to the base url e.g. /v1/embedding » et « If you see Not Found Error when testing make sure your api_base has the /v1 postfix. » Elles se résument à une seule règle : arrêtez-vous à /v1 et n’ajoutez rien après.

Sous Docker, le guide d’installation précise que localhost et 127.0.0.1 dans une URL API de base désignent le conteneur : utilisez http://host.docker.internal:<port>, ou une adresse de passerelle telle que http://172.17.0.1:<port> sur le pont Linux par défaut, et déplacez un serveur lié à la boucle locale de l’hôte vers une adresse accessible depuis Docker, comme 0.0.0.0. Vérifiez ensuite que la configuration lue est bien celle qui a été exécutée : les préréglages A0_SET_ ne sont que des valeurs initiales par défaut — « Once a value is saved in settings.json, it takes precedence over these environment variables » — et un redémarrage est requis. Par ailleurs, l’issue #1769 (ouverte le 15 juillet 2026, toujours ouverte) signale que LiteLLM appelle exit(-9) lorsqu’un fournisseur enregistré pour un modèle diffère de celui qui le sert : il s’agit de l’analyse d’un rapporteur, non confirmée et non reproduite ici.

Le coût de la mauvaise solution

Le moyen le plus rapide de faire taire un rôle utilitaire défaillant consiste à le diriger vers le modèle principal. Cela fonctionne, et la facturation se fait au tarif du modèle principal pour le trafic que le guide d’installation décrit comme de la synthèse et de l’extraction de mémoire. Ces chiffres sont une arithmétique illustrative des tokens, et non des coûts de tâche mesurés ni un plafond de facturation : supposons une journée de travail du modèle principal à 1200k tokens d’entrée et 60k tokens de sortie, un trafic utilitaire à 320k et 24k, ainsi que les tarifs actuels du catalogue Kunavo par million de tokens.

Le rôle principal lui-même coûte $3.150 pour cette journée ; fusionner le rôle utilitaire avec Claude Sonnet 4.6 ajoute $0.924, tandis que Claude Haiku 4.5 coûte $0.308. Attention toutefois au seuil de capacité : le guide d’installation avertit que les modèles utilitaires doivent être « strong enough to extract and consolidate memory reliably » et que les modèles très petits, d’environ 4B, échouent généralement à extraire le contexte de manière fiable. Le guide décrit cela comme un échec de la tâche, et non comme une erreur ; c’est donc le cas où « le modèle a généré une erreur » constitue le mauvais diagnostic.

Agent Zero lui-même ne coûte rien sous licence — son LICENSE sur main est un texte MIT, copyright « Agent Zero, s.r.o » — ; la dépense correspond donc aux tokens des modèles utilisés pour les rôles que vous configurez. Le montant du catalogue Kunavo est un minimum de facturation, et non un plafond : lorsque le fournisseur en amont communique son coût, la facture correspond au montant le plus élevé entre le coût du catalogue et le coût du fournisseur en amont multiplié par la majoration applicable. Le rechargement minimal est de $10 en crédit prépayé. Consultez les détails de facturation.

Quelle route placer derrière les rôles

Pour le budget par rôle, consultez Agent Zero API costs ; pour ce troisième emplacement, changing the embedding model ; pour les conventions générales d’URL de base et de préfixe, consultez OpenAI-compatible API. Pour connecter une clé Kunavo à other : commencez par la référence des erreurs, puis créez un compte. Agent Zero n’a pas été testé à l’exécution avec le point de terminaison Kunavo ; gardez donc une route fonctionnelle disponible pendant vos essais.

Questions fréquentes

Le comportement d’Agent Zero a été analysé à partir du code source de la branche main de agent0ai/agent-zero — models.py et conf/model_providers.yaml — ainsi que de sa documentation, de ses versions et de ses issues, le 21 septembre 2026 ; les classes d’exception et les chaînes d’erreur de LiteLLM ont été lues dans l’archive litellm 1.88.1 de PyPI, la version fixée par Agent Zero. Rien de tout cela n’a été testé à l’exécution : aucune installation n’a été effectuée et aucune erreur n’a été reproduite de bout en bout. Les tarifs des tokens Kunavo proviennent du catalogue en ligne, et chaque montant en dollars correspond à une arithmétique illustrative des tokens.