初めに
AI アプリのサンプルは、たいてい client = OpenAI() から始まります。ですが、本番運用で本当に難しくなるのはその先です。provider ごとの差分をどう隠蔽するか、client をどこで生成して再利用するか、認証情報や model 選択をどう扱うか、timeout・retry・fallback をどの層に置くか、さらに observability やマルチテナント運用をどう設計するか。AI アプリが大きくなるほど、これらは単なる実装詳細ではなく、アーキテクチャそのものになります。(LangChain Docs)
本記事では、指定された 3 プロジェクトである Hermes Agent、OpenClaw、GraphRAG を起点に、追加調査対象として GitHub で 30k+ stars を持つ LangChain、LlamaIndex、LiteLLM、Dify を読み、AI Client 設計を横断的に整理します。ここでいう「AI Client 設計」とは、単なる SDK ラッパーではなく、provider abstraction / client lifecycle / routing / credential 管理 / reliability policy / observability を含む全体設計のことです。(GitHub)
先に結論
結論から言うと、今の良い AI Client 設計は 1 provider = 1 client では終わりません。成熟した OSS では、おおむね次の責務が分離されています。provider 差分を吸収する adapter / wrapper 層、client を生成・再利用・差し替えする factory / registry 層、model・provider・credential を選択する router / manager 層、retry・fallback・cooldown を持つ reliability policy 層、そして運用や監視を支える platform / observability 層です。Hermes Agent、GraphRAG、LiteLLM、Dify は、この多層構造をそれぞれ別の形で実装しています。(GitHub)
また、retry と fallback は同じものとして扱わない方がよいです。retry は「同じ候補に対する短い再試行」、fallback は「候補そのものを切り替える経路変更」です。OpenClaw は auth profile rotation と model fallback を二段階で分け、LiteLLM は function_with_fallbacks と function_with_retries を分離し、Hermes Agent は same-provider の credential rotation を cross-provider fallback より先に置いています。現時点の best practice は、まず同一 provider 内の credential / auth profile rotation を行い、その後に cross-model / cross-provider fallback に進むという流れだと考えています。(OpenClaw)
この記事でいう「AI Client設計」
この記事では、AI Client 設計を次の 6 つの観点で見ます。1) provider abstraction、2) client 生成とライフサイクル管理、3) routing / selection、4) retry / fallback / cooldown、5) credential・workspace・tenant 管理、6) observability です。LangChain は abstraction を、LlamaIndex は resolver と lifecycle を、LiteLLM は gateway / routing を、Dify は credential 運用と model management を、OpenClaw と Hermes Agent は reliability policy を、それぞれ強く見せています。(LangChain Docs)
1. Hermes Agent: Router中心で組み立てる AI Client 設計
Hermes Agent でまず目を引くのは、auxiliary_client.py が “shared auxiliary client router” として設計されている点です。docstring では、text task の解決順が OpenRouter → Nous Portal → custom endpoint → Codex OAuth を chat.completions 互換に包んだ client → Native Anthropic → direct API-key providers と明示されており、さらに auxiliary: セクションの per-task override も持てます。つまり Hermes は「各機能が勝手に client を new する」のではなく、用途ごとに最適 backend を 1 つの router で解決する設計を採っています。(GitHub)
さらに Hermes の credential pool は、AI Client 設計における「同一 provider 内 rotation」の良い参照例です。公式 docs では、credential pool は same-provider rotation であり、fallback provider は cross-provider failover だと明確に分けています。pool は fill_first、round_robin、least_used、random を持ち、429 では同じ key を一度だけ再試行してから rotation、402 では即 rotation、401 では token refresh を試し、すべての key が exhausted になって初めて fallback provider に進みます。つまり Hermes では、retry → same-provider rotation → cross-provider fallback の順序がかなり明確です。(エルメスエージェント)
Hermes から学べるのは、AI Client を「OpenAI SDK の初期化」ではなく、provider 解決・credential 解決・用途別 model 選択を担う router として扱うべきだ、ということです。特に agent や workflow では、要約・圧縮・検索補助・vision などで最適 backend が違うため、この router-first の発想はかなり実戦的です。(GitHub)
2. OpenClaw: auth profile rotation と model fallback を段階化する
OpenClaw は、retry / fallback を「AI Client の一部」としてかなり明示的に設計しています。公式 docs では、failover は二段階で処理されます。まず current provider 内の auth profile rotation、それでも失敗したら agents.defaults.model.fallbacks による model fallback です。さらに runtime flow では、candidate chain を構築し、同一 provider 内の profile を試し尽くしてから次の model candidate に進み、fallback candidate が失敗した場合は fallback-owned な session override フィールドだけを rollback する、と説明されています。(OpenClaw)
ここで重要なのは、OpenClaw が単に「次の model を試す」だけではないことです。rotation order は explicit config → configured profiles → stored profiles の順で決まり、明示 order がなければ OAuth 優先・lastUsed の古いもの優先の round-robin になります。さらに session stickiness により、同じ session では同じ auth profile を優先しつつ、rate limit や timeout では rotation できます。つまり OpenClaw は、可用性 と cache-friendly な安定性 を同時に見ています。(OpenClaw)
error taxonomy の設計も参考になります。OpenClaw では、auth failure、rate limit、overloaded、timeout-shaped error、billing disable などは fallback を進めますが、context overflow は compaction/retry logic に閉じ込め、明示 abort は fallback を進めません。cooldown も一律ではなく、通常は 1 分 → 5 分 → 25 分 → 1 時間の指数 backoff、billing failure は 5 時間から 24 時間までの長い disable に分かれています。加えて runWithModelFallback(...) は provider/model/reason/status/error summary を attempt ごとに記録します。fallback の有無より、「何の失敗なら進めるか」と「失敗後の state をどう保つか」が重要だと分かる設計です。(OpenClaw)
3. GraphRAG: Protocol / Factory / RetryConfig で整理する
GraphRAG は、OpenClaw のような aggressive failover よりも、拡張可能な model abstraction と config-driven な retry に重心があります。公式 docs では、GraphRAG は standard completion / embedding Protocol と accompanying factories を通じて custom model injection をサポートしており、register_completion("my-custom-completion-model", MyCustomCompletionModel) のように登録できます。CLI ではなく library 利用時の拡張として設計されている点も含め、これは典型的な protocol + factory パターンです。(GitHubのMicrosoft)
また GraphRAG の設定は settings.yml / settings.json に複数モデルを定義し、それらを workflow 内から参照する形になっています。docs では、GraphRAG は language model 呼び出しに LiteLLM を使い、model_provider、model、api_key、api_base、call_args、retry などを config として持てると説明されています。つまり GraphRAG は、AI Client をコード中の if provider == ... で切り替えるのではなく、構成可能な model registry として扱っています。(GitHubのMicrosoft)
retry も first-class object です。RetryConfig は type、max_retries、base_delay、jitter、max_delay を持ち、extra="allow" によって custom retry 実装の追加も想定しています。これは retry が decorator の内部事情ではなく、交換可能な戦略オブジェクトとして扱われていることを意味します。GraphRAG から学べるのは、最初から巨大な router を作らなくても、Protocol / Factory / RetryConfig を分離するだけで設計がかなり整理される、という点です。(GitHub)
4. 30k+ OSS から見える補助線
LangChain: provider abstraction と fallback の責務分離
LangChain の docs は、AI Client 抽象化の考え方をかなり素直に表しています。Providers and models では、すべての chat model が同じ interface を実装し、init_chat_model("provider:model") で provider を差し替えられると説明されています。さらに routers / proxies の章では、OpenRouter や LiteLLM のような gateway が automatic fallbacks や load balancing を提供できると明示されています。LangChain は、single API for any model という abstraction を前面に出しているわけです。(LangChain Docs)
一方で、LangChain は fallback を単一 model wrapper の責務に閉じ込めません。RunnableWithFallbacks の reference では、fallback は順番に試され、通常は with_fallbacks を使うのが便利だとされています。加えて ChatOpenAI の docs では max_retries、timeout、base_url、organization などが初期化パラメータとして exposed されており、OpenAI-compatible endpoint にも接続できます。つまり LangChain では、provider wrapper が client 生成を担い、cross-provider fallback は Runnable composition や router/proxy 側に持ち上げるという分離が見えます。(LangChain)
LlamaIndex: resolver と lifecycle control を API として出す
LlamaIndex は、AI Client 設計における resolver の良い例です。resolve_llm() は、文字列、既存 LLM instance、LangChain model、local: 形式、default、None などを受けて canonical な LLM object に解決します。デフォルトでは OpenAI を使い、local: なら LlamaCPP、LangChain model なら LangChainLLM で包みます。これは「new する client」を直接持つより、入力表現を正規化して LLM object に resolve する発想です。(GitHub)
OpenAI integration 側では、reuse_client が false なら毎回 SyncOpenAI / AsyncOpenAI を作り、true なら client を保持して再利用します。さらに _chat、_complete、_achat など主要メソッドには @llm_retry_decorator が付き、max_retries、random exponential backoff、最大 60 秒、最小 1 秒、最大 20 秒といった retry 設定が適用されます。LlamaIndex が示しているのは、client lifecycle と retry policy を adapter の public design として明示することの重要さです。(GitHub)
LiteLLM: AI Gateway / Router として完成度が高い
LiteLLM は、AI Client を「アプリ内部のライブラリ」ではなく AI Gateway として設計する代表例です。repo と docs では、LiteLLM は 100+ provider を OpenAI format で統一し、Python SDK としても Proxy Server としても使えるとされています。つまり LiteLLM の核心は、各アプリに provider ごとの SDK 差分を持ち込まないことです。(GitHub)
Router architecture では、request flow が function_with_fallbacks → function_with_retries → base unified function になっています。ここで retries は model group 内の再試行、fallbacks は経路変更です。さらに router は cooldowns、fallbacks、timeouts、retries、load balancing をまとめて扱い、production では Redis を使って cooldown や usage を追跡できます。LiteLLM は、routing / retries / fallbacks / load balancing を 1 つの制御面に集約する設計をはっきり打ち出しています。(LiteLLM)
fallback 設計も豊富です。SDK の completion(..., fallbacks=[...]) は primary model を先に呼び、失敗したら fallback を順に試し、rate-limited model は 60 秒 cooldown して skip します。Proxy 側では num_retries、fallbacks、allowed_fails、cooldown_time などをまとめて設定でき、さらに context window fallback や content policy fallback のような エラー種別別 fallback もサポートしています。これは「fallback を持つ」ことより、「どの failure mode にどの fallback を対応させるか」を構造化している点が重要です。(LiteLLM)
Dify: credential 運用と model management を platform として持つ
Dify は library というより platform ですが、AI Client 設計の運用面で非常に参考になります。repo では Dify を AI workflow / RAG / agent / model management / observability を含む platform と説明しており、ProviderManager は「Hosting と Customize Model Providers を管理する class」と明示されています。つまり Dify は、AI Client を 1 プロセス内の helper ではなく、workspace 単位の provider / model / credential 管理システムとして扱っています。(GitHub)
特に面白いのは load balancing です。公式 docs では、Dify は複数 credential を round-robin で回し、ある credential が rate limit に当たったら 1 分間 rotation から外します。重み付けしたければ、同じ credential を複数回 pool に入れて比率を調整できます。これは派手な cross-provider fallback ではありませんが、実サービスで頻出する「キー単位の偏り」や「tenant ごとの rate limit」にきわめて実務的です。Dify から見えるのは、AI Client 設計は認証情報の運用設計まで含めて初めて完成するということです。(Dify Docs)
横断して見えた設計パターン
ここまでを並べると、AI Client には大きく 4 つの設計パターンがあります。LangChain や LlamaIndex のような adapter / wrapper 型、GraphRAG のような protocol + factory 型、Hermes Agent や LiteLLM のような router / gateway 型、Dify のような manager / platform 型です。これらは見た目こそ違いますが、目的は共通しています。provider 差分を business logic に漏らさないことです。(LangChain Docs)
また、client 生成はもはや単なる SDK 初期化ではありません。LlamaIndex は resolve_llm() で canonical object に解決し、LangChain は provider:model や ChatOpenAI(base_url=...) で provider を抽象化し、GraphRAG は config で複数モデルを registry 的に扱い、Hermes / LiteLLM / Dify は router / manager / gateway で候補選択まで担います。どこで client を作るかより、誰が client を選び、いつ再利用し、いつ差し替えるかの方が重要になっています。(LangChain Docs)
reliability の観点では、共通点がかなり明確です。retry は小さく、fallback は大きく持つ。つまり retry は同一候補への短い再試行、fallback は model / provider / credential の切り替えです。そして fallback の前に、Hermes、OpenClaw、Dify がやっているような same-provider rotation を置くのが強い。コスト、レイテンシ、機能差、出力の安定性を考えると、いきなり provider を飛ぶより先に、同じ provider 内の別 key / 別 profile / 別 deployment を試す方が合理的です。(エルメスエージェント)
さらに本番では、state と observability が AI Client 設計の品質を左右します。OpenClaw は fallback-owned な override だけを rollback し、attempt ごとの summary を残します。LiteLLM は cooldown と routing 状態を持ち、Dify は workspace / credential 単位で provider を管理します。AI Client 設計の失敗は API 呼び出しの失敗ではなく、状態管理と運用設計の失敗として現れることが多い、というのが今回の大きな学びでした。(OpenClaw)
現時点でのベストプラクティス
私が現時点の best practice としてまとめるなら、次のようになります。
-
Adapter -> Factory/Registry -> Router/Manager -> ReliabilityPolicy -> App Logicの責務分離を行う。 provider 固有差分、client 生成、候補選択、retry/fallback を 1 クラスに詰め込まない。(GitHubのMicrosoft) -
内部表現はできるだけ標準化する。 OpenAI format でも、provider-neutral protocol でもよいが、上位層が provider ごとの分岐を知らなくてよい形に寄せる。(GitHub)
-
client lifecycle を API として明示する。 reuse するのか、都度生成するのか、sync/async をどう持つのかを設計対象に含める。LlamaIndex の
reuse_clientはこの観点でとても良い。(GitHub) -
retry と fallback を分離する。 retry は同じ候補に対する短い再試行、fallback は候補の切り替え。LiteLLM と OpenClaw はこの責務分離が分かりやすい。(LiteLLM)
-
まず same-provider rotation、その後に cross-model / cross-provider fallback を行う。 credential pool や auth profile rotation を先に置く方が、コスト・安定性・互換性の面で有利。(エルメスエージェント)
-
fallback の発火条件を error taxonomy で管理する。 rate limit、billing、auth、timeout、context overflow、content policy を同じ扱いにしない。LiteLLM の context-window / content-policy fallback、OpenClaw の明確な error 分類はその好例。(OpenClaw)
-
cooldown・stickiness・state rollback・observability を標準機能にする。 失敗候補を一定時間外し、必要なら session に stick し、失敗時は state を局所的に戻し、試行履歴を見えるようにする。ここまで含めて初めて「本番で使える client」になる。(OpenClaw)
-
マルチテナントや credential 運用まで含めて設計する。 Dify が示すように、実サービスでは model routing より credential 管理の方が先に問題になることも多い。(Dify Docs)
実装イメージ
実装イメージは、だいたい次のような形になると思います。
class ProviderAdapter:
def supports(self, request) -> bool: ...
def create_client(self, candidate): ...
def invoke(self, client, request): ...
class ClientRegistry:
def resolve_candidates(self, request): ...
def get_or_create(self, candidate): ...
class RetryPolicy:
def run(self, fn): ...
class FallbackPolicy:
def should_advance(self, error, candidate) -> bool: ...
def record_failure(self, candidate, error): ...
def cooldown(self, candidate, error): ...
class Router:
def __init__(self, registry, retry_policy, fallback_policy):
self.registry = registry
self.retry_policy = retry_policy
self.fallback_policy = fallback_policy
def call(self, request):
for candidate in self.registry.resolve_candidates(request):
client = self.registry.get_or_create(candidate)
try:
return self.retry_policy.run(
lambda: candidate.adapter.invoke(client, request)
)
except Exception as e:
if not self.fallback_policy.should_advance(e, candidate):
raise
self.fallback_policy.record_failure(candidate, e)
self.fallback_policy.cooldown(candidate, e)
raise RuntimeError("All candidates failed")
ポイントは、provider SDK を握る adapter, 候補を解決する registry / router, retry, fallback / cooldown を分離することです。この分離ができていれば、Hermes 的な credential pool も、OpenClaw 的な staged failover も、GraphRAG 的な protocol/factory も、LiteLLM 的な gateway routing も、かなり自然に取り込めます。(エルメスエージェント)
まとめ
今回いちばん強く感じたのは、AI Client はもう「SDK の薄いラッパー」ではないということです。実際の OSS では、AI Client は provider abstraction、client lifecycle、routing、credential 管理、retry / fallback / cooldown、observability、そして運用基盤までを含むシステムとして設計されていました。Hermes Agent は router と credential pool、OpenClaw は段階的 failover と state 管理、GraphRAG は protocol / factory と retry config、LangChain は unified abstraction と composed fallbacks、LlamaIndex は resolver と lifecycle control、LiteLLM は gateway/router、Dify は credential 運用基盤の観点で特に参考になります。(GitHub)
一言でまとめるなら、現時点の best practice はこうです。
AI Client は 1 つの SDK client としてではなく、adapter・factory・router・policy・manager からなるシステムとして設計する。
その上で、retry / fallback はその一部として位置づけ、同一 provider 内 rotation、error taxonomy、cooldown、observability、credential 運用まで含めて全体最適する。これが、いまの主要 OSS を横断して見えた設計原則でした。(エルメスエージェント)