Errores de modelo de Agent Zero LiteLLM: autenticación, IDs de modelo y endpoints

Un error de modelo de LiteLLM en Agent Zero suele ser más un problema de prefijo o de rol que de clave, porque Agent Zero nunca envía el nombre del modelo que escribiste. En agent0ai/agent-zero main, models.py construye f"{provider}/{model}" antes de cada llamada a LiteLLM —línea 385 para chat, línea 800 para embeddings— y la parte del proveedor procede de conf/model_providers.yaml, no de la etiqueta del menú desplegable.

Dos datos sobre las versiones determinan el significado del resto. La versión más reciente es v2.12, publicada el 9 de septiembre de 2026, y la antigua ruta frdel/agent-zero ahora resuelve en agent0ai/agent-zero, por lo que los comandos de clonación antiguos y los enlaces de incidencias llegan a una redirección. Además, requirements.txt fija litellm==1.88.1, con el comentario # CVE-2026-42271 fix: patched floor is 1.83.7. PyPI fecha esa versión el 9 de junio de 2026, frente a la actual 1.102.0 del 20 de septiembre de 2026. Comprueba los síntomas con 1.88.1, no con la documentación actual de LiteLLM. Todo comprobado el 21 de septiembre de 2026.

Lee el código de estado antes de tocar la clave

Cuando la excepción contiene un código de estado entero, _is_transient_litellm_error decide basándose únicamente en él: verdadero para 408, 429, 500, 502, 503 y 504, verdadero para cualquier otro 5xx, falso para cualquier otro estado. Solo cuando no existe un código de estado recurre a comparar clases de excepciones —incluidos los tiempos de espera y los errores de conexión—, así que «sin estado» es el único caso en el que puede haber un reintento sin un 4xx/5xx que señalar. Todas las clases de la tabla siguiente contienen un estado, y se leyeron dentro del wheel litellm 1.88.1.

Una excepción y un punto ciego. models.py en la línea 638 genera un error en lugar de reintentar cuando got_any_chunk es true, por lo que no se reintenta un error transitorio que llega a mitad del streaming; «falló inmediatamente» es una pista, no una prueba. Además, configure_litellm() se ejecuta durante la importación y establece LITELLM_LOG=ERROR y litellm.suppress_debug_info = True. En 1.88.1, la indicación de la lista de proveedores en get_llm_provider_logic.py está protegida por if litellm.suppress_debug_info is False; esa es la única línea que LiteLLM imprimiría para dirigirte a su lista de proveedores y que Agent Zero desactiva.

El ID que escribiste no es el ID que se envía

Existen dos identificadores por proveedor, y el encabezado provider config lo indica: el ID del proveedor controla «the settings UI dropdowns» y la variable de entorno de la clave de API, mientras que litellm_provider es «The corresponding provider name in LiteLLM». El segundo es el que se antepone. Para un endpoint de terceros compatible con OpenAI, el ID del proveedor es other («Other OpenAI compatible»), cuyo litellm_provider es openai, y _adjust_call_args también remapea other a openai. El valor enviado es openai/<your-model>, el formulario que LiteLLM documents. Por tanto, escribe el ID sin prefijo: al leer esos dos sitios del código, añadir tú mismo el prefijo produciría openai/openai/gpt-4o; es un razonamiento sobre el código, no un error observado.

Cuando falla la resolución, la versión 1.88.1 tiene dos mensajes distintos, ambos con código 400. get_llm_provider_logic.py lanza BadRequestError con "LLM Provider NOT provided … You passed model=…": no se pudo obtener nada utilizable de la cadena. LiteLLMUnknownProvider en exceptions.py, línea 902, contiene "Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=…": sí se obtuvo un proveedor, pero no hay ninguna ruta para él en ese endpoint. El segundo es el mensaje que cabe esperar cuando un proveedor funciona para un rol y no para otro.

Un conflicto hace que la gente busque en el campo equivocado. La FAQ de Agent Zero dice que openai/gpt-5.3 es correcto para OpenRouter pero incorrecto para el proveedor OpenAI nativo, «which goes without prefix», y la tabla de nombres de la guía de instalación muestra OpenAI como «Model name only». Describen el cuadro de texto; el código antepone el prefijo después. Ambas cosas son ciertas una vez identificada la capa. Esa tabla también contiene un error de documentación: su fila de OpenAI utiliza un ID de modelo de Anthropic como ejemplo, así que no copies esa celda.

Averigua cuál de los tres roles falló

Agent Zero configura tres roles de forma independiente —chat, utility y embeddings—, cada uno con su propio proveedor, nombre de modelo y base de API. Las secciones de configuración son chat_model, utility_model y embedding_model, mientras que las claves planas heredadas son chat_model_*, util_model_* y embed_model_*; buscar settings.json con la convención incorrecta no encuentra nada. Hay una cuarta selección opcional que conviene conocer: el plugin de navegador incluido tiene su propio model_preset, se distribuye vacío y está documentado como «Empty uses the effective Main Model»; por tanto, salvo que lo configures, un fallo de la herramienta de navegador es el fallo del rol de chat bajo otro nombre. Y una respuesta de chat correcta demuestra que funciona un rol, no los tres.

El rol de embeddings difiere en dos aspectos que cambian el diagnóstico. LiteLLMEmbeddingWrapper.embed llama a embedding() de LiteLLM sin try/except ni bucle de intentos, por lo que genera un error en el primer intento independientemente de la clase. Además, el valor predeterminado distribuido es el proveedor huggingface con el nombre sentence-transformers/all-MiniLM-L6-v2; models.py enruta cualquier nombre de huggingface que empiece por sentence-transformers/ a un wrapper en proceso que el código describe como una forma de evitar las llamadas a la API de HuggingFace, así que el fallo no tiene por qué implicar ninguna llamada de red.

Kunavo no ofrece ningún modelo de embeddings, por lo que los roles que una clave de Kunavo puede ocupar en Agent Zero son el de chat y el de utility.

OpenRouter es la división de roles confirmada y la única rama aquí con una corrección del mantenedor en lugar de una inferencia. La incidencia #1597, «OpenRouter embedding models fail due to LiteLLM missing provider route», se abrió el 2 de mayo de 2026 y se cerró el 27 de agosto de 2026, horas antes de que v2.11 se publicara ese mismo día. Hay que separar dos cosas, porque es fácil confundirlas. La configuración sí enruta el proveedor según el rol: chat mantiene litellm_provider: openrouter nativo, mientras que embedding usa litellm_provider: openai más un api_base explícito, bajo la tarea pendiente de los mantenedores de que OpenRouter «not yet supported by LiteLLM»; pero esa división se lee igual en la etiqueta v2.10 y en main, así que no fue lo que cerró la incidencia. El cambio que sí lo hizo es una línea de models.py: en v2.10 el wrapper de embeddings construía f"{provider}/{model}" if provider != "openai" else model, eliminando el prefijo de todos los embeddings enrutados por openai, y desde v2.11 antepone el prefijo incondicionalmente; por eso la nota de cierre del mantenedor dice que los ID que contienen una barra ahora llegan intactos al endpoint. En esa rama, la solución es actualizar, no cambiar la configuración.

La búsqueda de la clave y por qué «cambiar la clave» suele no servir

get_api_key(service) lee tres nombres de entorno en un orden fijo y recurre a la cadena literal "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.

Ese marcador de posición se filtra —el punto de llamada comprueba api_key not in ("None", "NA") antes de adjuntarlo—, así que si no se resuelve la clave, no se envía ningún argumento api_key, y LiteLLM aplica su propia búsqueda en el entorno. Puede llegar un 401 desde una credencial que nunca elegiste. Una segunda búsqueda utiliza un valor service distinto: _merge_provider_defaults lee la clave con el ID de proveedor original y luego _get_litellm_chat recurre a get_api_key(provider_name), momento en el que ese nombre ya es el proveedor de LiteLLM: openai, para other. Por tanto, un API_KEY_OTHER sin definir junto a una clave de OpenAI en el mismo .env envía la clave de OpenAI a tu endpoint. Lectura de esas dos funciones en main; no está documentado ni probado en tiempo de ejecución aquí.

La guía de instalación coloca la clave en External Services → Other OpenAI-compatible API keys, y después OpenAI Compatible como proveedor. Dos síntomas documentados cercanos no son fallos del ID del modelo: cuando no ocurre nada al enviar, la FAQ culpa a las claves no configuradas en Settings; y ChatGPT Plus no incluye créditos de API, aunque el plugin OAuth incluido distribuye una conexión codex_oauth que inicia sesión con una cuenta de OpenAI, por lo que sería incorrecto decir que «ninguna suscripción puede hacer funcionar Agent Zero».

El endpoint y dos reglas que parecen contradictorias

El proveedor other se distribuye sin ningún api_base predeterminado, y ModelConfig.build_kwargs reenvía ese campo solo cuando no está vacío; por tanto, una URL de API en blanco no envía ninguna base y se aplica el valor predeterminado estándar de openai de LiteLLM. Aquí no se comprobó a qué host resuelve eso en 1.88.1; considera un 401 con una URL en blanco como motivo para rellenar el campo, no como un diagnóstico. La página de endpoints compatibles de LiteLLM incluye después dos notas que parecen apuntar en direcciones opuestas: «Do NOT add anything additional to the base url e.g. /v1/embedding» y «If you see Not Found Error when testing make sure your api_base has the /v1 postfix.» Se reconcilian en una sola regla: termina en /v1 y no añadas nada después.

Con Docker, la guía de instalación indica explícitamente que localhost y 127.0.0.1 en una URL base de API significan el contenedor: usa http://host.docker.internal:<port>, o una dirección de gateway como http://172.17.0.1:<port> en el bridge predeterminado de Linux, y mueve un servidor enlazado al loopback del host a algo accesible desde Docker, como 0.0.0.0. Después confirma que la configuración que lees es la que se ejecutó: los valores predeterminados de A0_SET_ solo son iniciales; «Once a value is saved in settings.json, it takes precedence over these environment variables», y es necesario reiniciar. Por separado, la incidencia #1769 (abierta el 15 de julio de 2026, todavía abierta) informa de que LiteLLM llama a exit(-9) cuando el proveedor registrado de un modelo difiere del que lo sirve: el análisis de un informante, no confirmado ni reproducido aquí.

El coste de la solución incorrecta

La forma más rápida de silenciar un rol utility que falla es dirigirlo al modelo principal. Funciona y se factura a la tarifa del modelo principal el tráfico que la guía de instalación describe como resumen y extracción de memoria. Estas cifras son cálculos ilustrativos de tokens, no costes de tareas medidos ni un límite de facturación: supón un día de trabajo del modelo principal con 1200k tokens de entrada y 60k de salida, tráfico utility con 320k y 24, y las tarifas actuales del catálogo de Kunavo por millón de tokens.

El rol principal por sí solo modela a $3.150 durante ese día; hacer que el rol utility use Claude Sonnet 4.6 añade $0.924, mientras que Claude Haiku 4.5 modela a $0.308. Sin embargo, ten en cuenta el umbral de capacidad: la guía de instalación advierte que los modelos utility deben ser «strong enough to extract and consolidate memory reliably» y que los modelos muy pequeños, de alrededor de 4B, suelen fallar al extraer contexto de forma fiable. La guía lo describe como un fallo de la tarea, no como un error, por lo que este es el caso en el que «el modelo dio error» es el diagnóstico equivocado.

El propio Agent Zero no cuesta nada por licencia: su LICENSE en main es texto MIT, con copyright «Agent Zero, s.r.o»; por tanto, el dinero corresponde a los tokens de los modelos en los roles que configures. El importe del catálogo de Kunavo es un mínimo de facturación, no un límite: cuando el proveedor ascendente informa de su cargo, la factura es el mayor entre el coste del catálogo y el coste ascendente multiplicado por el margen aplicable. La recarga mínima es de $10 en crédito prepago. Consulta billing details.

Qué ruta poner detrás de los roles

Para el presupuesto por rol, consulta Agent Zero API costs; para ese tercer espacio, changing the embedding model; para las convenciones generales de URL base y prefijos, OpenAI-compatible API. Para conectar una clave de Kunavo a other, empieza por the error reference y después create an account. Agent Zero no se ha probado en tiempo de ejecución con el endpoint de Kunavo, así que mantén disponible una ruta funcional mientras lo pruebas.

Preguntas frecuentes

El comportamiento de Agent Zero se leyó del código fuente de la rama main de agent0ai/agent-zero —models.py y conf/model_providers.yaml—, además de su documentación, versiones e incidencias, el 21 de septiembre de 2026; las clases de excepción y las cadenas de error de LiteLLM se leyeron dentro del wheel litellm 1.88.1 de PyPI, la versión que fija Agent Zero. Nada de esto se probó en tiempo de ejecución: no se ejecutó ninguna instalación ni se reprodujo ningún error de extremo a extremo. Las tarifas de tokens de Kunavo proceden del catálogo activo, y todas las cifras en dólares son cálculos ilustrativos de tokens.