Claude en Microsoft Foundry

Esta guía te muestra cómo configurar y realizar llamadas a la API de Claude en Microsoft Foundry usando uno de los SDK de cliente de Anthropic o solicitudes HTTP directas. Cuando accedes a Claude en Microsoft Foundry, se te factura el uso de Claude en el Azure Marketplace. Puedes usar los modelos Claude más recientes, incluidos Claude Opus 5, Claude Opus 4.8 y Claude Sonnet 5, y funciones como la "context window" (ventana de contexto) de 1M de tokens, mientras administras los costos a través de tu suscripción de Azure.

Claude está disponible en los tipos de implementación Global Standard y US Data Zone Standard en recursos de Foundry, facturado en Claude Consumption Units a través del Azure Marketplace. Visita precios de Claude en Microsoft Foundry para obtener más detalles.



Opciones de alojamiento

Los modelos Claude en Microsoft Foundry están disponibles en dos opciones de alojamiento. Eliges la opción de alojamiento cuando configuras la implementación.



Requisitos previos

Antes de comenzar, asegúrate de tener:

• Una suscripción activa de Azure
• Acceso al portal de Foundry
• La Azure CLI instalada (requerida para el ejemplo de cURL con Entra ID, opcional en otros casos)
• Un rol de Azure RBAC que te permita usar el recurso, como Foundry User (anteriormente Azure AI User) o Cognitive Services User



Instala un SDK

Los SDK de cliente de Anthropic admiten Foundry a través de un paquete o clase de cliente específico de la plataforma. Los ejemplos de esta página también muestran solicitudes con cURL y la CLI ant. Para configurar la CLI, consulta el inicio rápido de la CLI.

pip install -U "anthropic"

# Para la autenticación con Entra ID, instala también la biblioteca Azure Identity
pip install azure-identity



Aprovisionamiento

Foundry usa una jerarquía de dos niveles: los recursos contienen tu configuración de seguridad y facturación, mientras que las implementaciones son las instancias de modelo que llamas a través de la API. Primero crearás un recurso de Foundry y luego crearás una o más implementaciones de Claude dentro de él.



Aprovisionamiento de recursos de Foundry

Crea un recurso de Foundry, que es necesario para usar y administrar servicios en Azure. Puedes seguir estas instrucciones para crear un recurso de Foundry. Alternativamente, puedes comenzar creando un proyecto de Foundry, lo que implica crear un recurso de Foundry.

Para aprovisionar tu recurso:

1. Navega al portal de Foundry.
2. Crea un nuevo recurso de Foundry o selecciona uno existente.
3. Configura la administración de acceso usando claves de API emitidas por Azure o Entra ID (anteriormente Azure Active Directory) para el control de acceso basado en roles.
4. Opcionalmente, configura el recurso para que forme parte de una red privada (Azure Virtual Network) para restringir el acceso de red a tu recurso.
5. Anota el nombre de tu recurso. Lo usarás como {resource} en los endpoints de la API (por ejemplo, https://{resource}.services.ai.azure.com/anthropic/v1/*).



Creación de implementaciones de Foundry

Después de crear tu recurso, implementa un modelo Claude para que esté disponible para llamadas a la API. Estos pasos describen el nuevo portal de Foundry (el interruptor New Foundry está activado):

1. Inicia sesión en el portal de Foundry. Desde la página de inicio del portal, selecciona Discover en la navegación superior derecha y luego Models en el panel izquierdo para abrir el catálogo de modelos.
2. Busca y selecciona un modelo Claude (por ejemplo, claude-opus-5). Cada modelo aparece una sola vez en el catálogo, independientemente de cuántas opciones de alojamiento admita.
3. En la tarjeta del modelo, selecciona Deploy y luego Custom settings para abrir el panel de configuración de la implementación. Si en su lugar eliges Default settings, la implementación se configura automáticamente como Alojado en Azure para los modelos disponibles en ambas opciones de alojamiento.
4. En tu primera implementación de Claude, revisa los términos del Azure Marketplace, selecciona una industria y selecciona Agree and Proceed para aceptar los términos y suscribirte a la oferta del Azure Marketplace.
5. Configura la implementación:
   • Deployment name: De forma predeterminada es el ID del modelo, pero puedes personalizarlo (por ejemplo, my-claude-deployment). El nombre de la implementación no se puede cambiar después de la creación.
   • Region scope: Selecciona Global o, para modelos alojados en Azure, Data Zone. Seleccionar Data Zone crea una implementación US Data Zone Standard, que mantiene la inferencia dentro de los Estados Unidos y es equivalente a establecer inference_geo: "us" en la Claude API.
   • Model version: Expande Model version settings y selecciona una versión del menú desplegable Model version. Cada opción de alojamiento aparece como una versión de modelo separada, etiquetada con su opción de alojamiento (por ejemplo, versión 1 para Alojado en Anthropic, versión 2 para Alojado en Azure).
6. Selecciona Deploy y espera a que se complete el aprovisionamiento.
7. Una vez implementado, selecciona Build en la navegación superior derecha, luego Models en el panel izquierdo y abre tu implementación. La pestaña Details muestra el Target URI (la URL de tu endpoint) y la Key (tu clave de API).

Si el interruptor New Foundry está desactivado, estás en el diseño clásico del portal. Allí, abre Model catalog en el panel izquierdo para buscar e implementar un modelo, y abre Models + endpoints (en My assets) para ver tus implementaciones y los detalles de sus endpoints.



Autenticación

Claude en Microsoft Foundry admite dos métodos de autenticación: claves de API y tokens de Entra ID. Ambos métodos usan endpoints alojados en Azure con el formato https://{resource}.services.ai.azure.com/anthropic/v1/*.



Autenticación con clave de API

Después de aprovisionar tu recurso Claude de Foundry, puedes obtener una "API key" (clave de API) desde el portal de Foundry:

1. En el portal de Foundry, selecciona Build en la navegación superior derecha y luego Models en el panel izquierdo.
2. Abre tu implementación de Claude y selecciona la pestaña Details.
3. Copia el valor de Key (y anota el Target URI de tu endpoint).
4. Usa el encabezado api-key o x-api-key en tus solicitudes, o proporciónalo al SDK.

Los SDK de Foundry requieren una clave de API y un nombre de recurso o una URL base. Los SDK de C#, Java, PHP, Python y TypeScript leen automáticamente estos valores de las siguientes variables de entorno si están definidas:

• ANTHROPIC_FOUNDRY_API_KEY - Tu clave de API
• ANTHROPIC_FOUNDRY_RESOURCE - El nombre de tu recurso (por ejemplo, example-resource)
• ANTHROPIC_FOUNDRY_BASE_URL - Alternativa al nombre del recurso: la URL base completa (por ejemplo, https://example-resource.services.ai.azure.com/anthropic/). El SDK de C# no lee esta variable: siempre construye la URL base a partir del nombre del recurso.

Ejemplo usando clave de API:

import os
from anthropic import AnthropicFoundry

client = AnthropicFoundry(
    api_key=os.environ.get("ANTHROPIC_FOUNDRY_API_KEY"),
    resource="example-resource",  # your resource name
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)



Autenticación con Microsoft Entra

La autenticación con Entra ID te permite administrar el acceso con Azure RBAC, integrarte con la administración de identidades de tu organización y evitar manejar claves de API manualmente. Para usar tokens de Entra ID:

1. Habilita la autenticación con Microsoft Entra ID para tu recurso de Foundry.
2. Obtén un token de acceso de Entra ID.
3. Usa el token en el encabezado Authorization: Bearer {TOKEN}.

Ejemplo usando Entra ID:

from anthropic import AnthropicFoundry
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# Obtener el token de Microsoft Entra ID usando el patrón de proveedor de tokens
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

# Crear el cliente con autenticación de Entra ID
client = AnthropicFoundry(
    resource="example-resource",  # your resource name
    azure_ad_token_provider=token_provider,  # Use token provider for Entra ID auth
)

# Realizar la solicitud
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)



ID de solicitud de correlación

Foundry incluye identificadores de solicitud en los encabezados de respuesta HTTP para depuración y seguimiento. Al contactar con soporte, proporciona los valores de request-id y apim-request-id (Azure API Management) para ayudar a los equipos a localizar e investigar rápidamente tu solicitud en los sistemas de Anthropic y Azure.



Compatibilidad de funciones

Claude en Microsoft Foundry admite la mayoría de las funciones de Claude. Puedes encontrar todas las funciones actualmente admitidas en Descripción general de funciones.



Ventana de contexto

Claude Fable 5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 y Claude Sonnet 4.6 tienen una ventana de contexto de 1M de tokens en Microsoft Foundry. Otros modelos Claude, incluido Claude Sonnet 4.5, tienen una ventana de contexto de 200k tokens.



Funciones de Claude no admitidas para Claude en Microsoft Foundry

• Admin API
• Herramienta Advisor
• Claude Managed Agents
• Compliance API
• Models API
• Message Batches API
• Fallback del lado del servidor (el parámetro fallbacks; usa en su lugar el patrón de fallback del lado del cliente)



Funciones adicionales no admitidas cuando se aloja en Azure

Las siguientes funciones están disponibles para implementaciones alojadas en Anthropic, pero no se admiten para implementaciones alojadas en Azure:

• Salidas estructuradas
• Herramientas del lado del servidor (búsqueda web, obtención web, ejecución de código y búsqueda de herramientas)
• Conector MCP
• Agent Skills
• Llamada programática de herramientas
• Files API

Las solicitudes que usan estas funciones contra una implementación alojada en Azure devuelven un error 400 Bad Request por diseño. Claude Code detecta las implementaciones alojadas en Azure y adapta automáticamente su conjunto de funciones.



Respuestas de la API

Las respuestas de la API de Claude en Microsoft Foundry siguen el formato de respuesta estándar de la Claude API. Esto incluye el objeto usage en los cuerpos de respuesta, que proporciona información detallada sobre el consumo de tokens de tus solicitudes. El objeto usage es consistente en todas las plataformas (Claude API, Amazon Bedrock, Claude Platform on AWS, Foundry y Google Cloud).

Para obtener detalles sobre los encabezados de respuesta específicos de Foundry, consulta ID de solicitud de correlación.



ID de modelo de la API e implementaciones

Los términos del ciclo de vida (Deprecated, Retired) se definen en Obsolescencia de modelos. Microsoft Foundry sigue el calendario del ciclo de vida de la Claude API.

Los siguientes modelos Claude están disponibles a través de Foundry:

De forma predeterminada, los nombres de implementación coinciden con los ID de modelo que se muestran en la tabla anterior. Sin embargo, puedes crear implementaciones personalizadas con nombres diferentes en el portal de Foundry para administrar distintas configuraciones, versiones o límites de velocidad. Usa el nombre de la implementación (no necesariamente el ID del modelo) en tus solicitudes a la API.



Facturación

Claude en Microsoft Foundry se factura a través del Azure Marketplace. El uso se denomina en Claude Consumption Units (CCU), se mide por hora y se factura mensualmente a posteriori en tu factura de Azure. Las CCU no son créditos prepagados. No existe un saldo ni un compromiso de CCU.

Para conocer el precio de las CCU, la mecánica de conversión y las tarifas de tokens por modelo, consulta precios de Claude en Microsoft Foundry.



Migración entre opciones de alojamiento

Para mover una implementación existente de una opción de alojamiento a la otra:

1. Crea una nueva implementación de la otra versión de alojamiento del modelo (Alojado en Azure o Alojado en Anthropic). Puede estar en el mismo recurso de Foundry o en uno nuevo.
2. Actualiza tu aplicación para pasar el nuevo nombre de implementación en el parámetro model.
3. Elimina la implementación anterior una vez que el tráfico se haya trasladado.

Si la nueva implementación está en el mismo recurso de Foundry, la URL de tu endpoint y la autenticación no cambian. Si creaste un nuevo recurso, actualiza el endpoint y las credenciales de tu aplicación para que apunten a él.



Monitoreo y registro

Azure proporciona monitoreo y registro para tu uso de Claude a través de patrones estándar de Azure:

• Azure Monitor: Realiza un seguimiento del uso de la API, la latencia y las tasas de error
• Azure Log Analytics: Consulta y analiza los registros de solicitudes/respuestas
• Cost Management: Monitorea y pronostica los costos asociados con el uso de Claude

Anthropic recomienda registrar tu actividad al menos de forma continua durante 30 días para comprender los patrones de uso e investigar cualquier posible problema.



Solución de problemas



Errores de autenticación

Error: 401 Unauthorized o Invalid API key

• Solución: Verifica que tu clave de API sea correcta. Puedes encontrarla en el portal de Foundry en la pestaña Details de tu implementación (en Build > Models).
• Solución: Si usas Microsoft Entra ID, asegúrate de que tu token de acceso sea válido y no haya expirado. Los tokens normalmente expiran después de 1 hora.

Error: 403 Forbidden

• Solución: Es posible que tu cuenta de Azure no tenga los permisos necesarios. Asegúrate de tener asignado el rol de Azure RBAC adecuado (por ejemplo, Foundry User (anteriormente Azure AI User) o Cognitive Services User).



Limitación de velocidad

Error: 429 Too Many Requests

• Solución: Has excedido tu "rate limit" (límite de velocidad). Implementa lógica de retroceso exponencial y reintentos en tu aplicación.
• Solución: Considera solicitar aumentos del límite de velocidad a través del portal de Azure o del soporte de Azure.



Encabezados de límite de velocidad

Foundry no incluye los encabezados estándar de límite de velocidad de Anthropic (anthropic-ratelimit-tokens-limit, anthropic-ratelimit-tokens-remaining, anthropic-ratelimit-tokens-reset, anthropic-ratelimit-input-tokens-limit, anthropic-ratelimit-input-tokens-remaining, anthropic-ratelimit-input-tokens-reset, anthropic-ratelimit-output-tokens-limit, anthropic-ratelimit-output-tokens-remaining y anthropic-ratelimit-output-tokens-reset) en las respuestas. En su lugar, administra la limitación de velocidad a través de las herramientas de monitoreo de Azure.



Errores de modelo e implementación

Error: Model not found o Deployment not found

• Solución: Verifica que estés usando el nombre de implementación correcto. Si no has creado una implementación personalizada, usa el ID de modelo predeterminado (por ejemplo, claude-opus-5).
• Solución: Asegúrate de que el modelo/implementación esté disponible en tu región de Azure.

Error: Invalid model parameter

• Solución: El parámetro model debe contener el nombre de tu implementación, que se puede personalizar en el portal de Foundry. Verifica que la implementación exista y esté configurada correctamente.



Próximos pasos



Recursos adicionales