Claude apps gatewayにmantleを足してBedrock Mantleへ流す

Claude apps gatewayのupstreamsにprovider: mantleを1件足すと、ゲートウェイはAmazon BedrockのMantleエンドポイントへ推論リクエストを流せるようになります。Mantleは、Invoke APIではなくAnthropicのネイティブAPIと同じ形でClaudeを提供するBedrock側のエンドポイントです。クライアントごとに環境変数を配る方法ではなく、ゲートウェイ側の設定でまとめて切り替えたい組織向けの手順です。

このプロバイダーはClaude Codeのv2.1.283で追加されました。ゲートウェイを動かすサーバー側のバージョンが条件で、古いレプリカは起動時にこの設定を拒否します。

mantle upstreamは何を足す設定か

ゲートウェイのupstreamsは順序つきのリストで、要求されたモデルを解決できる最初のupstreamへ転送します。これまでBedrock向けにはprovider: bedrockがあり、こちらはbedrock-runtimeエンドポイントとAWSのデフォルト認証情報チェーンを使います。mantleはその隣に並ぶ別のプロバイダーです。

両者の違いは、エンドポイントとモデルの扱いにあります。

Claude Code本体をMantleへ直結する環境変数(CLAUDE_CODE_USE_MANTLEなど)は、Claude Code Bedrock Mantleエンドポイントの使い方で扱っています。ここで足すのはゲートウェイ側のupstreamなので、開発者のマシンには何も配りません。

足す前に確かめる3つの前提

設定を書く前に、次の3点が揃っているかを見ます。

IAMについては、Mantleにbedrock-mantle:プレフィックスの独自アクションがあります。推論はbedrock-mantle:CreateInference、トークン数の計算はbedrock-mantle:CountTokensです。なおBedrock upstreamでは、bedrock:CountTokensが、クライアントが途中で切ったリクエストのトークン数を数えて支出上限を保つ処理に使われます。

gateway.yamlにmantleを足す

最小の構成は、Mantleを先頭に置き、その後ろにBedrock upstreamを置く形です。Mantleに載せたモデルだけを先に試し、それ以外のモデルを後ろのBedrockに回します。

次の例は、Mantleを先頭に置き、そのモデル一覧から漏れたモデルを後ろのBedrockが受ける構成です(設定リファレンスの例に沿った形です)。

upstreams:
  - provider: mantle
    region: us-east-1
    models: [claude-opus-4-7, claude-haiku-4-5]   # 必須
    auth: {}                           # AWSのデフォルト認証情報チェーン
  - provider: bedrock
    region: us-east-1
    auth: {}

起動は、ゲートウェイに設定ファイルを渡す1行です。

claude gateway --config gateway.yaml

ログの詳しさは環境変数CLAUDE_GATEWAY_LOG_LEVELで変えられます(debug・info・warn・error、既定はinfo)。立ち上がらないときは、まずdebugにして原因を見るのが手早い方法です。

mantle upstreamが取る4つのフィールド

mantle upstreamに固有のフィールドは4つです。

authがbedrockと同じ規則だという点は、設定を使い回せることを意味します。空のauth: {}ならAWS SDKのデフォルト認証情報チェーンを使い、環境変数・~/.aws/credentials・ECSタスクロール・EC2インスタンスメタデータ・EKSのIRSAを順に拾います。本番ではコンテナイメージに静的キーを埋めず、ゲートウェイにIAMロールを持たせる方法が推奨されています。静的キーを明示する場合は、aws_access_key_idとaws_secret_access_keyを必ず組で書きます。片方だけだとゲートウェイは起動時に落ちます。

base_urlは、VPCエンドポイントなどでURLを差し替えたいときに使います。上書きしても、末尾の/anthropicは消さないでください。

modelsはリクエストの振り分けに効く

modelsは、単なる宣言ではなく振り分けの条件として働きます。リストに並べたモデルだけがこのupstreamに届き、それ以外のモデルは次のupstreamへ飛ばされます。

先ほどの例で、クライアントがclaude-haiku-4-5を要求すればMantleへ、modelsに無いモデルならそのまま後ろのBedrockへ流れます。「Mantleに載せたいモデルだけを明示して、残りは従来のBedrockに任せる」という段階移行が、設定だけで組めます。

フェイルオーバーの規則はbedrockなどと同じです。ゲートウェイは、5xx・429・401・403・404・タイムアウトのときに次のupstreamへ移ります。それ以外の4xxはリクエスト側の問題とみなして移りません。404は「そのupstreamがモデルを扱わない」という意味なので、後ろのupstreamが扱えるなら転送が続きます。

ここで一つ、設計上の注意があります。404でのフェイルオーバーは、ゲートウェイがv2.1.198以降であることが条件です。それより前の版は、最初の404をそのままクライアントに返します。mantleを足すサーバーは2.1.283以降なので、この条件は満たしますが、レプリカの版がそろっているかは見ておくと安心です。

Mantleのモデルがゲートウェイの既知ではないとき

ゲートウェイが知らないMantleのモデルIDを使うときは、トップレベルのmodels:ブロックに項目を足します。そのupstream_modelで、このupstreamの名前をMantle側のIDに対応付けます。そして、その項目のidをmantle upstreamのmodelsにも書きます。

Mantle側のIDは、anthropic.で始まりバージョンサフィックスが付かない形です。たとえばanthropic.claude-haiku-4-5のようになります。次は、カスタムIDを一つ作ってMantleへ対応付ける例です(claude-sonnet-mantleは説明用の名前です)。

upstreams:
  - name: mantle-east
    provider: mantle
    region: us-east-1
    models: [claude-sonnet-mantle]     # 下の models: の id と同じ名前
    auth: {}
 
models:
  - id: claude-sonnet-mantle
    label: Claude Sonnet (Mantle)
    upstream_model:
      mantle-east: anthropic.claude-sonnet-5

upstream_modelのキーは、設定済みupstreamのnameと一致させます。nameを省いたときの既定はプロバイダー名です。一致しないキーがあると起動に失敗するので、使わないプロバイダーの行は消しておきます。同じプロバイダーのupstreamを複数並べるときは、name:を別々にする決まりです。

組み込みのClaudeモデルではないカスタムIDは、upstream_modelに載っていないupstreamを飛ばします。つまり上のclaude-sonnet-mantleは、mantle-eastにしか流れません。後ろにbedrockを並べていても、そちらへは落ちません。「このモデルはMantleだけで受けたい」という運用なら、この性質が使えます。

同じ設定ファイルでbedrockと併用するときの制約

mantleはbedrockの設定をそのまま引き継ぎません。次の2つは、見落とすと起動できない・意図と違う署名になる点です。

guardrailとの混在は起動を拒否される

ゲートウェイは、mantleを並べたまま、いずれかのbedrock upstreamにguardrailが設定されていると起動を拒否します。Mantleへ送るリクエストには、Bedrock guardrailを適用しないためです。mantleを足す前に、既存のbedrock upstreamにguardrailがないかを確かめてください。

assume_roleは使えない

mantle upstreamはassume_roleを取りません。Mantleが処理するリクエストは、mantle upstream自身のauthで署名されます。そのため、開発者ごとのAWSコスト帰属にもなりません。bedrockのassume_roleにsession_nameを付けると開発者ごとのセッションで署名できますが、Mantleを通った分にはその仕組みが及びません。

両方の制約の背景と、bedrock側の設定はClaude apps gatewayのBedrockでassume_roleとguardrailを設定するにまとめています。要するに、Guardrailで入力を縛る運用や、開発者単位でAWSの請求を追う運用と、Mantleの併用には条件がつきます。

起動しない・流れないときの切り分け

設定を足したあとに起きやすい症状は、次のように切り分けられます。

403の切り分けは、クライアントから直結する場合と同じです。ゲートウェイは403を次のupstreamへのフェイルオーバー対象にするので、後ろにBedrockを並べておけば、Mantleで許可が足りなかったモデルが自動でそちらに回ることがあります。ただし、その場合は気づかないうちにMantleが使われなくなる形で、見つけにくくなります。意図してMantleを使いたいモデルがあるなら、許可の状態を別途確かめておくと安心です。

全体の構成に組み込む

ゲートウェイをAWSに載せる全体の構成は、Claude apps gatewayをAWSにデプロイするでECS FargateとRDSの例を扱っています。そこで使うbedrock upstreamの隣にmantleを足すイメージです。設定ファイル全体のキーを見渡したいときは、Claude apps gatewayの設定リファレンスが入口になります。

まとめ

設定そのものは数行で済みます。手間がかかるのは、既存のbedrock upstreamにguardrailが付いていないかの確認と、assume_roleで開発者ごとに帰属させている運用をMantle経由では続けられない点の見直しです。この2つを先に片づければ、あとはmodelsの範囲を広げるだけで移行が進みます。

Mantleへ載せ替えるモデルを決め、modelsにその名前を並べ、後ろにbedrockを置いて段階的に移す。この順で組むと、既存の運用を壊さずに試せます。