Un proxy transporta el tráfico. Un gateway lo entiende.

Módulo 3 · Arquitectura de despliegue · Lección 4 de 5

Al terminar esta lección podrás explicar cuándo un cliente necesita un gateway LLM sobre un proxy, configurarlo para cualquier ruta de despliegue y mostrar cómo los headers de sesión convierten los logs del gateway en chargeback (imputación de costos) por equipo.

Proxy frente a gateway

La distinción que importa a los clientes empresariales

Los clientes empresariales con varios equipos de desarrollo que hacen llamadas al modelo acabarán preguntando: ¿quién gasta qué? Un proxy no puede responder esa pregunta. Un gateway sí.

	Proxy	Gateway LLM
Idea central	Reenvía el tráfico	Entiende el tráfico del modelo
Qué hace	Enruta solicitudes desde dentro de la red hacia un endpoint externo. Aplica reglas de firewall, inspección TLS y controles de salida.	Analiza la solicitud, aplica la política de autenticación, atribuye el costo a un equipo, impone límites de tasa, registra la interacción y enruta al proveedor correcto.
Qué ve	Paquetes, sin entender lo que contienen	Equipos, presupuestos y proveedores

El proxy saca el tráfico del edificio. El gateway gobierna lo que pasa con él.

Qué aporta un gateway

Cinco capacidades que un proxy no puede replicar

Un proxy no tiene concepto de equipo, presupuesto ni proveedor. Un gateway tiene los tres. Estas son las cinco cosas que los clientes con más de un equipo acabarán pidiendo:

1. Autenticación centralizada. Las credenciales del proveedor viven en un solo lugar que controla el equipo de plataforma. Los desarrolladores tienen tokens de gateway de corta duración. La rotación de credenciales ocurre una vez, de forma central, y no en cada máquina de desarrollador.
2. Atribución de costos por equipo. Los headers de sesión asocian cada solicitud a un token de equipo. El gateway responde quién gastó qué sin analizar los cuerpos de las solicitudes ni estimar a partir de las facturas de nube.
3. Aplicación de presupuestos. Límites de tasa y topes de gasto por equipo, aplicados en el límite de la solicitud, antes de que se haga la llamada al modelo. Es una función de aplicación, no de reporte.
4. Enrutamiento de modelos. Cambiar de proveedor o de versión del modelo detrás de un endpoint estable. Un cliente que ejecuta Bedrock y Vertex en paralelo los presenta a través de una sola base URL. No hace falta modificar ninguna máquina de desarrollador al cambiar de proveedor.
5. Registro de auditoría de cumplimiento. Cada interacción con el modelo queda registrada en el stack propio del cliente. En las rutas de nube, donde la telemetría OTel hacia Anthropic viene desactivada por defecto, como se indicó en la lección 3.2, el log de auditoría del gateway es de donde sale la observabilidad.

Configuración

Una base URL, un token y una bandera de omisión

Para desarrolladores y arquitectos: esta sección es para ti. El patrón es idéntico en todas las rutas de despliegue; solo cambian los nombres de las variables.

# Gateway que expone el formato de la API de Anthropic
export ANTHROPIC_BASE_URL=https://llm-gateway.client.com
export ANTHROPIC_AUTH_TOKEN=team-token-from-gateway
# Bedrock detrás del gateway
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.client.com/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
# Vertex detrás del gateway
export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.client.com/vertex
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1

Las banderas de omisión de autenticación son el beneficio de la autenticación centralizada, traducido a configuración: Claude Code deja de firmar las solicitudes por sí mismo, porque el gateway inyecta las credenciales del proveedor del lado del servidor. Para tokens rotativos por usuario, configura apiKeyHelper en los ajustes para que ejecute un script que obtenga el token desde la bóveda del cliente.

Un requisito para los criterios de aceptación del equipo del gateway: el gateway debe reenviar intactos los headers anthropic-beta y anthropic-version. Un gateway que los elimine en silencio degrada las funciones de Claude Code, y esa falla parece un bug del producto hasta que alguien inspecciona el tráfico.

sequenceDiagram
    participant CC as Claude Code
    participant GW as Gateway LLM
    participant PV as "Proveedor (API, Bedrock o Vertex)"
    CC->>GW: Solicitud con token de equipo y headers de sesión
    GW->>GW: Autenticación, presupuesto y registro de auditoría
    GW->>PV: Solicitud con credenciales inyectadas en el servidor
    PV-->>GW: Respuesta
    GW-->>CC: Respuesta

Headers de sesión

Cómo Claude Code etiqueta su propio tráfico

Cada solicitud de Claude Code lleva headers de atribución que el gateway puede leer sin analizar el cuerpo de la solicitud. Estos tres headers son la base del chargeback por equipo.

Nivel	Header	Qué hace
Sesión	X-Claude-Code-Session-Id	Identificador único de la sesión actual de Claude Code. El gateway agrupa todas las solicitudes de la sesión bajo este ID. Esto da reportes de costo y duración a nivel de sesión sin tocar los cuerpos de las solicitudes.
Subagente	X-Claude-Code-Agent-Id	Presente en las solicitudes de los subagentes. Cuando Claude Code se divide en subagentes paralelos, cada uno lleva su propio ID de agente, para que el gateway atribuya el costo a cada hilo de agente dentro de la sesión.
Relación padre	X-Claude-Code-Parent-Agent-Id	Vincula un subagente con su padre. Permite la atribución completa de agentes anidados: una sesión que lanza cinco subagentes se consolida correctamente en un único reporte de costos de equipo en la revisión del CoE.

flowchart TD
    S["Sesión (X-Claude-Code-Session-Id)"] --> AP["Agente padre"]
    AP --> SA1["Subagente (X-Claude-Code-Agent-Id)"]
    AP --> SA2["Subagente (X-Claude-Code-Agent-Id)"]
    SA1 -->|"X-Claude-Code-Parent-Agent-Id"| AP
    SA2 -->|"X-Claude-Code-Parent-Agent-Id"| AP
    S --> T["Equipo (token del gateway)"]

Qué habilita esto

Chargeback por equipo. Asocia los tokens del gateway a equipos y los tres headers te dan costo por equipo por semana, sesiones por desarrollador y alertas de presupuesto antes de la siguiente factura. La revisión de métricas del CoE y la conversación con el CFO se sirven con el mismo canal de datos.

Para líderes no técnicos: estos headers son los que habilitan el reporte de costos por equipo en la presentación del Día 30. No los configuras tú: Claude Code los envía automáticamente y el gateway los lee.

Implementación de referencia

LiteLLM como punto de partida

La documentación de gateways de Anthropic usa LiteLLM como implementación de referencia. No es la única opción, pero tiene los patrones de configuración más probados para despliegues de Claude Code.

Los proxies LiteLLM soportan tanto el formato Anthropic Messages como el paso directo en formato compatible con OpenAI. Para los clientes que ya usan herramientas en formato OpenAI, esto significa que un solo gateway puede atender ambos flujos sin una capa de integración separada. Los overrides de base URL y las banderas de omisión de autenticación de la sección «Una base URL, un token y una bandera de omisión» funcionan igual, ya sea que la ruta sea la API de Anthropic, Bedrock o Vertex. Los detalles de configuración y las versiones probadas vigentes están en la documentación del gateway LLM de Anthropic, en code.claude.com/docs/en/llm-gateway.

Aviso de seguridad

Las versiones 1.82.7 y 1.82.8 de LiteLLM publicadas en PyPI fueron comprometidas con malware que roba credenciales. No instales esas versiones. Antes de cualquier despliegue en cliente que use LiteLLM, verifica la versión segura vigente en la documentación del gateway LLM de Anthropic. Esto es un riesgo de cadena de suministro, no una limitación del producto.

Principio de posicionamiento

Todo cliente empresarial con más de un equipo acabará preguntando quién gasta qué. Recomienda un gateway antes de que lo pregunten, no después de que la primera factura sorprenda a alguien.

Artefacto del curso · Deployment Decision Doc

Sección: recomendación y configuración del gateway.

Agrega la sección de gateway a tu Deployment Decision Document. Esta sección registra si el proyecto necesita un gateway y las decisiones de configuración clave que el equipo de plataforma debe ejecutar.

1. Indica si el cliente requiere un gateway. Usa como criterio de decisión el principio de posicionamiento de esta lección: más de un equipo, un requisito de chargeback o una necesidad de enrutamiento multinube.
2. Si la respuesta es sí, registra qué ruta de despliegue va a fronterizar el gateway (API de Anthropic, Bedrock, Vertex o una combinación) y confirma qué banderas de omisión de autenticación aplican a cada ruta.
3. Anota el criterio de aceptación del gateway para la entrega al equipo de plataforma: el gateway debe reenviar intactos los headers anthropic-beta y anthropic-version. Márcalo como requisito de go/no-go del piloto.
4. Si recomiendas LiteLLM, confirma la versión instalada contra la documentación del gateway LLM de Anthropic antes de registrarla en el documento.

Ideas clave

• Un proxy saca el tráfico del edificio; un gateway LLM entiende el tráfico del modelo y lo gobierna: autenticación central, presupuestos por equipo, enrutamiento y auditoría.
• La configuración es la misma en todas las rutas; solo cambian los nombres de las variables. Las banderas de omisión hacen que el gateway inyecte las credenciales del proveedor del lado del servidor.
• El gateway debe reenviar intactos los headers anthropic-beta y anthropic-version; si los elimina, Claude Code degrada sus funciones sin avisar.
• Los headers X-Claude-Code-Session-Id, X-Claude-Code-Agent-Id y X-Claude-Code-Parent-Agent-Id permiten el chargeback por equipo sin analizar los cuerpos de las solicitudes.
• Recomienda un gateway antes de que el cliente pregunte quién gasta qué, y confirma la versión de LiteLLM antes de instalarla.

Siguiente: Residencia de datos y ZDR