Kesalahan model Agent Zero LiteLLM: autentikasi, ID model, dan endpoint

Kesalahan model LiteLLM Agent Zero lebih sering merupakan masalah prefix atau peran daripada masalah key, karena Agent Zero tidak pernah mengirim nama model yang Anda ketik. Pada agent0ai/agent-zero main, models.py membangun f"{provider}/{model}" sebelum setiap panggilan LiteLLM — baris 385 untuk chat, baris 800 untuk embedding — dan bagian provider berasal dari conf/model_providers.yaml, bukan label dropdown.

Dua fakta versi menentukan arti bagian selanjutnya. Rilis terbaru adalah v2.12, diterbitkan 9 September 2026, dan path lama frdel/agent-zero kini mengarah ke agent0ai/agent-zero, sehingga perintah clone dan tautan issue lama mengalami redirect. Dan requirements.txt mematok litellm==1.88.1, dengan komentar # CVE-2026-42271 fix: patched floor is 1.83.7. PyPI mencatatnya pada 9 Juni 2026 dibandingkan 1.102.0 saat ini dari 20 September 2026. Periksa gejala terhadap 1.88.1, bukan dokumentasi LiteLLM saat ini. Semuanya diperiksa 21 September 2026.

Baca kode status sebelum menyentuh key

Saat exception membawa kode status bilangan bulat, _is_transient_litellm_error menentukan berdasarkan hal itu saja: true untuk 408, 429, 500, 502, 503, dan 504, true untuk 5xx lainnya, false untuk status lainnya. Hanya ketika tidak ada kode status, fungsi itu beralih mencocokkan kelas exception — termasuk timeout dan kesalahan koneksi — sehingga "tanpa status" adalah satu-satunya kasus ketika percobaan ulang dapat terjadi tanpa 4xx/5xx sebagai acuan. Setiap kelas dalam tabel di bawah membawa status, dan semuanya dibaca di dalam wheel litellm 1.88.1.

Satu exception dan satu titik buta. models.py baris 638 memunculkan exception alih-alih mencoba ulang ketika got_any_chunk bernilai true, sehingga kesalahan sementara yang datang di tengah streaming tidak dicoba ulang — "gagal seketika" adalah petunjuk, bukan bukti. Dan configure_litellm() berjalan saat import, menetapkan LITELLM_LOG=ERROR dan litellm.suppress_debug_info = True. Dalam 1.88.1, petunjuk daftar provider di get_llm_provider_logic.py dilindungi oleh if litellm.suppress_debug_info is False — satu-satunya baris yang akan dicetak LiteLLM untuk mengarahkan Anda ke daftar providernya adalah baris yang dimatikan Agent Zero.

Id yang Anda ketik bukan id yang dikirim

Setiap provider memiliki dua identifier, dan header provider config menjelaskannya: Provider ID mengendalikan "the settings UI dropdowns" dan environment variable API key, sedangkan litellm_provider adalah "The corresponding provider name in LiteLLM". Identifier kedua itulah yang ditambahkan di depan. Untuk endpoint kompatibel OpenAI pihak ketiga, provider id-nya adalah other ("Other OpenAI compatible"), yang litellm_provider-nya adalah openai, dan _adjust_call_args juga memetakan ulang other menjadi openai. Nilai wire-nya adalah openai/<your-model>, sesuai formulir yang didokumentasikan LiteLLM. Jadi ketik id tanpa prefix: dari membaca dua lokasi kode tersebut, menambahkan prefix sendiri akan menghasilkan openai/openai/gpt-4o — penalaran tentang kode, bukan kesalahan yang diamati.

Saat resolusi gagal, 1.88.1 memiliki dua string berbeda, keduanya 400. get_llm_provider_logic.py memunculkan BadRequestError dengan "LLM Provider NOT provided … You passed model=…" — tidak ada sesuatu yang dapat digunakan yang diturunkan dari string tersebut. LiteLLMUnknownProvider pada exceptions.py baris 902 membawa "Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=…" — sebuah provider telah diturunkan, tetapi tidak ada rute untuknya pada endpoint tersebut. Yang kedua diharapkan ketika sebuah provider berfungsi untuk satu peran tetapi tidak untuk peran lainnya.

Satu konflik mengarahkan orang ke kolom yang salah. FAQ Agent Zero menyatakan openai/gpt-5.3 benar untuk OpenRouter tetapi salah untuk provider OpenAI native, "which goes without prefix", dan tabel penamaan dalam panduan instalasi mencantumkan OpenAI sebagai "Model name only". Keduanya menjelaskan kotak teks; kode menambahkan prefix di atasnya. Keduanya benar setelah lapisannya disebutkan. Tabel itu juga memiliki bug dokumentasi — baris OpenAI menggunakan id model Anthropic sebagai contoh — jadi jangan salin sel tersebut.

Cari tahu peran mana dari tiga peran yang gagal

Agent Zero mengonfigurasi tiga peran secara terpisah — chat, utility, dan embedding — masing-masing dengan provider, nama model, dan API base sendiri. Bagian pengaturannya adalah chat_model, utility_model, dan embedding_model, sedangkan key datar lama adalah chat_model_*, util_model_*, dan embed_model_*; mencari settings.json dengan konvensi yang salah tidak akan menemukan apa pun. Ada pilihan opsional keempat yang perlu diketahui: plugin browser bawaan memiliki model_preset sendiri, dikirim dalam keadaan kosong dan didokumentasikan sebagai "Empty uses the effective Main Model" — jadi kecuali Anda menetapkannya, kegagalan alat browser adalah peran chat yang gagal dengan nama lain. Dan satu balasan chat yang berhasil membuktikan satu peran berfungsi, bukan tiga.

Peran embedding berbeda dalam dua hal yang mengubah triase. LiteLLMEmbeddingWrapper.embed memanggil embedding() milik LiteLLM tanpa try/except dan tanpa loop percobaan, sehingga gagal pada percobaan pertama tanpa memandang kelasnya. Dan default bawaan adalah provider huggingface dengan nama sentence-transformers/all-MiniLM-L6-v2; models.py merutekan nama huggingface apa pun yang diawali sentence-transformers/ ke wrapper dalam proses yang oleh kode dijelaskan sebagai menghindari panggilan API HuggingFace, sehingga kesalahan di sana tidak harus melibatkan panggilan jaringan apa pun.

Kunavo tidak menyediakan model embedding, sehingga peran yang dapat diisi key Kunavo di Agent Zero adalah chat dan utility.

OpenRouter adalah pemisahan peran yang terkonfirmasi, dan satu-satunya cabang di sini dengan perbaikan maintainer, bukan inferensi. Issue #1597, "OpenRouter embedding models fail due to LiteLLM missing provider route", dibuka 2 Mei 2026 dan ditutup 27 Agustus 2026, beberapa jam sebelum v2.11 dirilis pada hari yang sama. Dua hal perlu dipisahkan di sana karena mudah tercampur. Konfigurasi memang merutekan provider berdasarkan peran — chat mempertahankan litellm_provider: openrouter native, sementara embedding menggunakan litellm_provider: openai ditambah api_base eksplisit, di bawah TODO maintainer bahwa OpenRouter "not yet supported by LiteLLM" — tetapi pemisahan itu terbaca sama pada tag v2.10 dan main, jadi bukan penyebab issue ditutup. Perubahan yang menyelesaikannya adalah satu baris models.py: pada v2.10 wrapper embedding membangun f"{provider}/{model}" if provider != "openai" else model, menghapus prefix pada setiap embedding yang dirutekan melalui openai, dan sejak v2.11 wrapper menambahkan prefix tanpa syarat, sehingga catatan penutupan maintainer menyatakan bahwa id yang mengandung slash kini mencapai endpoint secara utuh. Pada cabang tersebut, perbaikannya adalah upgrade, bukan perubahan pengaturan.

Pencarian key, dan mengapa "ganti key" sering tidak menyelesaikan masalah

get_api_key(service) membaca tiga nama environment dalam urutan tetap dan menggunakan string literal "None" sebagai fallback.

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

Placeholder tersebut difilter — lokasi pemanggilan memeriksa api_key not in ("None", "NA") sebelum melampirkannya — sehingga key yang belum terselesaikan berarti tidak ada argumen api_key yang dikirim sama sekali, dan LiteLLM menerapkan pencarian environment-nya sendiri. 401 dapat datang dari kredensial yang tidak pernah Anda pilih. Pencarian kedua menggunakan nilai service yang berbeda: _merge_provider_defaults membaca key berdasarkan id provider asli, lalu _get_litellm_chat menggunakan fallback ke get_api_key(provider_name), yang pada saat itu merupakan nama provider LiteLLM — openai, untuk other. Jadi API_KEY_OTHER yang tidak ditetapkan bersama key OpenAI dalam .env yang sama akan mengirim key OpenAI ke endpoint Anda. Baca dari kedua fungsi tersebut pada main; tidak terdokumentasi dan tidak diuji saat runtime di sini.

Panduan instalasi menempatkan key di bawah External Services → Other OpenAI-compatible API keys, lalu OpenAI Compatible sebagai provider. Dua gejala terdokumentasi di dekatnya bukanlah kesalahan id model: ketika tidak terjadi apa-apa saat pengiriman, FAQ menyalahkan key yang belum ditetapkan di Settings; dan ChatGPT Plus tidak menyertakan kredit API — meskipun plugin OAuth bawaan menyediakan koneksi codex_oauth yang masuk menggunakan akun OpenAI, sehingga pernyataan "no subscription can drive Agent Zero" akan salah.

Endpoint, dan dua aturan yang tampak bertentangan

Provider other tidak menyediakan api_base default, dan ModelConfig.build_kwargs hanya meneruskan field tersebut jika tidak kosong — sehingga API URL kosong tidak mengirim base dan default openai bawaan LiteLLM yang berlaku. Host mana yang dituju dalam 1.88.1 tidak diperiksa di sini; perlakukan 401 pada URL kosong sebagai alasan untuk mengisi field tersebut, bukan diagnosis. Halaman endpoint kompatibel LiteLLM kemudian memuat dua catatan yang arahnya berlawanan: "Do NOT add anything additional to the base url e.g. /v1/embedding" dan "If you see Not Found Error when testing make sure your api_base has the /v1 postfix." Keduanya selaras sebagai satu aturan — akhiri di /v1, jangan tambahkan apa pun setelahnya.

Di bawah Docker, panduan instalasi secara eksplisit menyatakan bahwa localhost dan 127.0.0.1 dalam API base URL berarti container: gunakan http://host.docker.internal:<port>, atau alamat gateway seperti http://172.17.0.1:<port> pada bridge Linux default, dan pindahkan server yang terikat ke loopback host ke sesuatu yang dapat dijangkau Docker seperti 0.0.0.0. Kemudian pastikan konfigurasi yang Anda baca adalah konfigurasi yang dijalankan: preset A0_SET_ hanyalah default awal — "Once a value is saved in settings.json, it takes precedence over these environment variables" — dan perlu restart. Secara terpisah, issue #1769 (dibuka 15 Juli 2026, masih terbuka) melaporkan LiteLLM memanggil exit(-9) ketika provider yang terdaftar untuk model berbeda dari provider yang melayaninya: analisis seorang pelapor, belum dikonfirmasi dan tidak direproduksi di sini.

Biaya perbaikan yang salah

Cara tercepat untuk membungkam peran utility yang gagal adalah mengarahkannya ke model utama. Ini berhasil, dan ditagihkan dengan tarif model utama untuk lalu lintas yang dijelaskan panduan instalasi sebagai peringkasan dan ekstraksi memori. Angka-angka ini adalah perhitungan token ilustratif, bukan biaya tugas yang diukur dan bukan batas atas tagihan: asumsikan satu hari pekerjaan model utama dengan 1200k token input dan 60k token output, lalu lintas utility sebesar 320k dan 24k, serta tarif katalog Kunavo saat ini per juta token.

Peran utama itu sendiri memodelkan pada $3,150 untuk hari tersebut; menambahkan peran utilitas pada Claude Sonnet 4.6 menambah $0,924, sedangkan Claude Haiku 4.5 memodelkan pada $0,308. Namun, perhatikan batas kemampuan: panduan instalasi memperingatkan bahwa model utilitas harus "cukup kuat untuk mengekstrak dan mengonsolidasikan memori secara andal" dan bahwa model yang sangat kecil, sekitar 4B, biasanya gagal mengekstrak konteks dengan andal. Panduan tersebut menggambarkannya sebagai kegagalan dalam menjalankan tugas, bukan sebagai kesalahan, jadi inilah kondisi ketika diagnosis "model mengalami error" adalah diagnosis yang keliru.

Agent Zero sendiri tidak memerlukan biaya lisensi — LICENSE-nya di main berisi teks MIT, dengan hak cipta "Agent Zero, s.r.o" — jadi biaya yang dikeluarkan adalah token model di seluruh peran yang Anda konfigurasi. Nominal katalog Kunavo adalah batas penagihan minimum, bukan batas maksimum: ketika upstream melaporkan biayanya, tagihan adalah nilai yang lebih besar antara biaya katalog dan biaya upstream dikalikan markup yang berlaku. Top-up minimum adalah kredit prabayar sebesar $10. Lihat detail penagihan.

Rute yang digunakan di balik peran

Untuk anggaran per peran, lihat biaya API Agent Zero; untuk slot ketiga itu, mengubah model embedding; untuk konvensi base URL dan prefiks secara umum, lihat OpenAI-compatible API. Untuk menghubungkan kunci Kunavo ke other, mulai dari referensi error, lalu buat akun. Agent Zero belum diuji saat runtime terhadap endpoint Kunavo, jadi siapkan rute yang berfungsi selama Anda mencobanya.

Pertanyaan umum

Perilaku Agent Zero dibaca dari source pada branch main agent0ai/agent-zero — models.py dan conf/model_providers.yaml — beserta dokumentasi, rilis, dan issue-nya, pada 21 September 2026; kelas pengecualian dan string error LiteLLM dibaca dari wheel litellm 1.88.1 di PyPI, versi yang dipatok Agent Zero. Tidak ada yang diuji saat runtime di sini: instalasi tidak dijalankan dan tidak ada error yang direproduksi secara end-to-end. Tarif token Kunavo berasal dari katalog live, dan setiap angka dolar adalah perhitungan token ilustratif.