Qué cambia frente a la API directa

Iván tiene el prototipo del asistente de incidencias de Tlali Logística escrito contra la API de Claude. Son unas 300 líneas: un prompt de sistema, una herramienta para consultar el estado de un envío, caché de prompts para el catálogo de políticas y un lote nocturno que reclasifica los tickets del día. Daniela le pide moverlo a Bedrock, y en paralelo el equipo de Paquetería Ágil quiere la misma versión en Google Cloud. Iván calcula que es cambiar una línea, la que crea el cliente. Está casi en lo cierto, y ese "casi" es esta lección.

Al terminar podrás:

• elegir el cliente del SDK correcto para cada plataforma;
• traducir un ID de modelo de la API al formato de Bedrock y de Google Cloud;
• distinguir endpoints globales, geográficos, multirregión y regionales;
• revisar un prototipo y marcar las funciones que no existen en tu nube;
• explicar por qué las fechas de retiro y las cuotas dependen de tu proveedor.

Lo que no cambia

La buena noticia primero. En las dos nubes, Claude se usa con la misma forma de la API de Mensajes: system, messages con roles user y assistant, bloques de contenido, max_tokens, herramientas con tool_use y tool_result, pensamiento adaptativo con el parámetro de esfuerzo, visión, PDF y caché con cache_control. La documentación de Anthropic describe la API de Google Cloud como "casi idéntica" a la de Mensajes, y la integración nueva de Bedrock usa "la misma forma de solicitud" que la API de Anthropic.

El objeto usage de la respuesta también es el mismo en todas las plataformas: input_tokens, output_tokens y los campos de caché. Si ya guardas usage para medir costos, tu código de métricas sigue funcionando.

Cambio 1: el cliente y la autenticación

El SDK de Anthropic para Python trae una clase por plataforma. Todas exponen client.messages.create(...) y client.messages.stream(...), así que el resto del código no se entera.

Revisamos los constructores en la versión 1.13.0 del SDK de Python. AnthropicBedrock acepta aws_region, aws_profile, aws_access_key, aws_secret_key, aws_session_token y api_key; si no pasas región, la toma de AWS_REGION, de AWS_DEFAULT_REGION o de tu perfil de AWS. AnthropicVertex acepta project_id y region, y si no los pasas lee ANTHROPIC_VERTEX_PROJECT_ID y CLOUD_ML_REGION.

# clientes.py
import os

from anthropic import Anthropic, AnthropicBedrock, AnthropicVertex


def crear_cliente(plataforma: str):
    """Devuelve un cliente con la misma interfaz messages.create para cualquier plataforma."""
    if plataforma == "api":
        return Anthropic()  # lee ANTHROPIC_API_KEY
    if plataforma == "bedrock":
        # Sin claves en el código: usa el rol, el perfil o las variables de AWS
        return AnthropicBedrock(aws_region=os.environ.get("AWS_REGION", "us-east-1"))
    if plataforma == "google":
        return AnthropicVertex(
            project_id=os.environ["ANTHROPIC_VERTEX_PROJECT_ID"],
            region=os.environ.get("CLOUD_ML_REGION", "global"),
        )
    raise ValueError(f"Plataforma desconocida: {plataforma}")

Por debajo, cada clase hace trabajo distinto. AnthropicBedrock firma la solicitud con SigV4 y la envía a InvokeModel en bedrock-runtime, con anthropic_version igual a bedrock-2023-05-31 en el cuerpo. AnthropicVertex saca el modelo del cuerpo, lo pone en la URL (.../publishers/anthropic/models/MODELO:rawPredict) y agrega anthropic_version igual a vertex-2023-10-16. No necesitas hacerlo a mano, pero conviene saberlo cuando leas un error o un registro de red.

Cambio 2: los IDs de modelo

Cada plataforma nombra los modelos a su manera. Esta tabla viene de la página de modelos de Anthropic y de las fichas de modelo de AWS y Google, consultadas en octubre de 2026:

En Bedrock hay un detalle que confunde a todo el mundo la primera vez. En bedrock-runtime, los modelos nuevos no se invocan con el ID base: se invocan con un perfil de inferencia que lleva un prefijo (global., us., eu., au. o jp., según el modelo). Si pasas el ID base, la documentación de Anthropic muestra el error típico: la invocación "con throughput bajo demanda no está soportada" y te pide usar un perfil de inferencia. En el endpoint bedrock-mantle, en cambio, se usa el ID con prefijo anthropic. y sin perfil. Lo verás con calma en la lección 2.1.

Dos notas más:

• En Google Cloud, los modelos anteriores a la generación 4.6 usan un sufijo con fecha, por ejemplo claude-haiku-4-5@20251001. Los actuales no lo llevan.
• En Microsoft Foundry no envías el ID del modelo sino el nombre del despliegue, que por defecto coincide con el ID de la API pero puede ser otro.

No escribas IDs dispersos por el código. Centralízalos:

# modelos.py
MODELOS = {
    # familia: {plataforma: id}
    "opus": {
        "api": "claude-opus-5-5",
        "bedrock": "global.anthropic.claude-opus-5-5",
        "bedrock_mantle": "anthropic.claude-opus-5-5",
        "google": "claude-opus-5-5",
    },
    "sonnet": {
        "api": "claude-sonnet-5-5",
        "bedrock": "global.anthropic.claude-sonnet-5-5",
        "bedrock_mantle": "anthropic.claude-sonnet-5-5",
        "google": "claude-sonnet-5-5",
    },
    "haiku": {
        "api": "claude-haiku-5-5",
        "bedrock": "global.anthropic.claude-haiku-5-5",
        "bedrock_mantle": "anthropic.claude-haiku-5-5",
        "google": "claude-haiku-5-5",
    },
}

PREFIJOS_GEO_BEDROCK = {"global", "us", "eu", "au", "jp"}


def id_modelo(familia: str, plataforma: str, geo_bedrock: str = "global") -> str:
    modelo = MODELOS[familia][plataforma]
    if plataforma == "bedrock" and geo_bedrock != "global":
        if geo_bedrock not in PREFIJOS_GEO_BEDROCK:
            raise ValueError(f"Prefijo geográfico no válido: {geo_bedrock}")
        # Cambia global. por us., eu., etc. Verifica en la ficha que el perfil exista.
        modelo = modelo.replace("global.", f"{geo_bedrock}.", 1)
    return modelo


if __name__ == "__main__":
    print(id_modelo("sonnet", "bedrock", geo_bedrock="us"))
    print(id_modelo("haiku", "google"))

Ojo con el comentario: no todos los modelos tienen todos los perfiles. Según la ficha de AWS, Claude Sonnet 5.5 tiene perfiles us., eu. y au., pero no jp.. Antes de cambiar de geografía, revisa la ficha del modelo o ejecuta aws bedrock list-inference-profiles.

Cambio 3: endpoints globales, geográficos y regionales

En la API de Claude no eliges región: es global por defecto, con opciones de residencia aparte. En la nube sí eliges, y la elección tiene consecuencias de disponibilidad, cumplimiento y precio.

• Bedrock (bedrock-runtime): el perfil global. enruta a cualquier región comercial con capacidad. Un perfil geográfico (us., eu., au., jp.) enruta solo dentro de esa geografía. Para Tlali hay un dato importante: según las fichas de AWS, desde la región de México (mx-central-1) los modelos 5.5 están disponibles solo con el perfil global. Si un requisito exige que el tráfico no salga de una geografía concreta, Tlali tendría que llamar desde una región de Estados Unidos con el perfil us..
• Google Cloud: global para máxima disponibilidad, us o eu como multirregión, o una región concreta como us-east5. La documentación de Anthropic aclara que los endpoints regionales específicos admiten Claude Sonnet 4.6 y anteriores; los modelos más nuevos se usan con el endpoint global o multirregión.

En las dos nubes, el global no tiene sobreprecio y el regional o multirregión sí. En Google Cloud, además, el throughput aprovisionado solo funciona con endpoints regionales. Elige con los requisitos de residencia en la mano, no por costumbre.

Cambio 4: funciones que no existen o tienen otro formato

Esta es la parte que más rompe prototipos. Las páginas de Bedrock y de Google Cloud en la documentación de Anthropic listan lo que no está disponible. Resumido a octubre de 2026:

Comprobamos el comportamiento del conteo en el código del SDK: el cliente de Bedrock lanza AnthropicError con el mensaje "Token counting is not supported in Bedrock yet", y el de Google Cloud redirige la llamada al endpoint count-tokens:rawPredict. Esto te permite escribir una función que degrade con elegancia:

# conteo.py
import anthropic


def contar_tokens(cliente, modelo: str, mensajes: list[dict]) -> int | None:
    """Cuenta tokens si la plataforma lo permite; si no, devuelve None."""
    try:
        resultado = cliente.messages.count_tokens(model=modelo, messages=mensajes)
        return resultado.input_tokens
    except anthropic.AnthropicError as error:
        print(f"Conteo no disponible en esta plataforma: {error}")
        return None

Para el prototipo de Iván, la revisión deja tres pendientes: el lote nocturno usa la Message Batches API (habrá que reescribirlo con el servicio de lotes de cada nube, lecciones 2.2 y 3.2), la validación con salidas estructuradas no existe en Bedrock (usará una herramienta con esquema y validación propia) y la caché automática se cambia por un punto de corte explícito.

Cambio 5: cuotas, errores y ciclo de vida

• Cuotas. Los límites los fija tu nube. En Bedrock se piden aumentos con Service Quotas o soporte de AWS; en Google Cloud, en la página de cuotas del proyecto. La forma de contar también cambia: Bedrock reserva al inicio de cada solicitud los tokens de entrada más max_tokens. Lo veremos en la lección 4.1.
• Errores. Los códigos HTTP son parecidos (429 por exceso de tasa, 400 por solicitud inválida, 403 por permisos), pero los mensajes vienen de AWS o de Google. Un 403 en Bedrock puede significar que falta la acción de IAM o que tu cuenta no tiene acceso al modelo.
• Ciclo de vida. La página de modelos de Anthropic aclara que las fechas de retiro que publica Anthropic aplican a las plataformas que opera Anthropic, y que Amazon Bedrock y Google Cloud fijan las suyas. Consulta la página de ciclo de vida de modelos de AWS y la ficha de cada modelo en Google Cloud.

Práctica

Dedica 25 minutos. No necesitas credenciales reales.

1. Instala el SDK con los extras de las dos nubes en un entorno virtual: pip install "anthropic[bedrock,vertex]". Importa AnthropicBedrock, AnthropicBedrockMantle y AnthropicVertex y confirma que existen.
2. Copia modelos.py y agrega una familia "fable" con los IDs de Claude Fable 5.1 que encuentres en la página de modelos de Anthropic.
3. Toma un script tuyo que use la API de Claude (o uno del curso API de Claude desde cero) y haz una tabla con cada función que usa. Marca las que no existen en Bedrock o en Google Cloud y escribe la alternativa.
4. Ejecuta contar_tokens con un cliente AnthropicBedrock creado con una región cualquiera. Aunque no tengas credenciales, observa que el error del SDK aparece antes de cualquier llamada de red.
5. Escribe en dos líneas qué tipo de endpoint usarías para Tlali en cada nube y por qué.

Resumen

• La forma de la API de Mensajes y el objeto usage son los mismos; cambian el cliente, la autenticación y los IDs.
• Clases del SDK: AnthropicBedrock para bedrock-runtime, AnthropicBedrockMantle para bedrock-mantle, AnthropicVertex para Google Cloud y AnthropicAWS para Claude Platform on AWS.
• En bedrock-runtime los modelos nuevos se invocan con perfiles de inferencia (global., us., eu....); en Google Cloud con el ID simple y la ubicación en el cliente.
• Lotes, Files API, varias herramientas del servidor y, en Bedrock, las salidas estructuradas no están disponibles igual que en la API; revisa cada prototipo contra la tabla.
• Cuotas, errores y fechas de retiro dependen de tu nube, no de Anthropic.

Quiz