Proveedor de inferencia

De forma predeterminada, tu servidor envía las llamadas al modelo a la Claude API. Esta página muestra cómo enviarlas a un proveedor de nube o a un gateway de modelos que ejecutes tú. Para cambiar el proveedor:

1. Coloca el ejemplo de la sección de tu proveedor en esta página en el archivo de configuración del servidor.
2. Proporciona al servidor la credencial del proveedor, como muestra esa misma sección.
3. Reinicia el servidor, como muestra Dónde van los ajustes. En Docker Compose, si el paso 2 cambió .env o docker-compose.yml, ejecuta docker compose up -d en su lugar, porque un reinicio no los vuelve a leer.
4. Comprueba el proveedor.

La configuración inference.provider admite estos valores:

Con cualquier valor excepto anthropic, el servidor no necesita una clave de API de Claude. Ignora ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN y ANTHROPIC_BASE_URL. La única excepción es un gateway de modelos cuya clave le indicas al servidor que lea de una de esas variables.

Los agentes nombran los modelos por sus ID de la Claude API, como claude-opus-5-5. El servidor traduce el ID, por lo que una definición de agente funciona sin cambios con cualquier proveedor que sirva ese modelo.

Algunas herramientas y configuraciones de agentes dependen del proveedor. Consulta Diferencias que dependen de tu proveedor de inferencia.

Dar al servidor una credencial de nube

La forma en que la credencial de un proveedor de nube llega al servidor depende de tu instalación:

• Docker Compose: Pasa cada variable y archivo al servidor.
• Kubernetes: El chart del servidor no pasa variables de AWS, Google Cloud ni Azure, así que usa la identidad de carga de trabajo de tu nube. Crea una cuenta de servicio con la anotación de identidad de carga de trabajo de tu nube y establece server.serviceAccountName en su nombre. El values.yaml del chart nombra la anotación. En Azure Kubernetes Service, establece también 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

El servidor firma sus llamadas con lo que encuentre en el host la cadena de credenciales predeterminada del SDK de AWS. Puede ser un rol de tarea o una identidad de pod. En una estación de trabajo, puede ser AWS_PROFILE o AWS_ACCESS_KEY_ID.

Habilita en la cuenta los modelos que uses. La identidad de AWS con la que firma el servidor necesita estos permisos:

• bedrock:InvokeModel y bedrock:InvokeModelWithResponseStream sobre los modelos y perfiles de inferencia que uses.
• bedrock:ListFoundationModels y bedrock:ListInferenceProfiles sobre el recurso *. El servidor lee las listas de modelos de Amazon Bedrock, para que los agentes puedan usar un modelo más reciente que la versión de tu servidor. Para omitir esto, establece inference.list_models: false.

De forma predeterminada, el servidor antepone us.anthropic. a cada ID de modelo, lo que nombra un perfil de inferencia entre regiones. Para usar otra familia de perfiles, quita el comentario de 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 es obligatorio. Es una ubicación de Google Cloud’s Agent Platform que ofrece los modelos que usas, o global. project_id es el proyecto en el que se realizan y se facturan las llamadas.

El servidor usa Google Application Default Credentials: el archivo que indica GOOGLE_APPLICATION_CREDENTIALS, o la cuenta de servicio que adjunta Compute Engine, Cloud Run o GKE. Esa identidad necesita el rol roles/aiplatform.user en el proyecto. El proyecto necesita tener habilitadas la API aiplatform.googleapis.com y los modelos de Claude que uses.

Microsoft Foundry

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

resource es el nombre de tu recurso de Foundry, la primera parte de su nombre de host: <resource>.services.ai.azure.com.

La credencial proviene del entorno del servidor:

• Una clave de API de Foundry: Establece ANTHROPIC_FOUNDRY_API_KEY. En el stack de Compose, pasa la variable al servidor. En Kubernetes, colócala en el Secret cma-server-upstream. Con earlierNames: true en tu archivo de valores del servidor, el Secret tiene otro nombre. Encuéntralo en Kubernetes: los nombres de tus objetos.
• Microsoft Entra ID: Deja ANTHROPIC_FOUNDRY_API_KEY sin establecer. El servidor obtiene entonces un token para una entidad de servicio, una identidad de carga de trabajo en Azure Kubernetes Service o una identidad administrada. La identidad necesita un rol de Azure en el recurso de Foundry que permita llamadas a sus implementaciones de modelos. Para una entidad de servicio, establece AZURE_TENANT_ID, AZURE_CLIENT_ID y AZURE_CLIENT_SECRET.

Una solicitud a Foundry nombra una implementación, y el servidor envía el ID del modelo como nombre de la implementación. Si una implementación tiene otro nombre, asígnalo con model_id_overrides.

Asignar un ID de modelo diferente

Tu cuenta de nube puede tener un modelo con un ID distinto del que envía el servidor. En ese caso, quita el comentario de las líneas model_id_overrides en el ejemplo de ese proveedor y asigna el ID de la Claude API al ID de tu cuenta. Ambos ID deben nombrar el mismo modelo, porque el servidor construye cada solicitud para el modelo que nombra el agente.

Gateway de modelos

Primero comprueba qué solicitudes acepta tu gateway:

• Las mismas solicitudes que la Claude API, con una credencial de larga duración: Mantén el proveedor predeterminado. Establece ANTHROPIC_BASE_URL en la dirección del gateway y establece ANTHROPIC_API_KEY o ANTHROPIC_AUTH_TOKEN en la credencial que espera el gateway.
• Las mismas solicitudes que la Claude API, pero con tokens de corta duración, una credencial en otro encabezado o sus propios ID de modelo: Establece inference.provider: gateway con format: anthropic-messages.
• El formato InvokeModel de Amazon Bedrock: Establece inference.provider: gateway con format: bedrock-invoke.
• El formato rawPredict de Claude Models on Google Cloud (Google managed): Establece inference.provider: gateway con format: vertex-raw-predict.

Este ejemplo establece inference.provider: gateway con format: bedrock-invoke, para un gateway que acepta una clave de larga duración. Coloca la clave en una variable de entorno y nombra la variable, nunca el valor:

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 es la ruta de modelos del gateway. {model} marca dónde va el ID del modelo. La URL debe ser https:// y terminar en /invoke.
• model_map asigna cada ID de modelo que un agente puede nombrar al ID que espera el gateway. El servidor rechaza un modelo que no tiene entrada.
• send_as nombra el encabezado que lleva la clave. Sin él, el servidor envía Authorization: Bearer <key>.
• En el stack de Compose, pasa la variable al servidor.
• En Kubernetes, el chart del servidor no puede pasar una variable propia. Sí pasa ANTHROPIC_AUTH_TOKEN, que lee del Secret cma-server-upstream, así que usa ese nombre:
  1. Establece env: { var: ANTHROPIC_AUTH_TOKEN }.
  2. Coloca la clave del gateway en el Secret cma-server-upstream, con el nombre ANTHROPIC_AUTH_TOKEN. Con earlierNames: true en tu archivo de valores del servidor, el Secret tiene otro nombre. Encuéntralo en Kubernetes: los nombres de tus objetos.

Para format: anthropic-messages, reemplaza el bloque gateway por este:

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"

Aquí, url es la URL completa de la ruta de Messages del gateway, sin {model}.

Para format: vertex-raw-predict, reemplaza el bloque gateway por este:

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"

Aquí, url es la ruta rawPredict del gateway, y debe terminar en /{model}:rawPredict. Un valor de model_map no puede contener dos puntos. El bloque credentials se mantiene igual. El servidor envía la credencial propia de tu gateway y no obtiene ninguna credencial de Google.

La referencia de configuración enumera las demás configuraciones del gateway, como streaming, y la configuración inference.headers.

Tokens de corta duración

Si tu gateway acepta tokens de corta duración, reemplaza el bloque credentials por este:

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"

El servidor obtiene entonces cada token en dos pasos. Primero, llama a un callback HTTP que construyes tú. El callback devuelve una aserción, una declaración firmada que suele ser un “JSON Web Token” (token web JSON), o JWT. Luego, el servidor intercambia la aserción en tu endpoint de tokens OAuth por el token de acceso que envía al gateway.

• auth es cómo se autentica el servidor ante el callback. El ejemplo usa un certificado de cliente. Para usar un token bearer que el servidor lee de un archivo, establece auth: { type: bearer_file, token_file: /etc/callback/token }.
• exchange nombra tu endpoint de tokens OAuth. El servidor envía a ese endpoint solo grant_type y la aserción, sin ID ni secreto de cliente.
• Si tu endpoint de tokens necesita más que eso, omite exchange. Haz que tu callback obtenga el token de acceso en sí y lo devuelva en el campo assertion, que el servidor envía entonces al gateway.
• En Kubernetes, coloca los archivos de certificado en un Secret, nómbralo en server.extensionFiles.secretName del chart y apunta cert_file y key_file a /run/cma-server/extension-files/.

El servidor envía al callback una solicitud POST con este cuerpo:

{
  "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 es el llamador que creó la sesión. Para un llamador con inicio de sesión único, issuer es el issuer_url de ese llamador y subject es el sujeto del llamador. Para la clave de API del servidor, principal es {"issuer": "cma", "subject": "server"}. Haz que el callback ignore los campos que no conozca.

El callback responde con el estado 200 y este cuerpo:

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

reuse indica qué sesiones pueden usar el token. Con session, el valor predeterminado, solo puede la sesión de la solicitud, lo cual es adecuado para un token que nombra a un usuario. Con deployment, las sesiones comparten el token, así que devuelve deployment solo para un token que nombra a tu organización y a ninguna persona.

Si el callback o el endpoint de tokens fallan, el turno termina con un evento session.error de tipo model_request_failed_error, y la sesión sigue siendo utilizable. El motivo está en el registro del servidor, en una línea que contiene credential supplier failed.

Si la respuesta del endpoint de tokens no tiene expires_in y el token no tiene un claim exp, el servidor envía el token pero no lo almacena. Entonces pide otro token en cada llamada al modelo.

Para las demás configuraciones, como renew_before y ca_file, consulta las tablas de la referencia de configuración de configuraciones del gateway de modelos y configuraciones de tokens de corta duración.

Tokens de Microsoft Entra ID

Si tu gateway verifica los tokens de Microsoft Entra ID con su propio registro de aplicación, reemplaza el bloque credentials por este:

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

scope es el URI de ID de aplicación o el ID de aplicación del registro de aplicación del gateway, seguido de /.default. Nombra solo el registro propio del gateway. Un token para otro recurso permitiría a quien ejecute el gateway actuar como el servidor en ese recurso.

El token se emite a la identidad de Azure propia del servidor, configurada como para Microsoft Entra ID en Microsoft Foundry. Si el registro requiere un rol de aplicación, asigna ese rol a la identidad antes de iniciar el servidor. Una asignación posterior solo surte efecto cuando el servidor obtiene otro token.

El token nombra a esa identidad y a ninguna persona, así que un gateway que deba saber qué persona llama necesita oauth_exchange. Ejecuta un turno a través de tu gateway, con la identidad que usarán tus servidores, antes de depender de este proveedor de credenciales.

Comprobar el proveedor

Después de cambiar la configuración y reiniciar el servidor, busca esta línea en el registro del servidor. Indica que el servidor encontró una credencial para el proveedor:

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

La línea no demuestra que tu cuenta tenga un modelo habilitado. Un modelo faltante aparece como un session.error en el primer turno que lo usa.

Un gateway que nombres en ANTHROPIC_BASE_URL podría rechazar el campo o el encabezado de fallback del lado del servidor. Si todos los turnos fallan por ese motivo, establece inference.model_fallback: false en el archivo de configuración.