Agent Zero LiteLLM model hataları: kimlik doğrulama, model kimlikleri ve uç noktalar

Agent Zero LiteLLM model hatası, bir anahtar sorunundan çok önek veya rol sorunudur; çünkü Agent Zero yazdığınız model adını hiçbir zaman göndermez. agent0ai/agent-zero main dalında models.py, her LiteLLM çağrısından önce f"{provider}/{model}" ifadesini oluşturur — sohbet için 385. satırda, embedding için 800. satırda — sağlayıcı kısmı açılır menü etiketinden değil, conf/model_providers.yaml dosyasından gelir.

Geri kalanların anlamını iki sürüm bilgisi belirler. En son sürüm v2.12, 9 Eylül 2026'da yayımlandı ve eski frdel/agent-zero yolu artık agent0ai/agent-zero'ye çözümleniyor; bu nedenle eski klon komutları ve issue bağlantıları yönlendirmeye gider. Ayrıca requirements.txt, litellm==1.88.1 sürümünü sabitler ve # CVE-2026-42271 fix: patched floor is 1.83.7 yorumunu içerir. PyPI bunu 9 Haziran 2026'ya, 1.102.0 güncel sürümünü ise 20 Eylül 2026'ya tarihlendiriyor. Belirtileri LiteLLM'in güncel belgelerine göre değil, 1.88.1'e göre kontrol edin. Tümü 21 Eylül 2026'da kontrol edildi.

Anahtara dokunmadan önce durum kodunu okuyun

İstisna bir tamsayı durum kodu taşıyorsa, _is_transient_litellm_error kararı yalnızca buna göre verir: 408, 429, 500, 502, 503 ve 504 için doğru; diğer tüm 5xx değerleri için doğru; diğer tüm durumlar için yanlış. Yalnızca durum kodu yoksa istisna sınıflarıyla eşleştirmeye — timeout ve bağlantı hatları dahil — geri döner; dolayısıyla "durum yok" bir 4xx/5xx olmadan yeniden denemenin gerçekleşebileceği tek durumdur. Aşağıdaki tablodaki her sınıf bir durum kodu taşır ve bunlar litellm 1.88.1 wheel'i içinde okundu.

Bir istisna ve bir kör nokta var. models.py dosyasının 638. satırında, got_any_chunk true olduğunda yeniden denemek yerine hata yükseltilir; bu nedenle akışın ortasında gelen geçici bir hata yeniden denenmez — "hemen başarısız oldu" bir ipucudur, kanıt değildir. Ayrıca configure_litellm(), içe aktarma sırasında çalışır ve LITELLM_LOG=ERROR ile litellm.suppress_debug_info = True ayarlarını uygular. 1.88.1'de get_llm_provider_logic.py dosyasındaki sağlayıcı listesi ipucu if litellm.suppress_debug_info is False koşuluna bağlıdır — LiteLLM'in sizi sağlayıcı listesine yönlendirmek için yazacağı tek satır, Agent Zero'nun kapattığı satırdır.

Yazdığınız kimlik gönderilen kimlik değildir

Sağlayıcı başına iki tanımlayıcı vardır ve sağlayıcı yapılandırması başlığı bunu belirtir: sağlayıcı kimliği "ayarlar kullanıcı arayüzündeki açılır menüleri" ve API anahtarı ortam değişkenini belirler; litellm_provider ise "LiteLLM'deki karşılık gelen sağlayıcı adıdır". Önek olarak eklenen ikincisidir. Üçüncü taraf OpenAI uyumlu bir uç nokta için sağlayıcı kimliği other ("Diğer OpenAI uyumlu") olur; bunun litellm_provider alanının değeri openai olur ve _adjust_call_args ayrıca other değerini openai olarak yeniden eşler. İletilen değer openai/<your-model> biçimindedir; bu, LiteLLM'in belgelediği biçimdir. Bu nedenle yalın kimliği yazın: bu iki kod konumuna göre, öneki kendiniz eklerseniz openai/openai/gpt-4o elde edersiniz — bu, gözlemlenmiş bir hata değil, koddan yapılan bir çıkarımdır.

Çözümleme başarısız olduğunda 1.88.1'de iki farklı hata dizesi vardır; her ikisi de 400 durum kodlu hatalara aittir. get_llm_provider_logic.py, BadRequestError hatasını "LLM Provider NOT provided … You passed model=…" mesajıyla yükseltir — dizeden kullanılabilir hiçbir şey türetilmemiştir. LiteLLMUnknownProvider, exceptions.py dosyasının 902. satırında "Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=…" mesajını taşır — bir sağlayıcı türetilmiştir, ancak o uç noktasında bunun için bir yönlendirme yoktur. Bir sağlayıcı bir rolde çalışıp başka bir rolde çalışmadığında beklemeniz gereken mesaj ikincisidir.

Bir çelişki, kullanıcıları yanlış alana yönlendiriyor. Agent Zero'nun SSS sayfası, openai/gpt-5.3 model kimliğinin OpenRouter için doğru, ancak "önek olmadan kullanılan" yerleşik OpenAI sağlayıcısı için yanlış olduğunu söylüyor; kurulum kılavuzunun adlandırma tablosu da OpenAI için "Yalnızca model adı" ifadesini kullanıyor. Bunlar metin kutusunu açıklar; kod bunun üzerine önek ekler. Hangi katmandan söz edildiği belirtildiğinde ikisi de doğrudur. Bu tabloda ayrıca bir dokümantasyon hatası vardır — OpenAI satırında örnek olarak bir Anthropic model kimliği kullanılmıştır — bu nedenle hücreyi kopyalamayın.

Üç rolden hangisinin başarısız olduğunu belirleyin

Agent Zero üç rolü — sohbet, yardımcı ve embedding — birbirinden bağımsız yapılandırır; her birinin kendi sağlayıcısı, model adı ve API tabanı vardır. Ayarlar bölümleri chat_model, utility_model ve embedding_model olarak, eski düz anahtarlar ise chat_model_*, util_model_* ve embed_model_* olarak adlandırılır; yanlış adlandırma biçimini settings.json dosyasında aramak hiçbir sonuç vermez. Bilinmesi gereken dördüncü, isteğe bağlı bir seçim daha vardır: birlikte gelen tarayıcı eklentisinin kendine ait bir model_preset değeri bulunur; bu değer boş olarak gönderilir ve "Boş bırakılırsa etkin Ana Model kullanılır" şeklinde belgelenir — dolayısıyla siz ayarlamadıkça tarayıcı aracı hatası, başka bir ad altındaki sohbet rolü hatasıdır. Ayrıca başarılı bir sohbet yanıtı, üç rolün değil yalnızca bir rolün çalıştığını kanıtlar.

Embedding rolü, sorun gidermeyi değiştiren iki açıdan farklıdır. LiteLLMEmbeddingWrapper.embed, LiteLLM'in embedding() işlevini try/except olmadan ve deneme döngüsü olmadan çağırır; bu nedenle sınıfı ne olursa olsun ilk denemede hata verir. Gönderilen varsayılan ise huggingface sağlayıcısı ve sentence-transformers/all-MiniLM-L6-v2 adıdır; models.py, sentence-transformers/ ile başlayan her huggingface adını, kodun HuggingFace API çağrılarından kaçındığını belirttiği işlem içi bir sarmalayıcıya yönlendirir; dolayısıyla buradaki bir arızanın herhangi bir ağ çağrısıyla ilgisi olmayabilir.

Kunavo hiçbir embedding modeli sunmaz; bu nedenle bir Kunavo anahtarının Agent Zero'da doldurabileceği roller sohbet ve yardımcı rolleridir.

OpenRouter, role göre ayrımın doğrulandığı örnektir ve burada bir çıkarım yerine bakımcıların sağladığı bir düzeltmenin bulunduğu tek durumdur. #1597 numaralı "OpenRouter embedding modelleri, LiteLLM sağlayıcı yönlendirmesi eksik olduğu için başarısız oluyor" başlıklı issue 2 Mayıs 2026'da açılmış ve aynı gün v2.11'in yayımlanmasından birkaç saat önce, 27 Ağustos 2026'da kapatılmıştır. Burada kolayca birbirine karıştırılabilecek iki şeyi ayırmak gerekir. Yapılandırma sağlayıcıyı role göre gerçekten yönlendirir — chat doğrudan litellm_provider: openrouter ayarını korurken embedding, bakımcıların OpenRouter'ın "henüz LiteLLM tarafından desteklenmediği" TODO'su kapsamında litellm_provider: openai ve açık bir api_base kullanır — ancak bu ayrım hem v2.10 etiketinde hem de main dalında aynıdır; dolayısıyla issue'yu kapatan şey bu değildir. Issue'nun kapanmasını sağlayan değişiklik models.py dosyasındaki tek bir satırdır: v2.10'da embedding sarmalayıcısı f"{provider}/{model}" if provider != "openai" else model ifadesiyle model kimliğini oluşturuyor, openai üzerinden yönlendirilen tüm embedding'lerde öneki düşürüyordu; v2.11'den itibaren önek koşulsuz eklenir. Bu nedenle bakımcının kapanış notu, eğik çizgi içeren kimliklerin artık uç noktaya eksiksiz ulaştığını söyler. Bu durumda düzeltme, ayar değişikliği değil yükseltmedir.

Anahtar araması ve "anahtarı değiştir" önerisinin neden çoğu zaman işe yaramadığı

get_api_key(service), üç ortam adını sabit bir sırayla okur ve "None" sabit dizesine geri döner.

# 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.

Bu yer tutucu filtrelenir — çağrı noktası, onu eklemeden önce api_key not in ("None", "NA") koşulunu kontrol eder — bu nedenle çözümlenmemiş bir anahtar, hiçbir api_key bağımsız değişkeninin gönderilmediği ve bunun yerine LiteLLM'in kendi ortam aramasını uyguladığı anlamına gelir. Hiç seçmediğiniz bir kimlik bilgisinden 401 gelebilir. İkinci aramada farklı bir service değeri kullanılır: _merge_provider_defaults, anahtarı orijinal sağlayıcı kimliği altında okur; ardından _get_litellm_chat, get_api_key(provider_name) çağrısına geri döner. Bu noktada bu ad LiteLLM sağlayıcısıdır — openai değeri, other için kullanılır. Bu nedenle API_KEY_OTHER değişkeni ayarlanmamışsa ve aynı .env dosyasında bir OpenAI anahtarı varsa OpenAI anahtarı uç noktanıza gönderilir. Bu bilgiler main dalındaki bu iki işlevin kodundan alınmıştır; belgelenmemiştir ve burada çalışma zamanında test edilmemiştir.

Kurulum kılavuzu anahtarın External Services → Other OpenAI-compatible API keys altında, sağlayıcının ise OpenAI Compatible olarak seçilmesini önerir. Yakındaki belgelenmiş iki belirti model kimliğiyle ilgili değildir: gönderim sırasında hiçbir şey olmuyorsa SSS, Ayarlar'da anahtarların ayarlanmamış olmasını neden olarak gösterir; ChatGPT Plus ise API kredisi içermez — ancak birlikte gelen OAuth eklentisi, bunun yerine OpenAI hesabıyla oturum açan bir codex_oauth bağlantısı gönderir. Bu nedenle "hiçbir abonelik Agent Zero'yu çalıştıramaz" demek yanlış olur.

Uç nokta ve çelişkili görünen iki kural

other sağlayıcısı varsayılan bir api_base sağlamaz ve ModelConfig.build_kwargs bu alanı yalnızca boş değilse iletir — bu nedenle boş bir API URL'si temel URL göndermez ve LiteLLM'in standart openai varsayılanı uygulanır. Bunun 1.88.1'de hangi ana makineye çözümlendiği burada kontrol edilmedi; boş URL'de 401 almayı, bir teşhis olarak değil alanı doldurma gerekçesi olarak değerlendirin. LiteLLM'in uyumlu uç nokta sayfasında ise ters yönlere çekiyor gibi görünen iki not vardır: "Temel URL'ye /v1/embedding gibi başka hiçbir şey eklemeyin" ve "Test ederken Not Found Error görürseniz api_base'nizde /v1 son ekinin bulunduğundan emin olun." Bunlar tek bir kural olarak uzlaştırılır — /v1'de bitirin, sonrasına hiçbir şey eklemeyin.

Docker altında kurulum kılavuzu, API temel URL'sindeki localhost ve 127.0.0.1 değerlerinin konteyneri ifade ettiğini açıkça belirtir: http://host.docker.internal:<port> adresini veya varsayılan Linux köprüsünde http://172.17.0.1:<port> gibi bir ağ geçidi adresini kullanın; ana makinenin loopback arayüzüne bağlı bir sunucuyu 0.0.0.0 gibi Docker'ın erişebileceği bir adrese taşıyın. Ardından okuduğunuz yapılandırmanın gerçekten çalıştırılan yapılandırma olduğunu doğrulayın: A0_SET_ ön ayarları yalnızca başlangıç varsayılanlarıdır — "Bir değer settings.json'a kaydedildiğinde bu değer ortam değişkenlerine göre öncelik kazanır" — ve yeniden başlatma gerekir. Ayrı olarak, #1769 numaralı issue (15 Temmuz 2026'da açıldı, hâlâ açık), modelin kayıtlı sağlayıcısı onu sunan sağlayıcıdan farklı olduğunda LiteLLM'in exit(-9) çağrısını yaptığını bildirir: bir raporlayıcının analizi, doğrulanmamış ve burada yeniden üretilmemiştir.

Yanlış düzeltmenin maliyeti

Başarısız bir yardımcı rolünü susturmanın en hızlı yolu, onu ana modele yönlendirmektir. Bu işe yarar ve kurulum kılavuzunun özetleme ile bellek çıkarma olarak tanımladığı trafik için ana modelin ücretlendirme oranını uygular. Bu rakamlar ölçülmüş görev maliyetleri veya fatura üst sınırı değil, örnek token hesabıdır: bir günlük ana model çalışmasının 1200k giriş ve 60k çıkış token'ı, yardımcı trafiğin 320k ve 24k token'ı kullandığını ve milyon token başına güncel Kunavo kataloğu oranlarını varsayın.

Ana rolün kendisi o gün $3,150 tutarındadır; yardımcı rol için de Claude Sonnet 4.6 modelini kullanmak, Claude Haiku 4.5 modeli için hesaplanan $0,308 tutarına kıyasla $0,924 ek maliyet getirir. Ancak asgari yetenek gereksinimini göz önünde bulundurun: kurulum kılavuzu, yardımcı modellerin "belleği güvenilir biçimde çıkarmak ve birleştirmek için yeterince güçlü" olması gerektiği ve yaklaşık 4B'lik çok küçük modellerin güvenilir bağlam çıkarımında genellikle başarısız olduğu konusunda uyarır. Kılavuz bunu bir hata yerine görevde başarısızlık olarak tanımlar; dolayısıyla "model hata verdi" ifadesinin yanlış teşhis olduğu dal budur.

Agent Zero'nun lisans maliyeti yoktur — main dalındaki LICENSE dosyası MIT metnidir ve telif hakkı "Agent Zero, s.r.o"'ya aittir — bu nedenle para, yapılandırdığınız roller arasında kullanılan model token'larına gider. Kunavo kataloğundaki tutar bir faturalandırma tabanı, üst sınır değil: upstream kendi ücretini bildirdiğinde fatura, katalog maliyeti ile upstream maliyetinin geçerli çarpanla çarpımından büyük olanıdır. Minimum yükleme $10 ön ödemeli kredidir. Faturalandırma ayrıntılarına bakın.

Rollerin arkasına hangi yönlendirmeyi koymalı

Rol başına bütçelendirme için Agent Zero API maliyetleri; üçüncü yuva için embedding modelini değiştirme; genel olarak temel URL ve önek kuralları için OpenAI uyumlu API. Kunavo anahtarını other seçeneğine bağlamak için hata referansından başlayın, ardından hesap oluşturun. Agent Zero, Kunavo'nun uç noktasına karşı çalışma zamanında test edilmemiştir; bu nedenle denerken çalışan bir yönlendirmeyi hazır tutun.

Sık sorulan sorular

Agent Zero davranışı, 21 Eylül 2026'da agent0ai/agent-zero main dalındaki kaynak koddan — models.py ve conf/model_providers.yaml — ayrıca belgelerinden, sürümlerinden ve issue'larından okunmuştur; LiteLLM istisna sınıfları ve hata dizeleri, Agent Zero'nun sabitlediği sürüm olan PyPI'daki litellm 1.88.1 wheel'i içinden okunmuştur. Buradaki hiçbir şey çalışma zamanında test edilmemiştir: kurulum çalıştırılmadı ve uçtan uca hiçbir hata yeniden üretilmedi. Kunavo token oranları canlı katalogdan alınmıştır ve her dolar tutarı örnek token hesabıdır.