Claude Platform Docs
Managed Agentsエンタープライズ設定

推論プロバイダー

セルフホストのClaude Managed Agentsサーバーからのモデル呼び出しを、Claude APIではなく、Amazon Bedrock、Claude Models on Google Cloud (Google managed)、Microsoft Foundry、またはご自身で運用するモデルゲートウェイに送信します。

デフォルトでは、サーバーはモデル呼び出しをClaude APIに送信します。このページでは、それらをクラウドプロバイダー、またはご自身で運用するモデルゲートウェイに送信する方法を説明します。プロバイダーを変更するには、次の手順に従います。

  1. このページにあるご利用のプロバイダーのセクションのサンプルを、サーバーの設定ファイルに記述します。
  2. 同じセクションに示すとおり、プロバイダーの認証情報をサーバーに渡します。
  3. 設定の配置場所に示すとおりに、サーバーを再起動します。Docker Composeでは、手順2で .env または docker-compose.yml を変更した場合、再起動ではそれらが再読み込みされないため、代わりに docker compose up -d を実行します。
  4. プロバイダーを確認します。

inference.provider 設定には次の値を指定できます。

inference.providerモデル呼び出しの送信先サーバーの認証方法
anthropic（デフォルト）Claude APIANTHROPIC_API_KEY
bedrockAmazon BedrockAWS認証情報
vertexClaude Models on Google Cloud (Google managed)Google Application Default Credentials
foundryMicrosoft FoundryFoundry APIキー、またはMicrosoft Entra ID
gatewayご自身で運用するモデルゲートウェイゲートウェイが受け付けるキーまたはトークン

anthropic 以外のすべての値では、サーバーはClaude APIキーを必要としません。ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL を無視します。唯一の例外は、これらの変数のいずれかからキーを読み取るようサーバーに指示したモデルゲートウェイです。

エージェントは、claude-opus-5-5 のようなClaude APIのIDでモデルを指定します。サーバーがIDを変換するため、エージェント定義は、そのモデルを提供するどのプロバイダーでも変更なしで動作します。

一部のツールとエージェント設定はプロバイダーに依存します。推論プロバイダーに依存する違いを参照してください。

サーバーにクラウドの認証情報を渡す

クラウドプロバイダーの認証情報がサーバーに届く方法は、インストール方法によって異なります。

  • Docker Compose： 各変数とファイルをサーバーに渡します。
  • Kubernetes： サーバーチャートはAWS、Google Cloud、Azureの変数を渡さないため、クラウドのワークロードIDを使用してください。クラウドのワークロードIDのアノテーションを持つサービスアカウントを作成し、server.serviceAccountName をその名前に設定します。そのアノテーションはチャートの values.yaml に記載されています。Azure Kubernetes Serviceでは、server.azureWorkloadIdentity: true も設定してください。

Amazon Bedrock

inference:
  provider: bedrock
  region: us-east-1
  #model_id_prefix: global.anthropic.
  #model_id_overrides:
  #  claude-opus-5-5: us.anthropic.claude-opus-5-5

サーバーは、AWS SDKのデフォルトの「credential chain」（認証情報チェーン）がホスト上で見つけたものを使って呼び出しに署名します。これはタスクロールやPod Identityの場合があります。ワークステーション上では、AWS_PROFILE や AWS_ACCESS_KEY_ID の場合があります。

使用するモデルをアカウントで有効化してください。サーバーが署名に使用するAWS IDには次の権限が必要です。

  • 使用するモデルと推論プロファイルに対する bedrock:InvokeModel および bedrock:InvokeModelWithResponseStream。
  • リソース * に対する bedrock:ListFoundationModels および bedrock:ListInferenceProfiles。サーバーはAmazon Bedrockのモデル一覧を読み取るため、エージェントはサーバーのリリースより新しいモデルを使用できます。これを省略するには、inference.list_models: false を設定します。

デフォルトでは、サーバーは各モデルIDの前に us.anthropic. を付けます。これはクロスリージョン推論プロファイルを指定するものです。別のプロファイルファミリーを使用するには、model_id_prefix のコメントを解除します。

Claude Models on Google Cloud (Google managed)

inference:
  provider: vertex
  region: us-east5
  project_id: my-project
  #model_id_overrides:
  #  claude-haiku-4-5: claude-haiku-4-5@20251001

region は必須です。使用するモデルを提供しているGoogle Cloud’s Agent Platformのロケーション、または global を指定します。project_id は、呼び出しが行われ、課金されるプロジェクトです。

サーバーはGoogle Application Default Credentialsを使用します。つまり、GOOGLE_APPLICATION_CREDENTIALS が指すファイル、またはCompute Engine、Cloud Run、GKEがアタッチするサービスアカウントです。そのIDには、プロジェクトに対する roles/aiplatform.user ロールが必要です。プロジェクトでは、aiplatform.googleapis.com APIと使用するClaudeモデルが有効化されている必要があります。

Microsoft Foundry

inference:
  provider: foundry
  foundry:
    resource: my-resource
  #model_id_overrides:
  #  claude-opus-5-5: team-a-opus

resource はFoundryリソースの名前で、そのホスト名 <resource>.services.ai.azure.com の最初の部分です。

認証情報はサーバーの環境から取得されます。

  • Foundry APIキー： ANTHROPIC_FOUNDRY_API_KEY を設定します。Composeスタックでは、変数をサーバーに渡します。Kubernetesでは、cma-server-upstream Secretに格納します。サーバーのvaluesファイルで earlierNames: true を設定している場合、Secretの名前は異なります。Kubernetes：オブジェクトの名前で確認してください。
  • Microsoft Entra ID： ANTHROPIC_FOUNDRY_API_KEY を未設定のままにします。サーバーは、サービスプリンシパル、Azure Kubernetes Service上のワークロードID、またはマネージドIDのトークンを取得します。そのIDには、Foundryリソースに対して、そのモデルデプロイメントへの呼び出しを許可するAzureロールが必要です。サービスプリンシパルの場合は、AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET を設定します。

Foundryへのリクエストはデプロイメントを指定し、サーバーはモデルIDをデプロイメント名として送信します。デプロイメントの名前が異なる場合は、model_id_overrides でマッピングしてください。

異なるモデルIDをマッピングする

クラウドアカウントでは、サーバーが送信するIDとは異なるIDでモデルが提供されている場合があります。その場合は、そのプロバイダーのサンプルにある model_id_overrides の行のコメントを解除し、Claude APIのIDをアカウントのIDにマッピングします。サーバーはエージェントが指定するモデル向けに各リクエストを構築するため、両方のIDは同じモデルを指している必要があります。

モデルゲートウェイ

まず、「model gateway」（モデルゲートウェイ）がどのリクエストを受け付けるかを確認します。

  • Claude APIと同じリクエストで、長期認証情報が1つの場合： デフォルトのプロバイダーのままにします。ANTHROPIC_BASE_URL をゲートウェイのアドレスに設定し、ANTHROPIC_API_KEY または ANTHROPIC_AUTH_TOKEN をゲートウェイが期待する認証情報に設定します。
  • Claude APIと同じリクエストで、短期トークン、別のヘッダーでの認証情報、または独自のモデルIDを使用する場合： format: anthropic-messages とともに inference.provider: gateway を設定します。
  • Amazon BedrockのInvokeModel形式： format: bedrock-invoke とともに inference.provider: gateway を設定します。
  • Claude Models on Google Cloud (Google managed) の rawPredict 形式： format: vertex-raw-predict とともに inference.provider: gateway を設定します。

このサンプルは、1つの長期キーを受け取るゲートウェイ向けに、format: bedrock-invoke とともに inference.provider: gateway を設定します。キーは環境変数に格納し、値ではなく変数名を指定してください。

inference:
  provider: gateway
  gateway:
    url: "https://llm-gateway.example.com/v1/model/{model}/invoke"
    format: bedrock-invoke
    # Quote every model_map value.
    model_map:
      claude-opus-5-5: "us.anthropic.claude-opus-5-5"
      claude-sonnet-5: "us.anthropic.claude-sonnet-5"
  credentials:
    supplier: env
    env: { var: LLM_GATEWAY_KEY }
    send_as: { header: x-api-key }
  • url はゲートウェイのモデルルートです。{model} はモデルIDが入る位置を示します。URLは https:// で始まり、/invoke で終わる必要があります。
  • model_map は、エージェントが指定できる各モデルIDを、ゲートウェイが期待するIDにマッピングします。サーバーはエントリのないモデルを拒否します。
  • send_as はキーを運ぶヘッダーの名前を指定します。指定しない場合、サーバーは Authorization: Bearer <key> を送信します。
  • Composeスタックでは、変数をサーバーに渡します。
  • Kubernetesでは、サーバーチャートは独自の変数を渡せません。ただし、cma-server-upstream Secretから読み取った ANTHROPIC_AUTH_TOKEN は渡すため、その名前を使用してください。
    1. env: { var: ANTHROPIC_AUTH_TOKEN } を設定します。
    2. ゲートウェイのキーを cma-server-upstream Secretに ANTHROPIC_AUTH_TOKEN という名前で格納します。サーバーのvaluesファイルで earlierNames: true を設定している場合、Secretの名前は異なります。Kubernetes：オブジェクトの名前で確認してください。

format: anthropic-messages の場合は、gateway ブロックを次のものに置き換えます。

inference:
  gateway:
    url: "https://llm-gateway.example.com/v1/messages"
    format: anthropic-messages
    # Quote every model_map value.
    model_map:
      claude-opus-5-5: "corp-claude-opus"
      claude-sonnet-5: "corp-claude-sonnet"

ここでの url は、ゲートウェイのMessagesルートの完全なURLで、{model} は含みません。

format: vertex-raw-predict の場合は、gateway ブロックを次のものに置き換えます。

inference:
  gateway:
    url: "https://llm-gateway.example.com/v1/projects/my-project/locations/global/publishers/anthropic/models/{model}:rawPredict"
    format: vertex-raw-predict
    # Quote every model_map value.
    model_map:
      claude-opus-5-5: "claude-opus-5-5"
      claude-sonnet-5: "claude-sonnet-5"

ここでの url はゲートウェイの rawPredict ルートで、/{model}:rawPredict で終わる必要があります。model_map の値にはコロンを含めることはできません。credentials ブロックはそのままにします。サーバーはゲートウェイ独自の認証情報を送信し、Googleの認証情報は取得しません。

設定リファレンスには、streaming などのゲートウェイのその他の設定と、inference.headers 設定が記載されています。

短期トークン

ゲートウェイが短期トークンを受け取る場合は、credentials ブロックを次のものに置き換えます。

inference:
  credentials:
    supplier: oauth_exchange
    assertion:
      url: "https://app.example.com/assertion"
      auth: { type: mtls, cert_file: /etc/callback/client.pem, key_file: /etc/callback/client.key }
    exchange:
      token_url: "https://login.example.com/oauth2/token"
      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer"

サーバーは各トークンを2つのステップで取得します。まず、ご自身で構築したHTTPコールバックを呼び出します。コールバックは「assertion」（アサーション）を返します。これは署名されたステートメントで、通常は「JSON Web Token」（JSONウェブトークン）、すなわちJWTです。次に、サーバーはOAuthトークンエンドポイントでアサーションを交換し、ゲートウェイに送信するアクセストークンを取得します。

  • auth は、サーバーがコールバックに対して認証する方法です。サンプルではクライアント証明書を使用しています。サーバーがファイルから読み取るベアラートークンを使用するには、auth: { type: bearer_file, token_file: /etc/callback/token } を設定します。
  • exchange はOAuthトークンエンドポイントを指定します。サーバーはそのエンドポイントに grant_type とアサーションのみを送信し、クライアントIDやシークレットは送信しません。
  • トークンエンドポイントがそれ以上を必要とする場合は、exchange を省略してください。コールバックがアクセストークン自体を取得し、それを assertion フィールドで返すようにします。サーバーはそれをゲートウェイに送信します。
  • Kubernetesでは、証明書ファイルをSecretに格納し、その名前をチャートの server.extensionFiles.secretName に指定して、cert_file と key_file が /run/cma-server/extension-files/ を指すようにします。

サーバーはコールバックに、次の本文を持つ POST リクエストを送信します。

{
  "version": 1,
  "purpose": "inference",
  "session": {
    "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
    "agent_id": "agent_011CYm1BLqPXpQRk5khsSXrs",
    "environment_id": "env_01595EKxaaTTGwwY3kyXdtbs"
  },
  "principal": {
    "issuer": "https://login.example.com/oauth2/default",
    "subject": "00u1a2b3c4d5e6f7g8h9"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

principal はセッションを作成した呼び出し元です。シングルサインオンの呼び出し元の場合、issuer はその呼び出し元の issuer_url、subject は呼び出し元のサブジェクトです。サーバーAPIキーの場合、principal は {"issuer": "cma", "subject": "server"} です。コールバックは、認識しないフィールドを無視するようにしてください。

コールバックはステータス 200 と次の本文で応答します。

{ "assertion": "<signed JWT>", "reuse": "session" }

reuse は、どのセッションがトークンを使用できるかを示します。デフォルトの session では、リクエスト内のセッションのみが使用でき、1人のユーザーを指すトークンに適しています。deployment ではセッション間でトークンを共有するため、組織を指し、個人を指さないトークンの場合にのみ deployment を返してください。

コールバックまたはトークンエンドポイントが失敗した場合、ターンはタイプ model_request_failed_error の session.error イベントで終了しますが、セッションは引き続き使用できます。理由はサーバーログの credential supplier failed を含む行に記録されます。

トークンエンドポイントの応答に expires_in がなく、トークンに exp クレームもない場合、サーバーはトークンを送信しますが保存はしません。その後、モデル呼び出しのたびに別のトークンを要求します。

renew_before や ca_file などのその他の設定については、設定リファレンスのモデルゲートウェイの設定と短期トークンの設定の表を参照してください。

Microsoft Entra IDトークン

ゲートウェイが独自のアプリ登録に対してMicrosoft Entra IDトークンを検証する場合は、credentials ブロックを次のものに置き換えます。

inference:
  credentials:
    supplier: azure
    azure: { scope: "api://11111111-2222-3333-4444-555555555555/.default" }

scope は、ゲートウェイのアプリ登録のアプリケーションID URIまたはアプリケーションIDに /.default を続けたものです。ゲートウェイ自身の登録のみを指定してください。別のリソース向けのトークンを指定すると、ゲートウェイを運用する者がそのリソース上でサーバーとして振る舞えるようになってしまいます。

トークンはサーバー自身のAzure IDに対して発行されます。このIDは、Microsoft FoundryのMicrosoft Entra IDと同様に設定します。登録でアプリロールが必要な場合は、サーバーを起動する前にそのロールをIDに割り当ててください。後から割り当てた場合、サーバーが別のトークンを取得したときにのみ有効になります。

トークンはそのIDを指し、個人は指さないため、どの個人が呼び出しているかを知る必要があるゲートウェイには oauth_exchange が必要です。このサプライヤーに依存する前に、サーバーが使用するIDで、ご自身のゲートウェイを通して1ターン実行してください。

プロバイダーを確認する

設定を変更してサーバーを再起動した後、サーバーログで次の行を探してください。これは、サーバーがプロバイダーの認証情報を見つけたことを示しています。

level=INFO msg="upstream credential resolved" provider=bedrock

この行は、アカウントでモデルが有効化されていることを証明するものではありません。モデルが欠けている場合は、そのモデルを使用する最初のターンで session.error として表示されます。

ANTHROPIC_BASE_URL で指定したゲートウェイは、サーバー側フォールバックのフィールドまたはヘッダーを拒否する場合があります。その理由ですべてのターンが失敗する場合は、設定ファイルで inference.model_fallback: false を設定してください。

このページは役に立ちましたか？