Agent Zero LiteLLMモデルエラー：認証、モデルID、エンドポイント

Agent ZeroのLiteLLMモデルエラーは、Agent Zeroが入力したモデル名をそのまま送信しないため、キーの問題よりもプレフィックスまたはロールの問題であることが多いです。agent0ai/agent-zeroのmainでは、models.pyがすべてのLiteLLM呼び出しの前にf"{provider}/{model}"を構築します。チャットでは385行目、埋め込みでは800行目です。プロバイダー部分はドロップダウンのラベルではなく、conf/model_providers.yamlから取得されます。

残りの意味を決める2つのバージョン情報があります。最新リリースはv2.12、2026年9月9日公開で、古いfrdel/agent-zeroパスは現在agent0ai/agent-zeroに解決されるため、古いcloneコマンドとIssueリンクはリダイレクトに到達します。また、requirements.txtはlitellm==1.88.1を固定し、コメントは# CVE-2026-42271 fix: patched floor is 1.83.7です。PyPIではこれを2026年6月9日付けとし、現在の1.102.0は2026年9月20日付けです。症状はLiteLLMの現在のドキュメントではなく、1.88.1を基準に確認してください。すべて2026年9月21日に確認しました。

キーに触れる前にステータスコードを読む

例外に整数のステータスコードが含まれる場合、_is_transient_litellm_errorはそれだけで判定します。408、429、500、502、503、504ではtrue、その他の5xxでもtrue、それ以外のステータスではfalseです。ステータスコードが存在しない場合に限り、タイムアウトや接続エラーを含む例外クラスとの照合にフォールバックします。したがって「ステータスなし」は、指し示せる4xx/5xxがなくてもリトライが発生し得る唯一のケースです。以下の表の各クラスにはステータスがあり、litellm 1.88.1のwheel内で確認しました。

1つの例外と、1つの見落としがあります。models.pyの638行目は、got_any_chunkがtrueの場合にリトライせず例外を発生させるため、ストリーム途中で発生した一時的なエラーはリトライされません。「即座に失敗した」は手掛かりであって証明ではありません。また、configure_litellm()はインポート時に実行され、LITELLM_LOG=ERRORとlitellm.suppress_debug_info = Trueを設定します。1.88.1では、get_llm_provider_logic.py内のプロバイダー一覧のヒントがif litellm.suppress_debug_info is Falseで保護されています。LiteLLMがプロバイダー一覧を示すために出力する唯一の行を、Agent Zeroが無効にしている箇所です。

入力したIDは、送信されるIDではない

プロバイダーごとに2つの識別子があり、プロバイダー設定のヘッダーがそれを示しています。プロバイダーIDは「設定UIのドロップダウン」とAPIキーの環境変数を決め、一方でlitellm_providerは「LiteLLMにおける対応するプロバイダー名」です。前置されるのは後者です。サードパーティのOpenAI互換エンドポイントでは、プロバイダーIDはother（「Other OpenAI compatible」）で、そのlitellm_providerはopenaiです。また、_adjust_call_argsもotherをopenaiに再マッピングします。通信上の値はopenai/<your-model>で、LiteLLMが文書化している形式です。したがって、プレフィックスなしのIDだけを入力してください。この2つのコード箇所を読むと、自分でプレフィックスを追加した場合はopenai/openai/gpt-4oになりますが、これはコードからの推論であり、観測されたエラーではありません。

解決に失敗した場合、1.88.1には明確に異なる2つの文字列があり、どちらも400です。get_llm_provider_logic.pyはBadRequestErrorを発生させ、「LLM Provider NOT provided … You passed model=…」を示します。文字列から利用可能な情報は何も導出されませんでした。exceptions.pyの902行目にあるLiteLLMUnknownProviderは、「Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=…」というメッセージを伴います。プロバイダーは確かに導出されましたが、そのエンドポイントにはそのプロバイダー用のルートがありません。ある役割では機能するプロバイダーが、別の役割では機能しない場合に予想されるのは後者です。

1つの不一致が、人々を誤ったフィールドへ誘導します。Agent ZeroのFAQでは、OpenRouterにはopenai/gpt-5.3が正しい一方、ネイティブOpenAIプロバイダーには誤りであり、「プレフィックスなしで動作する」と説明されています。また、インストールガイドの命名表では、OpenAIを「モデル名のみ」としています。これらはテキストボックスについての説明であり、その上にコードがプレフィックスを付加します。レイヤーを明示すれば、両方とも正しい説明です。その表には別のドキュメント上のバグもあり、OpenAI行の例にAnthropicのモデルIDを使っています。このセルをコピーしないでください。

失敗した役割が3つのうちどれかを特定する

Agent Zeroは、チャット、ユーティリティ、埋め込みの3つの役割を個別に設定し、それぞれに独自のプロバイダー、モデル名、APIベースを持たせます。設定セクションはchat_model、utility_model、embedding_modelで、従来のフラットキーはchat_model_*、util_model_*、embed_model_*です。settings.jsonで間違った規則を検索しても何も見つかりません。さらに、知っておく価値のある任意の第4の選択があります。組み込みブラウザープラグインには独自のmodel_presetがあり、空の状態で提供され、「空の場合は、実際に適用されるメインモデルを使用する」と文書化されています。したがって設定しない限り、ブラウザーツールの失敗は別名で呼ばれるチャット役割の失敗です。チャットの応答が1回成功しても、1つの役割が機能したことしか証明せず、3つすべてが機能したことは証明しません。

埋め込み役割は、トリアージを変える2つの点で異なります。LiteLLMEmbeddingWrapper.embedはLiteLLMのembedding()をtry/exceptなし、試行ループなしで呼び出すため、クラスに関係なく最初の試行で例外を発生させます。また、同梱のデフォルトはプロバイダーhuggingface、名前sentence-transformers/all-MiniLM-L6-v2です。models.pyは、huggingface名がsentence-transformers/で始まる場合、それをインプロセスラッパーへルーティングします。このラッパーは、HuggingFace API呼び出しを回避するとコードに記載されているため、そこでの障害にネットワーク呼び出しが関係するとは限りません。

Kunavoは埋め込みモデルを提供していないため、Agent ZeroでKunavoキーが担える役割はチャットとユーティリティです。

OpenRouterは確認済みの役割分割であり、ここで推測ではなくメンテナーによる修正が存在する唯一の分岐です。Issue #1597「OpenRouter embedding models fail due to LiteLLM missing provider route」は2026年5月2日に起票され、同年8月27日、同日にv2.11がリリースされる数時間前にクローズされました。ここでは混同しやすい2つの点を分ける必要があります。設定は役割ごとにプロバイダーをルーティングしています。chatはネイティブのlitellm_provider: openrouterを維持し、embeddingはlitellm_provider: openaiと明示的なapi_baseを使用します。これはOpenRouterが「LiteLLMではまだサポートされていない」というメンテナーのTODOの下で行われています。しかし、この分割はv2.10タグでもmainでも同じなので、Issueをクローズした原因ではありません。実際の変更はmodels.pyの1行です。v2.10では埋め込みラッパーがf"{provider}/{model}" if provider != "openai" else modelを構築し、openaiでルーティングされたすべての埋め込みからプレフィックスを削除していました。v2.11以降は無条件にプレフィックスを付けるため、スラッシュを含むIDがそのままエンドポイントに到達するようになったと、メンテナーのクローズコメントが述べています。この分岐での修正は設定変更ではなくアップグレードです。

キーの検索と、「キーを変更する」だけでは解決しないことが多い理由

get_api_key(service)は3つの環境変数名を固定された順序で読み取り、最後にリテラル文字列"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.

そのプレースホルダーは除外されます。呼び出し元は、それを付加する前に api_key not in ("None", "NA") を確認するため、キーが解決されない場合はapi_key 引数が一切送信されず、代わりに LiteLLM が独自の環境変数検索を行います。自分で選んだ覚えのない認証情報が原因で 401 が返されることがあります。2 回目の検索では、異なる service の値が使われます。_merge_provider_defaults は元のプロバイダー ID に対応するキーを読み取り、その後 _get_litellm_chat が get_api_key(provider_name) にフォールバックしますが、その時点ではその名前は LiteLLM のプロバイダー名、つまり other の場合は openai になっています。そのため、API_KEY_OTHER が未設定で、同じ .env に OpenAI のキーがあると、OpenAI のキーが自分のエンドポイントに送信されます。これは main 上のその 2 つの関数を読んで確認した内容です。ドキュメントには記載されておらず、ここでは実行時のテストは行っていません。

インストールガイドでは、キーをExternal Services → Other OpenAI-compatible API keysに配置し、プロバイダーとしてOpenAI Compatibleを選ぶよう案内しています。近くに記載された2つの症状はモデルIDの障害ではありません。送信しても何も起きない場合、FAQはSettingsでキーが設定されていないことを原因として挙げています。また、ChatGPT PlusにはAPIクレジットが含まれません。ただし、同梱のOAuthプラグインにはcodex_oauth接続があり、OpenAIアカウントでサインインするため、「サブスクリプションではAgent Zeroを動かせない」という説明は誤りです。

エンドポイントと、矛盾しているように見える2つのルール

otherプロバイダーにはデフォルトのapi_baseがありません。また、ModelConfig.build_kwargsはそのフィールドを空でない場合にのみ転送します。したがってAPI URLが空欄ならベースは送信されず、LiteLLMの標準openaiデフォルトが適用されます。1.88.1でそれがどのホストに解決されるかはここでは確認していません。空欄のURLで401が返る場合は、診断ではなくフィールドを入力する理由として扱ってください。LiteLLMの互換エンドポイントページには、正反対に見える2つの注記があります。「ベースURLに、たとえば/v1/embeddingなど、追加の要素を一切付けないでください」と、「テスト時にNot Found Errorが表示された場合は、api_baseの末尾に/v1が付いていることを確認してください」です。これは1つのルールとして整合します。/v1で終え、その後には何も追加しません。

Dockerでは、インストールガイドが明確に、APIベースURL内のlocalhostと127.0.0.1はコンテナを意味すると説明しています。http://host.docker.internal:<port>、またはデフォルトのLinuxブリッジ上のhttp://172.17.0.1:<port>のようなゲートウェイアドレスを使用し、ホストのループバックにバインドされたサーバーは0.0.0.0のようなDockerから到達可能なアドレスへ移します。その後、読み込んでいる設定が実際に実行された設定であることを確認してください。A0_SET_のプリセットは初期デフォルトにすぎず、「settings.jsonに値が保存されると、これらの環境変数より優先されます」。再起動が必要です。別途、Issue #1769（2026年7月15日起票、現在もオープン）では、モデルに登録されたプロバイダーと実際に提供しているプロバイダーが異なる場合に、LiteLLMがexit(-9)を呼び出すと報告されています。これは1人の報告者による分析であり、未確認で、ここでは再現していません。

誤った修正にかかるコスト

失敗しているユーティリティ役割を黙らせる最も早い方法は、メインモデルを指定することです。機能はしますが、インストールガイドが要約とメモリ抽出として説明するトラフィックに、メインモデルの料金が適用されます。以下の数値は実測のタスクコストでも請求上限でもなく、例示的なトークン計算です。1日のメインモデル作業を入力1200kトークン、出力60kトークン、ユーティリティトラフィックを入力320k、出力24kトークンと仮定し、100万トークン当たりの現在のKunavoカタログ料金を使います。

メイン役割自体のモデル料金は、その日について$3.150です。ユーティリティ役割をClaude Sonnet 4.6に統合すると、$0.924が追加されます。Claude Haiku 4.5モデルの料金は$0.308です。ただし、性能要件の下限に注意してください。インストールガイドは、ユーティリティモデルが「メモリを確実に抽出・統合できるほど強力」である必要があり、約4Bの非常に小さなモデルは通常、信頼できるコンテキスト抽出に失敗すると警告しています。ガイドはこれをエラーではなくタスクの失敗として説明しているため、「モデルでエラーが発生した」という診断が誤りになる分岐です。

Agent Zero自体のライセンス費用はありません。mainのLICENSEはMIT文で、著作権表示は「Agent Zero, s.r.o」です。費用が発生するのは、設定した役割全体で使用するモデルのトークンです。Kunavoのカタログ金額は請求下限であり、上限ではありません。上流が料金を報告すると、請求額はカタログコストと、適用されるマークアップを掛けた上流コストの大きい方になります。最低チャージ額は$10の前払いクレジットです。請求の詳細を参照してください。

役割の背後に置くルート

役割ごとの予算についてはAgent ZeroのAPIコストを、3つ目のスロットについては埋め込みモデルの変更を、ベースURLとプレフィックスの一般的な規則についてはOpenAI互換APIを参照してください。Kunavoキーをotherに接続するには、まずエラーリファレンスから始め、次にアカウントを作成してください。Agent ZeroはKunavoのエンドポイントでランタイムテストされていないため、試す間は動作するルートを維持してください。

よくある質問

Agent Zeroの動作は、2026年9月21日時点で、agent0ai/agent-zeroのmainブランチ（models.pyおよびconf/model_providers.yaml）と、そのドキュメント、リリース、Issueから確認しました。LiteLLMの例外クラスとエラー文字列は、Agent Zeroが固定しているバージョンであるPyPIのlitellm 1.88.1のwheel内で確認しました。ここではランタイムテストを一切行っておらず、インストールも実行していなければ、エンドツーエンドでエラーを再現してもいません。Kunavoのトークン料金はライブカタログから取得し、すべての金額は例示的なトークン計算です。