Inferenzanbieter

Standardmäßig sendet dein Server Modellaufrufe an die Claude API. Diese Seite zeigt, wie du sie an einen Cloud-Anbieter oder an ein von dir betriebenes Modell-Gateway sendest. So änderst du den Anbieter:

1. Lege das Beispiel aus dem Abschnitt deines Anbieters auf dieser Seite in der Einstellungsdatei des Servers ab.
2. Gib dem Server die Anmeldedaten des Anbieters, wie es derselbe Abschnitt zeigt.
3. Starte den Server neu, wie Wo die Einstellungen stehen zeigt. Wenn Schritt 2 unter Docker Compose .env oder docker-compose.yml geändert hat, führe stattdessen docker compose up -d aus, weil ein Neustart sie nicht erneut einliest.
4. Prüfe den Anbieter.

Die Einstellung inference.provider akzeptiert diese Werte:

Bei jedem Wert außer anthropic benötigt der Server keinen Claude-API-Key. Er ignoriert ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN und ANTHROPIC_BASE_URL. Die einzige Ausnahme ist ein Modell-Gateway, dessen Key der Server laut deiner Angabe aus einer dieser Variablen lesen soll.

Agents benennen Modelle mit ihren Claude-API-IDs, etwa claude-opus-5-5. Der Server übersetzt die ID, sodass eine Agent-Definition unverändert bei jedem Anbieter funktioniert, der dieses Modell bereitstellt.

Einige Tools und Agent-Einstellungen hängen vom Anbieter ab. Siehe Unterschiede, die von deinem Inferenzanbieter abhängen.

Dem Server Cloud-Anmeldedaten geben

Wie die Anmeldedaten eines Cloud-Anbieters den Server erreichen, hängt von deiner Installation ab:

• Docker Compose: Übergib jede Variable und Datei an den Server.
• Kubernetes: Das Server-Chart übergibt keine AWS-, Google Cloud- oder Azure-Variablen, verwende also die Workload-Identität deiner Cloud. Erstelle ein Dienstkonto mit der Workload-Identity-Annotation deiner Cloud und setze server.serviceAccountName auf dessen Namen. Die values.yaml des Charts benennt die Annotation. Setze unter Azure Kubernetes Service außerdem 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

Der Server signiert seine Aufrufe mit den Anmeldedaten, die die Standard-Credential-Chain des AWS SDK auf dem Host findet. Das kann eine Task-Rolle oder eine Pod-Identität sein. Auf einer Workstation kann es AWS_PROFILE oder AWS_ACCESS_KEY_ID sein.

Aktiviere die Modelle, die du verwendest, im Konto. Die AWS-Identität, mit der der Server signiert, benötigt diese Berechtigungen:

• bedrock:InvokeModel und bedrock:InvokeModelWithResponseStream für die Modelle und Inferenzprofile, die du verwendest.
• bedrock:ListFoundationModels und bedrock:ListInferenceProfiles für die Ressource *. Der Server liest die Modelllisten von Amazon Bedrock, damit Agents ein Modell verwenden können, das neuer als das Release deines Servers ist. Um dies zu überspringen, setze inference.list_models: false.

Standardmäßig stellt der Server jeder Modell-ID us.anthropic. voran, was ein regionsübergreifendes Inferenzprofil benennt. Um eine andere Familie von Profilen zu verwenden, entferne die Auskommentierung von 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 ist erforderlich. Es ist ein Standort von Google Cloud’s Agent Platform, der die von dir verwendeten Modelle anbietet, oder global. project_id ist das Projekt, in dem die Aufrufe erfolgen und dem sie in Rechnung gestellt werden.

Der Server verwendet Google Application Default Credentials: die Datei, die GOOGLE_APPLICATION_CREDENTIALS benennt, oder das Dienstkonto, das Compute Engine, Cloud Run oder GKE anhängt. Diese Identität benötigt die Rolle roles/aiplatform.user für das Projekt. Im Projekt müssen die API aiplatform.googleapis.com und die von dir verwendeten Claude-Modelle aktiviert sein.

Microsoft Foundry

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

resource ist der Name deiner Foundry-Ressource, der erste Teil ihres Hostnamens: <resource>.services.ai.azure.com.

Die Anmeldedaten stammen aus der Umgebung des Servers:

• Ein Foundry-API-Key: Setze ANTHROPIC_FOUNDRY_API_KEY. Im Compose-Stack übergib die Variable an den Server. Unter Kubernetes lege sie im Secret cma-server-upstream ab. Mit earlierNames: true in deiner Server-Values-Datei hat das Secret einen anderen Namen. Du findest ihn unter Kubernetes: die Namen deiner Objekte.
• Microsoft Entra ID: Lass ANTHROPIC_FOUNDRY_API_KEY ungesetzt. Der Server bezieht dann ein Token für einen Service Principal, eine Workload-Identität auf Azure Kubernetes Service oder eine verwaltete Identität. Die Identität benötigt eine Azure-Rolle für die Foundry-Ressource, die Aufrufe an deren Modell-Deployments erlaubt. Setze für einen Service Principal AZURE_TENANT_ID, AZURE_CLIENT_ID und AZURE_CLIENT_SECRET.

Eine Anfrage an Foundry benennt ein Deployment, und der Server sendet die Modell-ID als Deployment-Namen. Wenn ein Deployment einen anderen Namen hat, ordne es mit model_id_overrides zu.

Eine abweichende Modell-ID zuordnen

Dein Cloud-Konto kann ein Modell unter einer anderen ID führen als der, die der Server sendet. Entferne in diesem Fall die Auskommentierung der model_id_overrides-Zeilen im Beispiel dieses Anbieters und ordne die Claude-API-ID der ID deines Kontos zu. Beide IDs müssen dasselbe Modell benennen, weil der Server jede Anfrage für das Modell aufbaut, das der Agent benennt.

Modell-Gateway

Prüfe zunächst, welche Anfragen dein Gateway akzeptiert:

• Dieselben Anfragen wie die Claude API, mit langlebigen Anmeldedaten: Behalte den Standardanbieter bei. Setze ANTHROPIC_BASE_URL auf die Adresse des Gateways und ANTHROPIC_API_KEY oder ANTHROPIC_AUTH_TOKEN auf die Anmeldedaten, die das Gateway erwartet.
• Dieselben Anfragen wie die Claude API, aber mit kurzlebigen Tokens, Anmeldedaten in einem anderen Header oder eigenen Modell-IDs: Setze inference.provider: gateway mit format: anthropic-messages.
• Das InvokeModel-Format von Amazon Bedrock: Setze inference.provider: gateway mit format: bedrock-invoke.
• Das rawPredict-Format von Claude Models on Google Cloud (Google managed): Setze inference.provider: gateway mit format: vertex-raw-predict.

Dieses Beispiel setzt inference.provider: gateway mit format: bedrock-invoke, für ein Gateway, das einen langlebigen Key akzeptiert. Lege den Key in einer Umgebungsvariablen ab und gib den Namen der Variablen an, niemals den Wert:

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 ist die Modellroute des Gateways. {model} markiert, wo die Modell-ID eingesetzt wird. Die URL muss mit https:// beginnen und auf /invoke enden.
• model_map ordnet jede Modell-ID, die ein Agent benennen kann, der ID zu, die das Gateway erwartet. Der Server lehnt ein Modell ohne Eintrag ab.
• send_as benennt den Header, der den Key überträgt. Ohne diese Angabe sendet der Server Authorization: Bearer <key>.
• Im Compose-Stack übergib die Variable an den Server.
• Unter Kubernetes kann das Server-Chart keine eigene Variable übergeben. Es übergibt aber ANTHROPIC_AUTH_TOKEN, das es aus dem Secret cma-server-upstream liest, verwende also diesen Namen:
  1. Setze env: { var: ANTHROPIC_AUTH_TOKEN }.
  2. Lege den Key des Gateways im Secret cma-server-upstream unter dem Namen ANTHROPIC_AUTH_TOKEN ab. Mit earlierNames: true in deiner Server-Values-Datei hat das Secret einen anderen Namen. Du findest ihn unter Kubernetes: die Namen deiner Objekte.

Ersetze für format: anthropic-messages den gateway-Block durch diesen:

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"

Hier ist url die vollständige URL der Messages-Route des Gateways, ohne {model}.

Ersetze für format: vertex-raw-predict den gateway-Block durch diesen:

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"

Hier ist url die rawPredict-Route des Gateways, und sie muss auf /{model}:rawPredict enden. Ein model_map-Wert darf keinen Doppelpunkt enthalten. Der credentials-Block bleibt unverändert. Der Server sendet die eigenen Anmeldedaten deines Gateways und bezieht keine Google-Anmeldedaten.

Die Konfigurationsreferenz listet die weiteren Einstellungen des Gateways auf, etwa streaming, sowie die Einstellung inference.headers.

Kurzlebige Tokens

Wenn dein Gateway kurzlebige Tokens akzeptiert, ersetze den credentials-Block durch diesen:

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"

Der Server bezieht dann jedes Token in zwei Schritten. Zuerst ruft er einen HTTP-Callback auf, den du erstellst. Der Callback gibt eine Assertion zurück, eine signierte Aussage, die üblicherweise ein JSON Web Token (JWT) ist. Dann tauscht der Server die Assertion an deinem OAuth-Token-Endpunkt gegen das Zugriffstoken ein, das er an das Gateway sendet.

• auth gibt an, wie sich der Server beim Callback authentifiziert. Das Beispiel verwendet ein Client-Zertifikat. Um ein Bearer-Token zu verwenden, das der Server aus einer Datei liest, setze auth: { type: bearer_file, token_file: /etc/callback/token }.
• exchange benennt deinen OAuth-Token-Endpunkt. Der Server sendet an diesen Endpunkt nur grant_type und die Assertion, ohne Client-ID oder Secret.
• Wenn dein Token-Endpunkt mehr benötigt, lass exchange weg. Lass deinen Callback das Zugriffstoken selbst beziehen und es im Feld assertion zurückgeben, das der Server dann an das Gateway sendet.
• Lege unter Kubernetes die Zertifikatsdateien in einem Secret ab, benenne es in server.extensionFiles.secretName des Charts und lass cert_file und key_file auf /run/cma-server/extension-files/ zeigen.

Der Server sendet dem Callback eine POST-Anfrage mit diesem Body:

{
  "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 ist der Aufrufer, der die Session erstellt hat. Für einen Single-Sign-On-Aufrufer ist issuer die issuer_url dieses Aufrufers und subject das Subject des Aufrufers. Für den Server-API-Key ist principal gleich {"issuer": "cma", "subject": "server"}. Lass den Callback Felder ignorieren, die er nicht kennt.

Der Callback antwortet mit Status 200 und diesem Body:

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

reuse gibt an, welche Sessions das Token verwenden können. Mit session, dem Standard, kann nur die Session in der Anfrage es verwenden, was zu einem Token passt, das einen einzelnen Benutzer benennt. Mit deployment teilen sich Sessions das Token, gib deployment also nur für ein Token zurück, das deine Organisation und keine Person benennt.

Wenn der Callback oder der Token-Endpunkt fehlschlägt, endet der Turn mit einem session.error-Event vom Typ model_request_failed_error, und die Session bleibt nutzbar. Der Grund steht im Server-Log in einer Zeile, die credential supplier failed enthält.

Wenn die Antwort des Token-Endpunkts kein expires_in enthält und das Token keinen exp-Claim hat, sendet der Server das Token, speichert es aber nicht. Er fordert dann bei jedem Modellaufruf ein neues Token an.

Die weiteren Einstellungen, etwa renew_before und ca_file, findest du in den Tabellen der Konfigurationsreferenz zu den Einstellungen des Modell-Gateways und den Einstellungen für kurzlebige Tokens.

Microsoft Entra ID-Tokens

Wenn dein Gateway Microsoft Entra ID-Tokens gegen seine eigene App-Registrierung prüft, ersetze den credentials-Block durch diesen:

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

scope ist der Application-ID-URI oder die Application-ID der App-Registrierung des Gateways, gefolgt von /.default. Benenne nur die eigene Registrierung des Gateways. Ein Token für eine andere Ressource würde es demjenigen, der das Gateway betreibt, ermöglichen, dort als der Server aufzutreten.

Das Token wird für die eigene Azure-Identität des Servers ausgestellt, die wie für Microsoft Entra ID unter Microsoft Foundry eingerichtet ist. Wenn die Registrierung eine App-Rolle erfordert, weise diese Rolle der Identität zu, bevor du den Server startest. Eine spätere Zuweisung wird erst wirksam, wenn der Server ein neues Token bezieht.

Das Token benennt diese Identität und keine Person, daher benötigt ein Gateway, das wissen muss, welche Person aufruft, oauth_exchange. Führe einen Turn über dein Gateway aus, unter der Identität, die deine Server verwenden werden, bevor du dich auf diese Anmeldedatenquelle verlässt.

Den Anbieter prüfen

Nachdem du die Einstellungen geändert und den Server neu gestartet hast, suche im Server-Log nach dieser Zeile. Sie besagt, dass der Server Anmeldedaten für den Anbieter gefunden hat:

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

Die Zeile beweist nicht, dass in deinem Konto ein Modell aktiviert ist. Ein fehlendes Modell zeigt sich als session.error beim ersten Turn, der es verwendet.

Ein Gateway, das du in ANTHROPIC_BASE_URL angibst, lehnt möglicherweise das Feld oder den Header für serverseitiges Fallback ab. Wenn deshalb jeder Turn fehlschlägt, setze inference.model_fallback: false in der Einstellungsdatei.