--- title: Proveedor de inferencia url: https://platform.claude.com/docs/es/managed-agents/self-hosted/inference-provider description: Envía las llamadas al modelo desde tu servidor autoalojado de Claude Managed Agents a Amazon Bedrock, Claude Models on Google Cloud (Google managed), Microsoft Foundry o un gateway de modelos que ejecutes tú, en lugar de a la Claude API. --- Para solicitar acceso a Claude Managed Agents autoalojado, ponte en contacto con el equipo de tu cuenta de Anthropic. 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/configuration-reference#where-settings-go) 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/configuration-reference#where-settings-go). 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/inference-provider#check-the-provider). La configuración `inference.provider` admite estos valores: | `inference.provider` | Las llamadas al modelo van a | El servidor se autentica con | | ---------------------------- | ---------------------------------------------- | ------------------------------------------------- | | `anthropic` (predeterminado) | La Claude API | `ANTHROPIC_API_KEY` | | `bedrock` | Amazon Bedrock | Tu credencial de AWS | | `vertex` | Claude Models on Google Cloud (Google managed) | Google Application Default Credentials | | `foundry` | Microsoft Foundry | Una clave de API de Foundry, o Microsoft Entra ID | | `gateway` | Un gateway de modelos que ejecutas tú | Una clave o token que acepte tu gateway | 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/inference-provider#model-gateway) 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/differences#differences-that-depend-on-your-inference-provider). ## 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack). * **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 ```yaml 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) ```yaml 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 ```yaml 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: `.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](https://platform.claude.com/docs/es/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack). 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/upgrade#object-names). * **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`](https://platform.claude.com/docs/es/managed-agents/self-hosted/inference-provider#map-a-model-id-that-differs). ## 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: ```yaml 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 `. * En el stack de Compose, [pasa la variable](https://platform.claude.com/docs/es/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack) 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/upgrade#object-names). Para `format: anthropic-messages`, reemplaza el bloque `gateway` por este: ```yaml 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: ```yaml 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/configuration-reference#model-gateway) 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: ```yaml 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: ```json { "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](https://platform.claude.com/docs/es/managed-agents/self-hosted/configure#single-sign-on), `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: ```json { "assertion": "", "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](https://platform.claude.com/docs/es/managed-agents/self-hosted/configuration-reference#model-gateway) y [configuraciones de tokens de corta duración](https://platform.claude.com/docs/es/managed-agents/self-hosted/configuration-reference#short-lived-gateway-tokens). ### 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: ```yaml 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](https://platform.claude.com/docs/es/managed-agents/self-hosted/inference-provider#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: ```text wrap 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](https://platform.claude.com/docs/es/build-with-claude/refusals-and-fallback#server-side-fallback). Si todos los turnos fallan por ese motivo, establece `inference.model_fallback: false` en el [archivo de configuración](https://platform.claude.com/docs/es/managed-agents/self-hosted/configuration-reference#where-settings-go).