214 214
215### `upstreams`215### `upstreams`
216 216
217`upstreams` es una lista ordenada. El gateway reenvía la inferencia al primer upstream que resuelve el modelo solicitado.217`upstreams` es una lista ordenada. El gateway reenvía la inferencia al primer upstream que resuelve el modelo solicitado, omitiendo cualquier upstream cuya [lista `groups`](#send-each-team-to-its-own-upstream) excluya al desarrollador.
218 218
219Ante `5xx`, `429`, `401`, `403`, `404` o un tiempo de espera agotado, el gateway conmuta por error al siguiente upstream; ante otros `4xx` no lo hace, porque esos errores son atribuibles a la solicitud y no al upstream. Un `401` o `403` significa que el upstream rechazó la credencial que usó el gateway, o le denegó el acceso, por ejemplo al modelo solicitado. Un `404` significa que ese upstream no sirve el modelo solicitado, por lo que un upstream posterior de la lista todavía puede hacerlo.219Ante `5xx`, `429`, `401`, `403`, `404` o un tiempo de espera agotado, el gateway conmuta por error al siguiente upstream; ante otros `4xx` no lo hace, porque esos errores son atribuibles a la solicitud y no al upstream. Un `401` o `403` significa que el upstream rechazó la credencial que usó el gateway, o le denegó el acceso, por ejemplo al modelo solicitado. Un `404` significa que ese upstream no sirve el modelo solicitado, por lo que un upstream posterior de la lista todavía puede hacerlo.
220 220
231El gateway devuelve la respuesta de error de un upstream, o su propio `502`, según cómo respondieron los upstreams:231El gateway devuelve la respuesta de error de un upstream, o su propio `502`, según cómo respondieron los upstreams:
232 232
233* **Un upstream devolvió un estado ante el que el gateway no [conmuta por error](#multiple-upstreams)**: la respuesta de ese upstream. El gateway no intenta más upstreams.233* **Un upstream devolvió un estado ante el que el gateway no [conmuta por error](#multiple-upstreams)**: la respuesta de ese upstream. El gateway no intenta más upstreams.
234* **Cada upstream que el gateway intentó falló de una manera ante la que [conmuta por error](#multiple-upstreams)**: el último `429`. Cuando ninguno devolvió un `429`, el gateway prefiere, en orden, el último `401` o `403`, el último `404` y el último `501`. Cuando ninguno devolvió ninguno de esos, el propio `502` del gateway, `all upstreams failed (N attempted)`, donde N cuenta cada entrada de [`upstreams`](#upstreams), incluidas las entradas que el gateway omitió porque no sirven el modelo solicitado.234* **Todos los upstreams que probó el gateway fallaron de una forma ante la que [conmuta](#multiple-upstreams)**: el último `429`. Cuando ninguno devolvió un `429`, el gateway prefiere, en este orden, el último `401` o `403`, el último `404` y el último `501`. Cuando ninguno devolvió ninguno de esos, el propio `502` del gateway, `all upstreams failed (N attempted)`. N cuenta tus entradas de [`upstreams`](#upstreams), incluidas las omitidas, menos las cuya lista [`groups`](#send-each-team-to-its-own-upstream) excluya al desarrollador.
235 235
236Cuando el gateway devuelve la respuesta de un upstream, conserva el código de estado del upstream. Que conserve el mensaje del upstream depende del proveedor. El cuerpo de error de un upstream de la API de Anthropic llega al desarrollador sin cambios.236Cuando el gateway devuelve la respuesta de un upstream, conserva el código de estado del upstream. Que conserve el mensaje del upstream depende del proveedor. El cuerpo de error de un upstream de la API de Anthropic llega al desarrollador sin cambios.
237 237
289 base_url: https://upstream-gateway.internal.example.com289 base_url: https://upstream-gateway.internal.example.com
290 auth:290 auth:
291 api_key: ${PROXY_KEY}291 api_key: ${PROXY_KEY}
292 forward_user_identity: true # por defecto false292 forward_user_identity: true # default false
293```293```
294 294
295El gateway añade estos encabezados a cada solicitud que reenvía a ese upstream.295El gateway añade estos encabezados a cada solicitud que reenvía a ese upstream.
320upstreams:320upstreams:
321 - provider: bedrock321 - provider: bedrock
322 region: us-east-1322 region: us-east-1
323 auth: {} # preferido: cadena de credenciales por defecto de AWS323 auth: {} # preferred: AWS default credential chain
324 # O credenciales explícitas:324 # OR explicit credentials:
325 # auth:325 # auth:
326 # aws_access_key_id: ${AWS_AKID}326 # aws_access_key_id: ${AWS_AKID}
327 # aws_secret_access_key: ${AWS_SK}327 # aws_secret_access_key: ${AWS_SK}
328 # aws_session_token: ${AWS_ST}328 # aws_session_token: ${AWS_ST}
329 # O un token bearer de la API de Bedrock:329 # OR a Bedrock API bearer token:
330 # auth:330 # auth:
331 # aws_bearer_token: ${AWS_BEARER_TOKEN}331 # aws_bearer_token: ${AWS_BEARER_TOKEN}
332 # Sobrescribe el endpoint de bedrock-runtime para despliegues FIPS o con endpoint de VPC:332 # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
333 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com333 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
334```334```
335 335
356 region: us-east-1356 region: us-east-1
357 auth: {}357 auth: {}
358 guardrail:358 guardrail:
359 id: gr-abc123 # ID de la barrera de protección o ARN completo359 id: gr-abc123 # guardrail ID or full ARN
360 version: "1" # un número de versión publicada, o DRAFT360 version: "1" # a published version number, or DRAFT
361 # conserva las comillas: un 1 sin comillas falla al arrancar361 # keep the quotes: a bare 1 fails at boot
362```362```
363 363
364> [!WARNING]
365>
366> El gateway no admite etiquetas de entrada de barreras de protección. No añade etiquetas de contenido de protección a los prompts, por lo que un filtro de barrera de protección que Amazon Bedrock aplica solo a la entrada etiquetada no se ejecuta sobre el tráfico que pasa por el gateway. Para saber qué filtros dependen de las etiquetas de entrada, consulta [input tags](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) en la documentación de Amazon Bedrock.
367
368Otorga también `bedrock:ApplyGuardrail` sobre la barrera de protección al principal que firma las solicitudes de este upstream: el principal de AWS del gateway o, con [`assume_role`](#bedrock-in-another-aws-account), el rol nombrado en `role_arn`.364Otorga también `bedrock:ApplyGuardrail` sobre la barrera de protección al principal que firma las solicitudes de este upstream: el principal de AWS del gateway o, con [`assume_role`](#bedrock-in-another-aws-account), el rol nombrado en `role_arn`.
369 365
370Establece `guardrail` en todos los upstreams `bedrock` o en ninguno. El gateway se niega a iniciar con una mezcla, porque de lo contrario la [conmutación por error](#multiple-upstreams) podría enviar una solicitud a un upstream de Bedrock sin barrera de protección.366Establece `guardrail` en todos los upstreams `bedrock` o en ninguno. El gateway se niega a iniciar con una mezcla, porque de lo contrario la [conmutación por error](#multiple-upstreams) podría enviar una solicitud a un upstream de Bedrock sin barrera de protección.
373 369
374Cuando una solicitud `/v1/messages` cuyo cuerpo lleva un campo `amazon-bedrock-*`, como `amazon-bedrock-guardrailConfig`, llega a un upstream de Bedrock que tiene `guardrail` establecido, el gateway responde 400 en lugar de reenviarla.370Cuando una solicitud `/v1/messages` cuyo cuerpo lleva un campo `amazon-bedrock-*`, como `amazon-bedrock-guardrailConfig`, llega a un upstream de Bedrock que tiene `guardrail` establecido, el gateway responde 400 en lugar de reenviarla.
375 371
372> [!WARNING]
373>
374> De forma predeterminada, el gateway no agrega etiquetas de entrada a los prompts, por lo que un filtro de guardrail que Amazon Bedrock aplica solo a la entrada etiquetada no se ejecuta sobre el tráfico que pasa por el gateway. Para agregar las etiquetas, establece [`input_tagging`](#add-guardrail-input-tags). Para saber qué filtros dependen de las etiquetas de entrada, consulta [etiquetas de entrada](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) en la documentación de Amazon Bedrock.
375
376##### Agregar etiquetas de entrada de guardrail
377
378Para que el gateway agregue las etiquetas de entrada que necesita el [filtro de ataques de prompt](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-prompt-attack.html) de una guardrail de Amazon Bedrock, establece `input_tagging` en el bloque `guardrail` y reinicia el gateway. Establece el mismo valor en todos los upstreams `bedrock`, o el gateway se niega a iniciarse. Requiere Claude Code v2.1.316 o posterior en el servidor del gateway. Un gateway en una versión que no tiene la clave termina al inicio con `Unrecognized key(s) in object: 'input_tagging'`.
379
380> [!WARNING]
381>
382> Según la [documentación de Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html), todos los filtros de la guardrail dejan de evaluar el contenido sin etiquetar en cuanto una solicitud incluye etiquetas de entrada. Prueba `input_tagging` en un gateway de prueba antes de establecerlo en uno que usen los desarrolladores.
383
384`input_tagging` admite uno de estos valores:
385
386| `input_tagging` | Dónde etiqueta el gateway el texto | Después de que la guardrail bloquea un prompt |
387| :- | :- | :- |
388| `last_message` | Los mensajes `user` desde la última respuesta de Claude | En Claude Code, el siguiente prompt puede pasar, y Claude recibe entonces el prompt bloqueado como parte de la conversación |
389| `user_messages` | Mensajes `user` | Los prompts posteriores de la sesión también pueden bloquearse, hasta que el desarrollador elimine el prompt bloqueado |
390| `all_messages` | Mensajes `user` y `assistant` | Igual que `user_messages` |
391| `all_messages_and_system` | El prompt del sistema y todos los mensajes, incluidos los [mensajes del sistema a mitad de la conversación](https://code.claude.com/docs/es/llm-gateway-protocol.md#feature-pass-through) | Igual que `user_messages` |
392
393Con `last_message`, si los mensajes `user` desde la última respuesta de Claude no contienen texto que etiquetar, el gateway etiqueta en su lugar los mensajes del sistema a mitad de la conversación desde esa respuesta. Una llamada a herramienta cuenta como respuesta.
394
395La recomendación de Amazon Bedrock para el filtro de ataques de prompt es [etiquetar la entrada del usuario de forma que el prompt del sistema quede excluido](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-prompt-attack.html). Si estableces `all_messages_and_system`, un filtro que marque el propio prompt del sistema de Claude Code puede bloquear solicitudes.
396
397El ejemplo siguiente etiqueta el texto de cada mensaje `user`:
398
399```yaml theme={null}
400upstreams:
401 - provider: bedrock
402 region: us-east-1
403 auth: {}
404 guardrail:
405 id: gr-abc123
406 version: "1"
407 input_tagging: user_messages
408```
409
410Los mensajes `user` también pueden contener texto que agrega Claude Code, como los [recordatorios del sistema](https://code.claude.com/docs/es/glossary.md#system-reminder), así que comprueba en el gateway de prueba que las solicitudes habituales no se bloqueen.
411
412En las pruebas de Anthropic, una sesión etiquetada mantuvo sus lecturas de la [caché de prompts](https://code.claude.com/docs/es/prompt-caching.md) de un prompt al siguiente, y las etiquetas no agregaron tokens de entrada.
413
414##### Lo que no cubren las etiquetas de entrada
415
416Ningún valor de `input_tagging` detiene a un desarrollador que coloca deliberadamente texto donde no va ninguna etiqueta. No cuentes con que la guardrail evalúe estas partes de una solicitud:
417
418* **Contenido que el gateway no etiqueta**: los mensajes que tu valor de `input_tagging` deja fuera, las definiciones de herramientas, las entradas de las llamadas a herramientas, las imágenes y los PDF, entre otros. A menos que establezcas `all_messages_and_system`, el prompt del sistema también queda sin etiquetar.
419* **Resultados de herramientas**: contienen lo que devuelven las herramientas de Claude, como el contenido de archivos y páginas web. En las pruebas de Anthropic, un filtro de palabras no los evaluó, con etiquetas o sin ellas.
420
421Si tu cuenta u organización de AWS impone una guardrail, consulta la [documentación de Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-enforcements.html) para saber cómo trata esa guardrail las etiquetas de entrada.
422
423##### Registrar qué filtro de la barrera de protección se activó
424
425Para averiguar qué filtro de la barrera de protección de Amazon Bedrock bloqueó la solicitud de un desarrollador, establece `guardrail_trace: true` en el upstream de Bedrock, reinicia el gateway y pide al desarrollador que vuelva a enviar la solicitud. Luego busca el evento `guardrail.trace` de la solicitud en el [registro de auditoría](https://code.claude.com/docs/es/claude-apps-gateway-deploy.md#logs). Requiere Claude Code v2.1.314 o posterior en el servidor del gateway. Un gateway anterior se niega a iniciar cuando encuentra `guardrail_trace`.
426
427```yaml theme={null}
428upstreams:
429 - provider: bedrock
430 region: us-east-1
431 auth: {}
432 guardrail:
433 id: gr-abc123
434 version: "1"
435 guardrail_trace: true # default false; beside guardrail, not inside it
436```
437
438El gateway escribe un evento `guardrail.trace`, sin el texto coincidente, cuando se activó un filtro o la acción de la barrera de protección es `INTERVENED`. Busca los eventos del desarrollador por `email` o `sub`. Una solicitud en streaming puede producir varios eventos, y uno de ellos puede tener una lista `filters` vacía, así que lee todos los eventos que tengan el mismo `request_id`:
439
440| Campo | Qué contiene |
441| - | - |
442| `request_id` | El ID de la solicitud |
443| `sub`, `email` | El ID de usuario y el correo electrónico del desarrollador |
444| `upstream` | El upstream del que provino la respuesta |
445| `action` | La acción de la barrera de protección, como `INTERVENED` |
446| `filters` | Los filtros que se activaron. La lista está vacía cuando AWS no envía detalles de los filtros |
447| `filters[].side` | `input` u `output` |
448| `filters[].guardrail` | El ID de la barrera de protección |
449| `filters[].policy` | La política y la lista de Bedrock, como `contentPolicy.filters` o `sensitiveInformationPolicy.piiEntities` |
450| Otros campos de `filters[]` | Una entrada también puede llevar campos como `action`, `name`, `type`, `confidence`, `filterStrength`, `score` y `threshold` |
451
452El evento omite el texto que coincidió con un filtro, incluido el campo `match` de la traza de Bedrock. Los desarrolladores no reciben los datos de traza de Bedrock, porque el gateway los elimina de cada respuesta, sea en streaming o no.
453
454Si un cliente envía un campo `amazon-bedrock-*` en el cuerpo de una solicitud `/v1/messages`, el gateway responde 400 en un upstream que establece `guardrail_trace`.
455
376##### Bedrock en otra cuenta de AWS456##### Bedrock en otra cuenta de AWS
377 457
378Establece `assume_role` en un upstream de Bedrock y el gateway usará su propia identidad de AWS solo para llamar a `sts:AssumeRole` sobre un rol que nombres, que puede estar en una cuenta de AWS distinta de la del gateway. Cada solicitud de Bedrock de ese upstream se firma con las credenciales de una hora que devuelve STS, por lo que ninguna clave de acceso de larga duración cruza entre cuentas.458Establece `assume_role` en un upstream de Bedrock y el gateway usará su propia identidad de AWS solo para llamar a `sts:AssumeRole` sobre un rol que nombres, que puede estar en una cuenta de AWS distinta de la del gateway. Cada solicitud de Bedrock de ese upstream se firma con las credenciales de una hora que devuelve STS, por lo que ninguna clave de acceso de larga duración cruza entre cuentas.
384 - name: bedrock-isolated464 - name: bedrock-isolated
385 provider: bedrock465 provider: bedrock
386 region: us-east-1466 region: us-east-1
387 auth: {} # el rol propio del gateway: solo llama a STS467 auth: {} # the gateway's own role: it only calls STS
388 assume_role:468 assume_role:
389 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock469 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
390 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # cuando la política de confianza del rol lo requiere470 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # when the role's trust policy requires one
391```471```
392 472
393El bloque `assume_role` admite tres claves:473El bloque `assume_role` admite tres claves:
415* Si STS rechaza la llamada o no es accesible, el gateway no envía la solicitud con las credenciales propias del upstream. Registra el error de STS con lo que hay que revisar y luego intenta el siguiente upstream que enumeraste. [Mensajes de error de upstream](#upstream-error-messages) explica lo que recibe el cliente cuando ningún upstream tiene éxito. Un upstream posterior sin `assume_role` serviría la solicitud con sus propias credenciales, así que enumera uno solo si eso es lo que quieres.495* Si STS rechaza la llamada o no es accesible, el gateway no envía la solicitud con las credenciales propias del upstream. Registra el error de STS con lo que hay que revisar y luego intenta el siguiente upstream que enumeraste. [Mensajes de error de upstream](#upstream-error-messages) explica lo que recibe el cliente cuando ningún upstream tiene éxito. Un upstream posterior sin `assume_role` serviría la solicitud con sus propias credenciales, así que enumera uno solo si eso es lo que quieres.
416* El gateway llama al endpoint regional de STS `sts.<region>.amazonaws.com`, al que su red debe poder llegar. Para el endpoint FIPS, establece `AWS_USE_FIPS_ENDPOINT=true` en el entorno del gateway en lugar de `use_fips_endpoint` en un archivo de configuración de AWS.496* El gateway llama al endpoint regional de STS `sts.<region>.amazonaws.com`, al que su red debe poder llegar. Para el endpoint FIPS, establece `AWS_USE_FIPS_ENDPOINT=true` en el entorno del gateway en lugar de `use_fips_endpoint` en un archivo de configuración de AWS.
417* `assume_role` se aplica solo a `provider: bedrock` y necesita credenciales de origen SigV4: el gateway se niega a iniciar cuando se establece junto a `aws_bearer_token`.497* `assume_role` se aplica solo a `provider: bedrock` y necesita credenciales de origen SigV4: el gateway se niega a iniciar cuando se establece junto a `aws_bearer_token`.
418* Cualquier desarrollador que el gateway admita puede usar este upstream; [`managed`](#managed) rige qué desarrolladores pueden usar qué modelos. Para evitar que un modelo servido a través del rol se sirva también desde otra cuenta, asígnale un ID personalizado cuyo mapa `upstream_model` contenga solo el nombre de este upstream. Para un ID así, el gateway omite todos los demás upstreams, de modo que ni la solicitud ni el conteo de tokens de una solicitud abortada pueden conmutar por error a otra cuenta. Una solicitud para un nombre de modelo integrado aún puede [llegar a este upstream](#multiple-upstreams), y el gateway la firma con el mismo rol. Enumera este upstream al final a menos que su cuenta también deba servir esos modelos.498* Sin una [lista `groups`](#send-each-team-to-its-own-upstream), todos los desarrolladores que admite el gateway pueden usar este upstream. Para limitar qué modelos puede usar un desarrollador, establece `availableModels` en una política [`managed`](#managed).
499* Para evitar que un modelo servido a través del rol también se sirva desde otra cuenta, asígnale un id personalizado cuyo mapa `upstream_model` tenga solo el nombre de este upstream. Para ese id, el gateway omite todos los demás upstreams, por lo que ni la solicitud ni el recuento de tokens de una solicitud abortada pueden conmutar a otra cuenta.
500* Una solicitud de un nombre de modelo integrado todavía puede [llegar a este upstream](#multiple-upstreams), y el gateway la firma con el mismo rol. Incluye este upstream en último lugar a menos que su cuenta también deba servir esos modelos.
419 501
420Este ejemplo asigna a un modelo un ID personalizado que solo sirve el upstream aislado:502Este ejemplo asigna a un modelo un ID personalizado que solo sirve el upstream aislado:
421 503
422```yaml theme={null}504```yaml theme={null}
423models:505models:
424 - id: restricted-claude-opus-4-8 # un ID personalizado, no un nombre de modelo integrado506 - id: restricted-claude-opus-4-8 # a custom id, not a built-in model name
425 upstream_model:507 upstream_model:
426 bedrock-isolated: us.anthropic.claude-opus-4-8 # el único upstream que lo sirve508 bedrock-isolated: us.anthropic.claude-opus-4-8 # the only upstream that serves it
427```509```
428 510
429##### Atribución de costos de AWS por desarrollador511##### Atribución de costos de AWS por desarrollador
436upstreams:518upstreams:
437 - provider: bedrock519 - provider: bedrock
438 region: us-east-1520 region: us-east-1
439 auth: {} # el rol propio del gateway: solo llama a STS521 auth: {} # the gateway's own role: it only calls STS
440 assume_role:522 assume_role:
441 role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user523 role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
442 session_name: email # o sub524 session_name: email # or sub
443```525```
444 526
445`session_name` selecciona qué reclamación verificada se convierte en el `RoleSessionName` de AWS: `email` o `sub`. El gateway escribe cualquier carácter que no sea una letra ASCII, un dígito o uno de `_+,.@-` como `=XX` en hexadecimal por cada byte UTF-8, y acorta un resultado de más de 64 caracteres a un prefijo más un hash, de modo que el nombre de sesión de cada desarrollador sigue siendo válido y único. Una solicitud de un desarrollador cuyo token carece de la reclamación no se envía a través de este upstream, y el registro del operador indica que cambies a `sub` o establezcas [`oidc.email_claim`](#oidc).527`session_name` selecciona qué reclamación verificada se convierte en el `RoleSessionName` de AWS: `email` o `sub`. El gateway escribe cualquier carácter que no sea una letra ASCII, un dígito o uno de `_+,.@-` como `=XX` en hexadecimal por cada byte UTF-8, y acorta un resultado de más de 64 caracteres a un prefijo más un hash, de modo que el nombre de sesión de cada desarrollador sigue siendo válido y único. Una solicitud de un desarrollador cuyo token carece de la reclamación no se envía a través de este upstream, y el registro del operador indica que cambies a `sub` o establezcas [`oidc.email_claim`](#oidc).
460upstreams:542upstreams:
461 - provider: mantle543 - provider: mantle
462 region: us-east-1544 region: us-east-1
463 models: [claude-opus-4-7, claude-haiku-4-5] # requerido545 models: [claude-opus-4-7, claude-haiku-4-5] # required
464 auth: {} # cadena de credenciales por defecto de AWS546 auth: {} # AWS default credential chain
465 - provider: bedrock547 - provider: bedrock
466 region: us-east-1548 region: us-east-1
467 auth: {}549 auth: {}
499 region: us-east-1581 region: us-east-1
500 workspace_id: wrkspc_...582 workspace_id: wrkspc_...
501 auth:583 auth:
502 api_key: ${ANTHROPIC_AWS_API_KEY} # enviada como x-api-key584 api_key: ${ANTHROPIC_AWS_API_KEY} # sent as x-api-key
503 # O SigV4 mediante la cadena de credenciales por defecto de AWS:585 # OR SigV4 via the AWS default credential chain:
504 # auth: {}586 # auth: {}
505 # O credenciales SigV4 explícitas:587 # OR explicit SigV4 credentials:
506 # auth:588 # auth:
507 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}589 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}
508 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}590 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
509 # Sobrescribe el endpoint derivado:591 # Override the derived endpoint:
510 # base_url: https://aws-external-anthropic.us-east-1.api.aws592 # base_url: https://aws-external-anthropic.us-east-1.api.aws
511```593```
512 594
531 - provider: vertex613 - provider: vertex
532 region: us-east5614 region: us-east5
533 project_id: example-prod615 project_id: example-prod
534 auth: {} # preferido: Application Default Credentials616 auth: {} # preferred: Application Default Credentials
535 # O un archivo de clave de cuenta de servicio:617 # OR a service account key file:
536 # auth: { service_account_json: /secrets/sa.json }618 # auth: { service_account_json: /secrets/sa.json }
537 # Sobrescribe el endpoint de aiplatform para Private Service Connect:619 # Override the aiplatform endpoint for Private Service Connect:
538 # base_url: https://us-east5-aiplatform.p.googleapis.com620 # base_url: https://us-east5-aiplatform.p.googleapis.com
539```621```
540 622
558upstreams:640upstreams:
559 - provider: foundry641 - provider: foundry
560 resource: example-foundry # https://example-foundry.services.ai.azure.com642 resource: example-foundry # https://example-foundry.services.ai.azure.com
561 auth: { use_azure_ad: true } # preferido: DefaultAzureCredential / Managed Identity643 auth: { use_azure_ad: true } # preferred: DefaultAzureCredential / Managed Identity
562 # O una clave de API:644 # OR an API key:
563 # auth:645 # auth:
564 # api_key: ${FOUNDRY_API_KEY}646 # api_key: ${FOUNDRY_API_KEY}
565```647```
627 709
628`429` indica capacidad por upstream, por lo que el agotamiento del rendimiento aprovisionado (PT) conmuta por error a bajo demanda. Si estableces [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) en un upstream, un `429` a una solicitud que llevaba el correo electrónico del desarrollador es en cambio una denegación por usuario y no conmuta por error.710`429` indica capacidad por upstream, por lo que el agotamiento del rendimiento aprovisionado (PT) conmuta por error a bajo demanda. Si estableces [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run) en un upstream, un `429` a una solicitud que llevaba el correo electrónico del desarrollador es en cambio una denegación por usuario y no conmuta por error.
629 711
630Cada solicitud comienza en el primer upstream. Una solicitud llega a un upstream posterior solo cuando todos los upstreams anteriores han fallado o no sirven el modelo solicitado.712Una solicitud pasa de un upstream al siguiente solo en estos casos:
713
714* El upstream ha fallado
715* El upstream no sirve el modelo solicitado
716* El upstream tiene una [lista `groups`](#send-each-team-to-its-own-upstream) que deja fuera al desarrollador
631 717
632El gateway no guarda registro de los upstreams que fallaron, así que mientras un upstream está caído, cada solicitud que llega a él lo sigue intentando y espera a que falle antes de pasar al siguiente.718El gateway no guarda registro de los upstreams que fallaron, así que mientras un upstream está caído, cada solicitud que llega a él lo sigue intentando y espera a que falle antes de pasar al siguiente.
633 719
680| - | - |766| - | - |
681| Distintas regiones | Un upstream de Amazon Bedrock por región, cada uno con su propio `region:`. Con [`auto_include_builtin_models: true`](#models) los perfiles de inferencia entre regiones se enrutan automáticamente; para despliegues fijados a una región, usa un bloque `models:`. |767| Distintas regiones | Un upstream de Amazon Bedrock por región, cada uno con su propio `region:`. Con [`auto_include_builtin_models: true`](#models) los perfiles de inferencia entre regiones se enrutan automáticamente; para despliegues fijados a una región, usa un bloque `models:`. |
682| Distintas cuentas | Un upstream de Amazon Bedrock por cuenta. La cadena por defecto (`auth: {}`) usa la identidad del pod; para una segunda cuenta, agrega [`assume_role`](#bedrock-in-another-aws-account) para acceder a ella con credenciales de corta duración, o establece credenciales explícitas o un token bearer en `auth:`. |768| Distintas cuentas | Un upstream de Amazon Bedrock por cuenta. La cadena por defecto (`auth: {}`) usa la identidad del pod; para una segunda cuenta, agrega [`assume_role`](#bedrock-in-another-aws-account) para acceder a ella con credenciales de corta duración, o establece credenciales explícitas o un token bearer en `auth:`. |
769| Distintos equipos | Dale al upstream de cada equipo una lista `groups`, de modo que solo los desarrolladores de esos grupos del IdP lleguen a él. Consulta [Envía cada equipo a su propio upstream](#send-each-team-to-its-own-upstream). |
683| Rendimiento aprovisionado | Asigna el modelo al ARN de rendimiento aprovisionado en `models:` para el nombre de ese upstream. Los demás upstreams conservan el ID bajo demanda, por lo que la capacidad de PT se agota antes de conmutar por error. |770| Rendimiento aprovisionado | Asigna el modelo al ARN de rendimiento aprovisionado en `models:` para el nombre de ese upstream. Los demás upstreams conservan el ID bajo demanda, por lo que la capacidad de PT se agota antes de conmutar por error. |
684| Endpoints de VPC / FIPS | Establece `base_url:` en el upstream con la URL de tu endpoint de VPC o FIPS |771| Endpoints de VPC / FIPS | Establece `base_url:` en el upstream con la URL de tu endpoint de VPC o FIPS |
685| Enrutamiento limitado por modelo | Solo un `id` de modelo personalizado, es decir, uno que no sea un modelo Claude integrado, omite los upstreams ausentes de su mapa `upstream_model:`. Un upstream `mantle` se intenta solo para los modelos enumerados en su [campo `models`](#amazon-bedrock-mantle-endpoint). En todos los demás upstreams, el gateway intenta los modelos integrados en orden y usa el ID por defecto del proveedor donde el mapa no tiene entrada, por lo que para los modelos integrados el mapa cambia qué ID recibe un upstream y no si se intenta; un upstream que rechaza el ID sigue las mismas [reglas de conmutación por error](#upstreams) que cualquier otro error de upstream. |772| Enrutamiento por modelo | Un `id` de modelo personalizado, uno que no es un modelo Claude integrado, omite los upstreams ausentes de su mapa `upstream_model:`. Un upstream con una lista `models`, que un [upstream `mantle`](#amazon-bedrock-mantle-endpoint) debe tener, solo se prueba para esos modelos. |
773| Enrutamiento de modelos integrados | En un upstream sin lista `models` ni `groups`, el gateway prueba los modelos integrados en orden y usa el ID predeterminado del proveedor cuando el mapa `upstream_model:` no tiene una entrada. Para un modelo integrado para el que el proveedor tiene un ID predeterminado, el mapa cambia qué ID recibe un upstream, no si se prueba o no. Un upstream que rechaza el ID sigue las mismas [reglas de conmutación por error](#upstreams) que cualquier otro error de upstream. |
686 774
687Conmutar por error entre proveedores de nube, o a la API de Anthropic directa, cambia qué acuerdo, geografía y demás términos rigen la solicitud.775Conmutar por error entre proveedores de nube, o a la API de Anthropic directa, cambia qué acuerdo, geografía y demás términos rigen la solicitud.
688 776
689La CLI aplica la misma restricción de funciones a los gateways independientemente de qué upstream sirva una solicitud determinada, por lo que, por defecto, la conmutación por error no envía un campo del cuerpo que un upstream rechazaría. Si estableces el [TTL de caché de una hora](#one-hour-prompt-cache) en una política, se envía a todos los upstreams de la lista, así que establécelo solo si todos lo aceptan.777La CLI aplica la misma restricción de funciones a los gateways independientemente de qué upstream sirva una solicitud determinada, por lo que, por defecto, la conmutación por error no envía un campo del cuerpo que un upstream rechazaría. Si estableces el [TTL de caché de una hora](#one-hour-prompt-cache) en una política, se envía a todos los upstreams de la lista, así que establécelo solo si todos lo aceptan.
690 778
779#### Envía cada equipo a su propio upstream
780
781Para enviar las solicitudes de cada equipo a su propia cuenta de AWS o a su propio proyecto de Google Cloud, enumera un upstream por equipo y dale a cada uno una lista `groups`. Solo los desarrolladores de un grupo del IdP enumerado llegan a ese upstream, tanto en el primer intento como en la [conmutación por error](#multiple-upstreams). Todos los proveedores admiten `groups`. Requiere Claude Code v2.1.314 o posterior en el servidor del gateway.
782
783Este ejemplo asigna una cuenta de AWS a cada uno de los grupos `payments-eng` y `search-eng`, y agrega un upstream sin lista `groups` que cualquier desarrollador puede usar:
784
785```yaml theme={null}
786upstreams:
787 - name: bedrock-payments
788 provider: bedrock
789 region: us-east-1
790 auth: {}
791 assume_role:
792 role_arn: arn:aws:iam::111111111111:role/claude-gateway-bedrock
793 groups: [payments-eng]
794 - name: bedrock-search
795 provider: bedrock
796 region: us-east-1
797 auth: {}
798 assume_role:
799 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
800 groups: [search-eng]
801 - name: bedrock-shared # no groups: open to everyone, so listed last
802 provider: bedrock
803 region: us-east-1
804 auth: {}
805```
806
807Con la configuración de ejemplo, las solicitudes de cada desarrollador comienzan en el primer upstream de su fila y pasan al siguiente en caso de conmutación por error:
808
809| Grupos del desarrollador | Upstreams, en orden |
810| - | - |
811| `payments-eng` | `bedrock-payments`, luego `bedrock-shared` |
812| `search-eng` | `bedrock-search`, luego `bedrock-shared` |
813| `payments-eng` y `search-eng` | `bedrock-payments`, luego `bedrock-search`, luego `bedrock-shared` |
814| Ninguno | `bedrock-shared` |
815
816Cuando el upstream de un equipo deniega el modelo solicitado con un `403`, el gateway prueba el siguiente upstream de la fila de ese equipo que sirva el modelo. Para mantener al equipo en un solo upstream, dale a cada upstream una lista `groups` y asegúrate de que ningún otro upstream enumere un grupo al que pertenezcan los desarrolladores del equipo. Ese equipo entonces no tiene conmutación por error, y las solicitudes de desarrolladores que no están en ningún grupo enumerado [fallan con un `400`](#what-happens-when-a-developer-is-in-no-listed-group).
817
818Para que cada desarrollador llegue al upstream que pretendes, escribe entradas que coincidan exactamente y coloca los upstreams abiertos al final:
819
820* **Entradas**: escribe cada grupo exactamente como tu IdP lo envía en el [claim de grupos](#oidc), que [`match.groups`](#managed) también lee. El gateway se niega a iniciarse cuando encuentra una lista vacía o una entrada vacía. No comprueba las entradas con tu IdP, así que una entrada que no coincide con nadie no genera ninguna advertencia.
821* **Orden**: coloca al final un upstream que no tenga lista `groups`. Sirve a todos, así que si aparece antes, toma las solicitudes de un equipo antes que el propio upstream de ese equipo.
822
823> [!WARNING]
824>
825> Un gateway anterior a v2.1.314 se niega a iniciarse cuando encuentra `groups`, así que actualiza todas las réplicas antes de agregarlo.
826>
827> Antes de revertir a una versión anterior, elimina cada upstream que tenga una lista `groups` y cada clave de `upstream_model` o sobrescritura de precios que lo nombre, y conserva al menos un upstream. Si solo eliminas la clave `groups`, ese upstream queda abierto a todos los desarrolladores. Una clave o sobrescritura que todavía nombre un upstream eliminado impide que el gateway se inicie, con `references unknown upstream`.
828
829##### Qué sucede cuando un desarrollador no está en ningún grupo enumerado
830
831Si cada upstream tiene una lista `groups`, un desarrollador que no está en ninguno de esos grupos ve este error, y el gateway no contacta a ningún proveedor:
832
833```text theme={null}
834API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one
835```
836
837Agrega al desarrollador a un grupo enumerado en tu IdP, o agrega un upstream sin lista `groups`.
838
839El gateway vuelve a leer los grupos de un desarrollador en cada renovación del token. Si tu IdP omite los grupos en una renovación, el desarrollador queda sin ninguno:
840
841* **[`oidc.allowed_groups`](#oidc) está configurado**: el gateway rechaza la renovación y la sesión termina
842* **En otro caso, si un upstream no tiene lista `groups`**: las solicitudes del desarrollador pasan a él
843* **En otro caso, si cada upstream tiene una lista `groups`**: las solicitudes del desarrollador fallan con ese error
844
845Si el endpoint userinfo de tu IdP devuelve el claim de grupos y `oidc.google_groups` no está configurado, configura [`oidc.userinfo_fallback`](#oidc) en `true` para completar los grupos desde ahí.
846
691## Secciones opcionales847## Secciones opcionales
692 848
693### `admin`849### `admin`
782 938
783#### Enviar las tarifas a los clientes con sesión iniciada939#### Enviar las tarifas a los clientes con sesión iniciada
784 940
785Con v2.1.268 o posterior en el servidor del gateway, el gateway también coloca las tarifas de `pricing` en las políticas [`managed`](#managed) que sirve, como el ajuste administrado [`modelPricing`](https://code.claude.com/docs/es/settings-reference#modelpricing). Los desarrolladores que coinciden con una política ven entonces las tarifas de `pricing` del primer upstream que atiende cada ID de modelo en `/usage`, la línea de estado y OpenTelemetry. Un desarrollador que no coincide con ninguna política no recibe configuración administrada, por lo que sus cifras se mantienen en el precio de lista. Los clientes aplican el ajuste en Claude Code v2.1.242 o posterior.941Con v2.1.268 o posterior en el servidor del gateway, el gateway también incluye las tarifas de `pricing` en las políticas [`managed`](#managed) que sirve, como el ajuste administrado [`modelPricing`](https://code.claude.com/docs/es/settings-reference#modelpricing).
942
943Los desarrolladores que coinciden con una política ven entonces las tarifas de `pricing` en `/usage`, la línea de estado y OpenTelemetry. Un desarrollador que no coincide con ninguna política no recibe configuración administrada, por lo que sus cifras se quedan en el precio de lista. Los clientes aplican el ajuste en Claude Code v2.1.242 o posterior.
786 944
787* Lo que agrega el gateway: a menos que el bloque `cli` de una política ya establezca `modelPricing`, el gateway agrega el `multiplier` y, para cada ID de modelo que un cliente puede solicitar, la fila de sobrescritura del primer upstream que atiende ese ID. Una tarifa que solo cobra un upstream de conmutación por error se queda en el gateway.945* Lo que agrega el gateway: a menos que el bloque `cli` de una política ya establezca `modelPricing`, el gateway agrega el `multiplier` y, para cada ID de modelo que un cliente puede solicitar, la fila de sobrescritura del primer upstream que atiende ese ID. Una tarifa que solo cobra un upstream de conmutación por error se queda en el gateway.
946* Upstreams con una [lista `groups`](#send-each-team-to-its-own-upstream): cuando uno es el primer upstream que atiende un ID de modelo, el gateway no agrega ninguna fila para ese ID. Los desarrolladores ven entonces la tarifa propia de Claude Code para ese ID, que es la tarifa estándar del modelo cuando Claude Code reconoce el ID, multiplicada por el `multiplier`.
788* Excluir una política: establece `modelPricing` en `{}` en el bloque `cli` de esa política, y sus desarrolladores se mantienen en el precio de lista.947* Excluir una política: establece `modelPricing` en `{}` en el bloque `cli` de esa política, y sus desarrolladores se mantienen en el precio de lista.
789* Conservar las tarifas propias de una política: una política cuyo bloque `cli` establece `modelPricing` con su propio `multiplier` u `overrides` conserva ese `modelPricing` completo, y el gateway no le agrega tarifas propias.948* Conservar las tarifas propias de una política: una política cuyo bloque `cli` establece `modelPricing` con su propio `multiplier` u `overrides` conserva ese `modelPricing` completo, y el gateway no le agrega tarifas propias.
790 949
808 967
809### `managed`968### `managed`
810 969
811El bloque `managed` define políticas de acceso basadas en roles según grupos de IdP o dominio de correo electrónico. Las políticas se evalúan en orden; se selecciona la primera coincidencia y luego se fusiona sobre la base de captura general `match: {}`. Se sirven por usuario en `GET /managed/settings` con almacenamiento en caché ETag/304.970El bloque `managed` define políticas de acceso basadas en roles según los grupos del IdP o el dominio de correo electrónico. Las políticas se evalúan en orden; de forma predeterminada se selecciona la primera coincidencia, que luego se combina sobre la base general `match: {}`. Un usuario que coincide con dos políticas de rol obtiene solo la primera, por lo que las reglas de denegación de la segunda política no se aplican a menos que [apliques todas las políticas coincidentes](#apply-every-matching-policy). Las políticas se sirven por usuario en `GET /managed/settings` con caché ETag/304.
812 971
813```yaml theme={null}972```yaml theme={null}
814managed:973managed:
849 1008
850Un usuario autenticado que no coincide con ninguna política obtiene los valores predeterminados del gateway, es decir, todos los modelos del catálogo y ninguna configuración administrada. Agrega una captura general `match: {}` al final si quieres una política predeterminada garantizada.1009Un usuario autenticado que no coincide con ninguna política obtiene los valores predeterminados del gateway, es decir, todos los modelos del catálogo y ninguna configuración administrada. Agrega una captura general `match: {}` al final si quieres una política predeterminada garantizada.
851 1010
1011Coloca las reglas de denegación para toda la organización en la política `match: {}`, porque las reglas de una política de grupo solo se aplican mientras el token del usuario incluya ese grupo.
1012
852> [!NOTE]1013> [!NOTE]
853>1014>
854> El gateway no mantiene un directorio de usuarios propio. Autoriza cada solicitud a partir del token de IdP del usuario, leyendo la pertenencia a grupos de la reclamación `groups` del token y evaluando las políticas con ella. No hay una lista de usuarios que enumerar ni cuentas que crear previamente y, por lo tanto, no hay endpoint SCIM, porque no hay nada en lo que SCIM pueda sincronizar.1015> El gateway no mantiene un directorio de usuarios propio. Autoriza cada solicitud a partir del token de IdP del usuario, leyendo la pertenencia a grupos de la reclamación `groups` del token y evaluando las políticas con ella. No hay una lista de usuarios que enumerar ni cuentas que crear previamente y, por lo tanto, no hay endpoint SCIM, porque no hay nada en lo que SCIM pueda sincronizar.
862>1023>
863> Claude Desktop sigue [su propio calendario](#when-a-policy-change-reaches-claude-desktop).1024> Claude Desktop sigue [su propio calendario](#when-a-policy-change-reaches-claude-desktop).
864 1025
1026#### Aplicar todas las políticas coincidentes
1027
1028Un usuario que coincide con varias políticas de rol obtiene solo la primera a menos que establezcas `policy_mode: layered` junto a `policies`. Con `layered`, se aplica cada política que coincide con el usuario, hasta la primera política `match: {}`.
1029
1030`policy_mode` requiere Claude Code v2.1.316 o posterior en el servidor del gateway. Un gateway en una versión que no la admite se niega a iniciar cuando encuentra la clave. Actualiza todas las réplicas antes de agregar la clave y elimínala antes de volver a una versión anterior. Este ejemplo tiene un grupo que pierde `WebFetch` y otro que obtiene Opus:
1031
1032```yaml theme={null}
1033managed:
1034 policy_mode: layered
1035 policies:
1036 - match: { groups: [no-web] }
1037 cli:
1038 permissions: { deny: ["WebFetch"] }
1039 - match: { groups: [opus-users] }
1040 cli:
1041 availableModels: [opus, sonnet]
1042 - match: {}
1043 cli:
1044 availableModels: [sonnet]
1045 enforceAvailableModels: true
1046```
1047
1048La tabla muestra lo que recibe un usuario que está tanto en `no-web` como en `opus-users` con el valor predeterminado, `first_match`, y con `layered`.
1049
1050| Ajuste | `first_match` | `layered` |
1051| - | - | - |
1052| `availableModels` | `sonnet` | `opus`, `sonnet` |
1053| `enforceAvailableModels` | `true` | `true` |
1054| `permissions.deny` | `WebFetch` | `WebFetch` |
1055
1056El gateway combina cada política coincidente sobre las que aparecen debajo de ella, con las mismas [reglas de combinación](#managed) que la capa base:
1057
1058* **Listas de permitidos, valores individuales y bloques como `sandbox`**: cada uno proviene completo de la primera política coincidente de la lista que lo establece, por lo que las listas `availableModels` de dos grupos no se suman.
1059* **Listas de denegación y arrays de hooks**: estas se suman en todas las políticas coincidentes, por lo que un usuario en dos grupos obtiene las reglas de denegación de ambos grupos.
1060* **`env`, `modelOverrides` y `skillOverrides`**: las entradas se combinan por nombre, y la primera política coincidente de la lista que establece un nombre proporciona su valor.
1061* **Claves de `desktop`**: estas se combinan según [las reglas del bloque `desktop` base](#how-a-role-policy-inherits-the-base-desktop-block).
1062
1063> [!WARNING]
1064>
1065> Las políticas pueden sumarse en reglas más permisivas que las que da cualquiera de ellas por separado. Por ejemplo, la política `match: {}` establece `sandbox.enabled: true`, la política de un grupo establece `permissions.allow: ["Bash"]` y la de otro grupo establece `sandbox.enabled: false`. Un usuario en ambos grupos recibe `Bash` permitido con el sandbox desactivado. En este caso, coloca primero la política que permite `Bash` y copia en ella el bloque `sandbox` completo de la política `match: {}`.
1066
1067Con `layered`, el gateway se niega a iniciar con algunos ajustes, entre ellos estos:
1068
1069* **Un patrón `!`**: una [negación `!`](https://code.claude.com/docs/es/permissions#special-characters-and-negation) en una regla `Read` o `Edit` en la lista `permissions.deny` o `permissions.ask` de cualquier política, incluida la de la política `match: {}`
1070* **Un límite sobre hooks fuera de la política general**: `disableAllHooks`, `allowedHttpHookUrls` o `httpHookAllowedEnvVars` en cualquier política que no sea `match: {}`
1071
865#### Iniciar las sesiones en un modelo que la política permite1072#### Iniciar las sesiones en un modelo que la política permite
866 1073
867Si `availableModels` deja fuera el modelo predeterminado de Claude Code, las sesiones reciben respuestas `400` hasta que el desarrollador elige un modelo de la lista, por ejemplo con `/model`. En las sesiones del gateway, el predeterminado es el modelo Opus al que se resuelve el alias `opus`, y `availableModels` por sí solo no lo cambia.1074Si `availableModels` deja fuera el modelo predeterminado de Claude Code, las sesiones reciben respuestas `400` hasta que el desarrollador elige un modelo de la lista, por ejemplo con `/model`. En las sesiones del gateway, el predeterminado es el modelo Opus al que se resuelve el alias `opus`, y `availableModels` por sí solo no lo cambia.
