Erros de modelo LiteLLM do Agent Zero: autenticação, IDs de modelo e endpoints

Um erro de modelo do LiteLLM no Agent Zero é mais frequentemente um problema de prefixo ou de função do que de chave, porque o Agent Zero nunca envia o nome de modelo que você digitou. No branch agent0ai/agent-zero main, models.py constrói f"{provider}/{model}" antes de cada chamada ao LiteLLM — linha 385 para chat, linha 800 para embedding — e a metade do provedor vem de conf/model_providers.yaml, não do rótulo do menu suspenso.

Dois fatos de versão determinam o significado do restante. A versão mais recente é v2.12, publicada em 9 de setembro de 2026, e o caminho antigo frdel/agent-zero agora resolve para agent0ai/agent-zero, portanto comandos de clone e links de issues antigos chegam a um redirecionamento. E requirements.txt fixa litellm==1.88.1, com o comentário # CVE-2026-42271 fix: patched floor is 1.83.7. O PyPI data isso de 9 de junho de 2026, contra a versão atual 1.102.0 de 20 de setembro de 2026. Verifique os sintomas contra 1.88.1, não contra a documentação atual do LiteLLM. Tudo verificado em 21 de setembro de 2026.

Leia o código de status antes de mexer na chave

Quando a exceção contém um código de status inteiro, _is_transient_litellm_error decide apenas com base nele: verdadeiro para 408, 429, 500, 502, 503 e 504, verdadeiro para qualquer outro 5xx, falso para qualquer outro status. Somente quando não há código de status ele recorre à correspondência de classes de exceção — incluindo timeouts e erros de conexão — portanto "sem status" é o único caso em que uma repetição pode acontecer sem um 4xx/5xx apontável. Todas as classes na tabela abaixo carregam um status, e foram lidas dentro do wheel litellm 1.88.1.

Uma exceção e um ponto cego. A linha 638 de models.py gera a exceção em vez de repetir quando got_any_chunk é true, portanto um erro transitório ocorrido no meio do streaming não é repetido — "falhou imediatamente" é uma pista, não uma prova. E configure_litellm() é executado na importação, definindo LITELLM_LOG=ERROR e litellm.suppress_debug_info = True. Na versão 1.88.1, a indicação de lista de provedores em get_llm_provider_logic.py é protegida por if litellm.suppress_debug_info is False — a única linha que o LiteLLM imprimiria para encaminhar você à lista de provedores é a linha que o Agent Zero desativa.

O ID que você digitou não é o ID enviado

Existem dois identificadores por provedor, e o cabeçalho provider config deixa isso claro: o ID do provedor controla "os menus suspensos da interface de configurações" e a variável de ambiente da chave de API, enquanto litellm_provider é "O nome de provedor correspondente no LiteLLM". É o segundo que é acrescentado como prefixo. Para um endpoint de terceiros compatível com OpenAI, o ID do provedor é other ("Other OpenAI compatible"), cujo litellm_provider é openai, e _adjust_call_args também remapeia other para openai. O valor transmitido é openai/<your-model>, o formulário documentado pelo LiteLLM. Portanto, digite o ID simples: ao ler esses dois pontos do código, acrescentar o prefixo por conta própria produziria openai/openai/gpt-4o — raciocínio sobre o código, não um erro observado.

Quando a resolução falha, a versão 1.88.1 tem duas strings distintas, ambas 400. get_llm_provider_logic.py gera BadRequestError com "LLM Provider NOT provided … You passed model=…" — nada utilizável foi derivado da string. LiteLLMUnknownProvider em exceptions.py linha 902 contém "Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=…" — um provedor foi derivado, mas não há uma rota para ele nesse endpoint. É isso que se deve esperar quando um provedor funciona para uma função, mas não para outra.

Um conflito envia as pessoas para o campo errado. A FAQ do Agent Zero diz que openai/gpt-5.3 está correto para OpenRouter, mas incorreto para o provedor OpenAI nativo, "que não usa prefixo", e a tabela de nomes do guia de instalação lista OpenAI como "Model name only". Isso descreve a caixa de texto; o código acrescenta o prefixo sobre ela. Ambos são verdadeiros quando a camada é identificada. Essa tabela também contém um erro de documentação — sua linha de OpenAI usa um ID de modelo Anthropic como exemplo — portanto não copie o conteúdo da célula.

Descubra qual das três funções falhou

O Agent Zero configura três funções independentemente — chat, utilitária e embedding — cada uma com seu próprio provedor, nome de modelo e base de API. As seções de configurações são chat_model, utility_model e embedding_model, enquanto as chaves simples legadas são chat_model_*, util_model_* e embed_model_*; pesquisar settings.json usando a convenção errada não encontra nada. Há uma quarta seleção opcional que vale conhecer: o plugin de navegador incluído tem seu próprio model_preset, distribuído vazio e documentado como "Empty uses the effective Main Model" — portanto, a menos que você o defina, uma falha da ferramenta de navegador é a função de chat falhando com outro nome. E uma resposta de chat bem-sucedida prova que uma função funciona, não três.

A função de embedding difere em dois aspectos que mudam a triagem. LiteLLMEmbeddingWrapper.embed chama o embedding() do LiteLLM sem try/except e sem loop de tentativas, portanto gera a exceção na primeira tentativa, independentemente da classe. E o padrão distribuído é o provedor huggingface com o nome sentence-transformers/all-MiniLM-L6-v2; models.py encaminha qualquer nome huggingface que comece com sentence-transformers/ para um wrapper no processo que o código descreve como evitando chamadas à API da HuggingFace, portanto uma falha ali pode não envolver nenhuma chamada de rede.

A Kunavo não oferece nenhum modelo de embedding, portanto as funções que uma chave Kunavo pode preencher no Agent Zero são chat e utilitária.

OpenRouter é a separação de funções confirmada e o único branch aqui com uma correção do mantenedor, e não uma inferência. A issue #1597, "OpenRouter embedding models fail due to LiteLLM missing provider route", foi aberta em 2 de maio de 2026 e encerrada em 27 de agosto de 2026, horas antes do lançamento da v2.11 naquele mesmo dia. É preciso separar duas coisas, porque é fácil confundi-las. A configuração de fato roteia o provedor por função — chat mantém litellm_provider: openrouter nativo, enquanto embedding usa litellm_provider: openai mais um api_base explícito, sob o TODO dos mantenedores de que o OpenRouter "not yet supported by LiteLLM" — mas essa divisão aparece de forma idêntica na tag v2.10 e no main, portanto não foi o que encerrou a issue. A mudança que a encerrou é uma linha de models.py: na v2.10, o wrapper de embedding construía f"{provider}/{model}" if provider != "openai" else model, removendo o prefixo de todo embedding roteado por openai, e a partir da v2.11 ele acrescenta o prefixo incondicionalmente, razão pela qual a nota de encerramento do mantenedor diz que IDs contendo uma barra agora chegam intactos ao endpoint. Nesse branch, a correção é atualizar, não alterar as configurações.

A busca da chave e por que "alterar a chave" muitas vezes não resolve

get_api_key(service) lê três nomes de ambiente em uma ordem fixa e recorre à string 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.

Esse placeholder é filtrado — o ponto de chamada verifica api_key not in ("None", "NA") antes de anexá-lo — portanto uma chave não resolvida significa que nenhum argumento api_key é enviado, e o LiteLLM executa sua própria busca no ambiente. Um 401 pode vir de uma credencial que você nunca escolheu. Uma segunda busca usa um valor service diferente: _merge_provider_defaults lê a chave sob o ID original do provedor, depois _get_litellm_chat recorre a get_api_key(provider_name), momento em que esse nome já é o provedor do LiteLLM — openai, para other. Assim, um API_KEY_OTHER não definido junto de uma chave OpenAI no mesmo .env envia a chave OpenAI ao seu endpoint. Leitura dessas duas funções no main; não documentado e não testado em tempo de execução aqui.

O guia de instalação coloca a chave em External Services → Other OpenAI-compatible API keys, e depois OpenAI Compatible como provedor. Dois sintomas documentados próximos não são falhas de ID de modelo: quando nada acontece ao enviar, a FAQ atribui a causa a chaves não definidas em Settings; e o ChatGPT Plus não inclui créditos de API — embora o plugin OAuth incluído traga uma conexão codex_oauth que inicia sessão com uma conta OpenAI, portanto seria errado dizer que "nenhuma assinatura pode operar o Agent Zero".

O endpoint e duas regras que parecem contraditórias

O provedor other não fornece nenhum api_base padrão, e ModelConfig.build_kwargs encaminha esse campo somente quando não está vazio — portanto uma URL de API em branco não envia base alguma, e o padrão openai do LiteLLM é aplicado. Qual host isso resolve na versão 1.88.1 não foi verificado aqui; trate um 401 em uma URL em branco como motivo para preencher o campo, não como diagnóstico. A página de endpoints compatíveis do LiteLLM então traz duas observações em sentidos opostos: "NÃO adicione nada adicional à URL base, por exemplo /v1/embedding" e "Se você vir Not Found Error ao testar, certifique-se de que seu api_base tenha o sufixo /v1." Elas se conciliam como uma única regra — termine em /v1 e não acrescente nada depois.

No Docker, o guia de instalação é explícito: localhost e 127.0.0.1 em uma URL base de API significam o contêiner: use http://host.docker.internal:<port>, ou um endereço de gateway como http://172.17.0.1:<port> na bridge Linux padrão, e mova um servidor vinculado ao loopback do host para algo acessível pelo Docker, como 0.0.0.0. Depois confirme que a configuração lida é a que foi executada: os padrões de A0_SET_ são apenas valores iniciais — "Depois que um valor é salvo em settings.json, ele tem precedência sobre essas variáveis de ambiente" — e é necessário reiniciar. Separadamente, a issue #1769 (aberta em 15 de julho de 2026, ainda aberta) relata que o LiteLLM chama exit(-9) quando o provedor registrado de um modelo difere daquele que o atende: a análise de um relator, não confirmada e não reproduzida aqui.

O custo da correção errada

A maneira mais rápida de silenciar uma função utilitária com falha é apontá-la para o modelo principal. Funciona, e a cobrança usa a tarifa do modelo principal para o tráfego que o guia de instalação descreve como resumo e extração de memória. Estes valores são aritmética ilustrativa de tokens, não custos de tarefas medidos nem um limite de cobrança: suponha um dia de trabalho do modelo principal com 1200k tokens de entrada e 60k de saída, tráfego utilitário de 320k e 24k, e tarifas atuais do catálogo da Kunavo por milhão de tokens.

O próprio papel principal modela a $3.150 naquele dia; colocar o papel de utilidade em Claude Sonnet 4.6 acrescenta $0.924, enquanto Claude Haiku 4.5 modela a $0.308. Mas atenção ao nível mínimo de capacidade: o guia de instalação alerta que os modelos de utilidade precisam ser "fortes o bastante para extrair e consolidar memória de forma confiável" e que modelos muito pequenos, em torno de 4B, geralmente falham na extração confiável de contexto. O guia descreve isso como uma falha na tarefa, e não como um erro, portanto este é o caso em que "o modelo apresentou erro" é o diagnóstico errado.

O próprio Agent Zero não custa nada para licenciar — seu LICENSE no branch main contém texto MIT, com copyright "Agent Zero, s.r.o" — portanto o custo está nos tokens dos modelos entre os papéis que você configurar. O valor do catálogo da Kunavo é um piso de cobrança, não um teto: quando o upstream informa sua cobrança, a fatura é o maior valor entre o custo do catálogo e o custo do upstream multiplicado pelo markup aplicável. O recarregamento mínimo é de $10 em crédito pré-pago. Consulte detalhes de cobrança.

Qual rota colocar por trás dos papéis

Para o orçamento por papel, consulte Custos da API do Agent Zero; para aquele terceiro slot, alteração do modelo de embeddings; para as convenções gerais de URL base e prefixo, consulte API compatível com OpenAI. Para conectar uma chave da Kunavo a other: comece pela referência de erros e depois crie uma conta. O Agent Zero ainda não foi testado em tempo de execução com o endpoint da Kunavo, portanto mantenha uma rota funcional disponível enquanto você o experimenta.

Perguntas frequentes

Comportamento do Agent Zero lido no código-fonte do branch main de agent0ai/agent-zero — models.py e conf/model_providers.yaml — além de sua documentação, releases e issues, em 21 de setembro de 2026; classes de exceção e mensagens de erro do LiteLLM lidas dentro do wheel litellm 1.88.1 do PyPI, versão fixada pelo Agent Zero. Nada aqui foi testado em tempo de execução: nenhuma instalação foi executada e nenhum erro foi reproduzido de ponta a ponta. As tarifas de tokens da Kunavo vêm do catálogo ativo, e todos os valores em dólares são cálculos ilustrativos de tokens.