Errori dei modelli LiteLLM di Agent Zero: autenticazione, ID dei modelli ed endpoint

Un errore del modello LiteLLM di Agent Zero è più spesso un problema di prefisso o di ruolo che un problema di chiave, perché Agent Zero non invia mai il nome del modello che hai digitato. Su agent0ai/agent-zero main, models.py costruisce f"{provider}/{model}" prima di ogni chiamata a LiteLLM — riga 385 per la chat, riga 800 per gli embedding — e la parte relativa al provider proviene da conf/model_providers.yaml, non dall'etichetta del menu a discesa.

Due fatti sulle versioni determinano il significato di tutto il resto. L'ultima release è v2.12, pubblicata il 9 settembre 2026, e il vecchio percorso frdel/agent-zero ora risolve in agent0ai/agent-zero, quindi i vecchi comandi di clonazione e i link alle issue portano a un reindirizzamento. Inoltre, requirements.txt fissa litellm==1.88.1, con il commento # CVE-2026-42271 fix: patched floor is 1.83.7. PyPI data questa versione al 9 giugno 2026, rispetto alla 1.102.0 attuale del 20 settembre 2026. Verifica i sintomi rispetto alla 1.88.1, non rispetto alla documentazione attuale di LiteLLM. Tutto verificato il 21 settembre 2026.

Leggi il codice di stato prima di toccare la chiave

Quando l'eccezione contiene un codice di stato intero, _is_transient_litellm_error decide basandosi solo su quello: true per 408, 429, 500, 502, 503 e 504, true per qualsiasi altro 5xx, false per ogni altro stato. Solo quando non è presente alcun codice di stato passa al confronto tra le classi delle eccezioni — includendo timeout ed errori di connessione — quindi "nessuno stato" è l'unico caso in cui può verificarsi un nuovo tentativo senza un 4xx/5xx da indicare. Ogni classe nella tabella seguente ha uno stato, e sono state lette all'interno del wheel litellm 1.88.1.

Un'eccezione e un punto cieco. models.py alla riga 638 solleva un'eccezione invece di ritentare quando got_any_chunk è true, quindi un errore transitorio che arriva durante lo streaming non viene ritentato — "è fallito immediatamente" è un indizio, non una prova. Inoltre, configure_litellm() viene eseguito all'importazione, impostando LITELLM_LOG=ERROR e litellm.suppress_debug_info = True. Nella versione 1.88.1 il suggerimento dell'elenco dei provider in get_llm_provider_logic.py è protetto da if litellm.suppress_debug_info is False — l'unica riga che LiteLLM stamperebbe per indirizzarti al suo elenco dei provider è la riga che Agent Zero disattiva.

L'id che hai digitato non è l'id che viene inviato

Per ogni provider esistono due identificatori, come indica l'intestazione provider config: il provider ID determina "the settings UI dropdowns" e la variabile d'ambiente della chiave API, mentre litellm_provider è "The corresponding provider name in LiteLLM". È il secondo a essere anteposto. Per un endpoint compatibile con OpenAI di terze parti, il provider id è other ("Other OpenAI compatible"), il cui litellm_provider è openai, e _adjust_call_args rimappa anche other in openai. Il valore trasmesso è openai/<your-model>, il formato documentato da LiteLLM. Quindi inserisci l'id senza prefisso: leggendo quei due punti del codice, aggiungere manualmente il prefisso produrrebbe openai/openai/gpt-4o — un ragionamento sul codice, non un errore osservato.

Quando la risoluzione fallisce, la versione 1.88.1 ha due stringhe distinte, entrambe con errore 400. get_llm_provider_logic.py solleva BadRequestError con "LLM Provider NOT provided … You passed model=…" — dalla stringa non è stato ricavato nulla di utilizzabile. LiteLLMUnknownProvider a exceptions.py riga 902 contiene "Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=…" — un provider è stato ricavato, ma non esiste alcun percorso per esso su quell'endpoint. È questo il caso da aspettarsi quando un provider funziona per un ruolo ma non per un altro.

Un conflitto indirizza le persone verso il campo sbagliato. La FAQ di Agent Zero afferma che openai/gpt-5.3 è corretto per OpenRouter ma errato per il provider OpenAI nativo, "which goes without prefix", mentre la tabella dei nomi nella guida all'installazione indica OpenAI come "Model name only". Queste descrizioni si riferiscono alla casella di testo; il codice aggiunge il prefisso sopra di essa. Entrambe sono vere una volta specificato il livello. La tabella contiene anche un errore nella documentazione — la sua riga OpenAI usa come esempio un model id Anthropic — quindi non copiare quel valore.

Scopri quale dei tre ruoli ha avuto il problema

Agent Zero configura separatamente tre ruoli — chat, utility ed embedding — ciascuno con il proprio provider, nome del modello e base API. Le sezioni delle impostazioni sono chat_model, utility_model e embedding_model, mentre le chiavi flat legacy sono chat_model_*, util_model_* e embed_model_*; cercare settings.json usando la convenzione sbagliata non trova nulla. Esiste inoltre una quarta selezione opzionale che vale la pena conoscere: il plugin browser incluso ha un proprio model_preset, distribuito vuoto e documentato come "Empty uses the effective Main Model" — quindi, salvo impostazione esplicita, un errore dello strumento browser è il fallimento del ruolo chat con un altro nome. Inoltre, una risposta chat riuscita dimostra che funziona un ruolo, non tutti e tre.

Il ruolo embedding differisce in due modi che cambiano il triage. LiteLLMEmbeddingWrapper.embed chiama il embedding() di LiteLLM senza try/except e senza un ciclo di tentativi, quindi solleva un'eccezione al primo tentativo indipendentemente dalla classe. Inoltre, il valore predefinito distribuito è il provider huggingface con il nome sentence-transformers/all-MiniLM-L6-v2; models.py instrada qualsiasi nome huggingface che inizi con sentence-transformers/ verso un wrapper in-process che il codice descrive come capace di evitare le chiamate all'API HuggingFace, quindi un errore in quel punto potrebbe non comportare alcuna chiamata di rete.

Kunavo non offre alcun modello di embedding, quindi i ruoli che una chiave Kunavo può ricoprire in Agent Zero sono chat e utility.

OpenRouter è la separazione dei ruoli confermata e l'unico ramo qui con una correzione del maintainer invece che con un'inferenza. La issue #1597, "OpenRouter embedding models fail due to LiteLLM missing provider route", è stata aperta il 2 maggio 2026 e chiusa il 27 agosto 2026, poche ore prima che v2.11 venisse rilasciata lo stesso giorno. È necessario separare due aspetti, perché è facile confonderli. La configurazione instrada effettivamente il provider per ruolo — chat mantiene litellm_provider: openrouter nativo, mentre embedding usa litellm_provider: openai più un api_base esplicito, nell'ambito del TODO dei maintainer secondo cui OpenRouter "not yet supported by LiteLLM" — ma questa separazione è identica nel tag v2.10 e in main, quindi non è ciò che ha chiuso la issue. La modifica che l'ha risolta è una riga di models.py: in v2.10 il wrapper degli embedding costruiva f"{provider}/{model}" if provider != "openai" else model, eliminando il prefisso da ogni embedding instradato tramite openai, mentre da v2.11 aggiunge il prefisso in modo incondizionato; per questo la nota di chiusura del maintainer afferma che gli id contenenti una barra raggiungono ora intatti l'endpoint. In quel ramo, la correzione è l'aggiornamento, non una modifica alle impostazioni.

La ricerca della chiave e perché "cambiare la chiave" spesso non risolve

get_api_key(service) legge tre nomi di variabili d'ambiente in un ordine fisso e, in mancanza, usa la stringa letterale "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.

Quel segnaposto viene filtrato — il punto di chiamata verifica api_key not in ("None", "NA") prima di allegarlo — quindi una chiave non risolta significa che non viene inviato alcun argomento api_key, e LiteLLM applica invece la propria ricerca nell'ambiente. Un 401 può arrivare da una credenziale che non hai mai selezionato. Una seconda ricerca utilizza un valore service diverso: _merge_provider_defaults legge la chiave usando l'id del provider originale, quindi _get_litellm_chat ripiega su get_api_key(provider_name), a quel punto il nome è quello del provider LiteLLM — openai, per other. Pertanto, se API_KEY_OTHER non è impostato ma nello stesso .env è presente una chiave OpenAI, la chiave OpenAI viene inviata al tuo endpoint. Lettura delle due funzioni su main; non documentato e non testato a runtime in questa sede.

La guida all'installazione colloca la chiave in External Services → Other OpenAI-compatible API keys, quindi indica OpenAI Compatible come provider. Due sintomi documentati nelle vicinanze non sono problemi di model id: quando non succede nulla all'invio, la FAQ attribuisce la causa alle chiavi non impostate nelle Settings; inoltre, ChatGPT Plus non include crediti API — anche se il plugin OAuth incluso fornisce una connessione codex_oauth che effettua l'accesso con un account OpenAI, quindi sarebbe errato dire che "no subscription can drive Agent Zero".

L'endpoint e due regole che sembrano contraddirsi

Il provider other viene distribuito senza alcun api_base predefinito, e ModelConfig.build_kwargs inoltra quel campo solo quando non è vuoto — quindi un URL API vuoto non invia alcuna base e si applica il valore predefinito standard di LiteLLM openai. Non è stato verificato qui a quale host risolva nella versione 1.88.1; considera un 401 con URL vuoto come un motivo per compilare il campo, non come una diagnosi. La pagina di LiteLLM sugli endpoint compatibili contiene poi due note apparentemente opposte: "Do NOT add anything additional to the base url e.g. /v1/embedding" e "If you see Not Found Error when testing make sure your api_base has the /v1 postfix." Si riconciliano in un'unica regola: termina con /v1 e non aggiungere nulla dopo.

Con Docker, la guida all'installazione è esplicita: localhost e 127.0.0.1 in un'API base URL indicano il container; usa http://host.docker.internal:<port>, oppure un indirizzo gateway come http://172.17.0.1:<port> sul bridge Linux predefinito, e sposta un server associato al loopback dell'host su qualcosa di raggiungibile da Docker, come 0.0.0.0. Poi verifica che la configurazione che stai leggendo sia quella effettivamente eseguita: i preset A0_SET_ sono solo valori predefiniti iniziali — "Once a value is saved in settings.json, it takes precedence over these environment variables" — e richiedono un riavvio. Separatamente, la issue #1769 (aperta il 15 luglio 2026, ancora aperta) segnala che LiteLLM chiama exit(-9) quando il provider registrato di un modello è diverso da quello che lo serve: l'analisi di un segnalatore, non confermata e non riprodotta qui.

Quanto costa la correzione sbagliata

Il modo più rapido per mettere a tacere un ruolo utility che fallisce è indirizzarlo al modello principale. Funziona e viene fatturato alla tariffa del modello principale per il traffico che la guida all'installazione descrive come riepilogo ed estrazione della memoria. Queste cifre sono aritmetica illustrativa dei token, non costi misurati delle attività e non un limite massimo della fattura: supponi una giornata di lavoro del modello principale con 1200k token di input e 60k di output, traffico utility con 320k e 24, e tariffe attuali del catalogo Kunavo per milione di token.

Il ruolo principale da solo modella a $3,150 per quella giornata; accorpare il ruolo utility a Claude Sonnet 4.6 aggiunge $0,924, dove Claude Haiku 4.5 modella a $0,308. Attenzione però al livello minimo di capacità: la guida all'installazione avverte che i modelli utility devono essere "strong enough to extract and consolidate memory reliably" e che i modelli molto piccoli, intorno a 4B, di solito non riescono a estrarre il contesto in modo affidabile. La guida descrive questo come un fallimento dell'attività, non come un errore, quindi è il caso in cui "il modello ha generato un errore" è una diagnosi sbagliata.

Agent Zero non costa nulla da concedere in licenza — il suo LICENSE su main contiene testo MIT, copyright "Agent Zero, s.r.o" — quindi il costo riguarda i token dei modelli nei ruoli configurati. L'importo del catalogo Kunavo è un minimo di fatturazione, non un limite massimo: quando il provider upstream comunica il proprio addebito, la fattura è il maggiore tra il costo del catalogo e il costo upstream moltiplicato per il markup applicabile. La ricarica minima è di $10 in credito prepagato. Consulta billing details.

Quale percorso mettere dietro i ruoli

Per la definizione del budget per ruolo, consulta Agent Zero API costs; per il terzo slot, changing the embedding model; per le convenzioni generali su base URL e prefissi, OpenAI-compatible API. Per collegare una chiave Kunavo a other, inizia da the error reference, quindi create an account. Agent Zero non è stato testato a runtime con l'endpoint Kunavo, quindi mantieni disponibile un percorso funzionante mentre lo provi.

Domande frequenti

Comportamento di Agent Zero ricavato dal codice del ramo main di agent0ai/agent-zero — models.py e conf/model_providers.yaml — oltre che dalla documentazione, dalle release e dalle issue, il 21 settembre 2026; le classi delle eccezioni e le stringhe degli errori di LiteLLM sono state lette all'interno del wheel litellm 1.88.1 proveniente da PyPI, la versione fissata da Agent Zero. Nulla di quanto riportato qui è stato testato a runtime: non è stata eseguita alcuna installazione e nessun errore è stato riprodotto end-to-end. Le tariffe dei token Kunavo provengono dal catalogo live e ogni cifra in dollari è aritmetica illustrativa dei token.