1. Capa 1 — Clave API con alcance
La clave es la primera puerta. Antes de que se inspeccione cualquier contenido o se llame a cualquier modelo, el gateway resuelve la clave llamante y decide si la solicitud está siquiera permitida. Lo que lleva la clave:model_limits— el conjunto de modelos que la clave puede llamar. Una solicitud para un modelo fuera de la lista se rechaza de inmediato.allow_ips— lista de IPs permitidas opcional. Una solicitud de una fuente no listada se rechaza.credit_limit_usd— un tope de gasto fijo. Una solicitud que empujaría la clave por encima del tope se rechaza.expiry— una fecha de expiración fija. Las claves expiradas se rechazan.environment— una etiqueta (production,staging,dev, …) para organizar e identificar la clave por entorno de despliegue.guardrail_id— la política de guardrail que se vincula a esta clave (ver Capa 2 y Capa 4).firewall_policy_id— la política de firewall que se vincula a esta clave (ver Capa 3).is_firewall_gateway— marca la clave como un token con alcance de gateway de firewall; requerido para las rutas de evaluación y gateway MCP.
is_firewall_gateway y lecturas de
clave en texto plano requieren Admin.
Para el modelo completo de claves, ver Alcance, claves, políticas y espacios de trabajo.
2. Capa 2 — Guardrails de entrada
Una vez que la clave está validada, el gateway ejecuta las reglas de etapa de entrada del guardrail vinculado contra el texto de la solicitud — antes de cualquier llamada al modelo upstream. Lo que ve: Los mensajes del llamador tal como se enviaron. (Un prompt inyectado desde un prompt del registro se añade más tarde, en la etapa de enrutamiento; las reglas de entrada no lo ven.) Tipos de regla disponibles:keyword, regex, pii, max_chars,
external, llm_judge, grounding.
Acciones que puede producir una regla:
| Acción | Qué ocurre |
|---|---|
block | La solicitud se rechaza — HTTP 400 guardrail_blocked. No se cobra cuota. Marcada skip-retry. |
mask | La coincidencia se redacta (p. ej. jane@acme.com → [EMAIL]). El texto saneado continúa hacia el modelo. |
flag | La coincidencia se registra; el tráfico no cambia. |
block en esta etapa significa que el modelo nunca se llama. Coste: cero.
El llamador ve un error estructurado que nombra el guardrail y la regla que
se disparó.
Dónde configurar: Consola → Guardrails, o la API de guardrails. Requiere
Developer+ para crear o modificar. Ver Guardrails
para la referencia completa de reglas.
3. Capa 3 — El modelo se ejecuta
Si la clave es válida y los guardrails de entrada pasan, el gateway reenvía la solicitud al modelo upstream. Esta es la única capa sin aplicación configurable — es simplemente el modelo haciendo su trabajo. El firewall opera sobre las acciones que produce el modelo (Capa 3 → Capa 4 a continuación), no sobre el modelo en sí. El enrutamiento, los fallbacks y el balance de carga ocurren aquí de forma transparente.4. Capa 4 — Agent Firewall (llamadas a herramienta y egress)
Después de que el modelo responde — o en línea, a medida que se emiten llamadas a herramienta — el Agent Firewall juzga cada acción que el modelo solicita. Cuatro superficies de aplicación:| Superficie | Lo que ve el firewall |
|---|---|
inbound | Definiciones de herramienta que el agente anuncia al modelo. Bloquea una herramienta peligrosa antes de que el modelo pueda elegirla. |
response | Los tool_calls que el modelo emite en su respuesta. |
mcp | Un tools/call despachado a través del gateway MCP del Firewall o evaluado vía el hook de evaluación. |
egress | Un destino de red saliente (host / IP / CIDR) reportado por una herramienta — la superficie de SSRF y exfiltración de datos. |
| Veredicto | Qué hace |
|---|---|
allow | La llamada procede. Registrada. |
audit | La llamada procede; registrada para revisión. El default_verdict por defecto. |
deny | La llamada se bloquea — HTTP 400 firewall_blocked en la superficie inbound; un error de herramienta en mcp. |
sanitize | Las subcadenas coincidentes se redactan de los argumentos de la herramienta; la llamada limpia procede. En inbound (sin argumentos aún), escala a deny. |
pending_approval | La llamada se retiene; un revisor fuera de banda aprueba o rechaza; el agente reenvía con un token de aprobación de un solo uso. |
cap_cost | Deny una vez que el gasto acumulado de la ejecución del agente supera un tope de centavos por regla. |
deny en la superficie inbound no cuesta tokens de modelo — el bloqueo
se dispara antes de la llamada upstream. Un hold pending_approval devuelve
HTTP 400 firewall_approval_pending con un id de aprobación sobre el que el
cliente hace polling.
Dónde configurar: Consola → Firewall, o la API de firewall. Requiere
Developer+ para crear o modificar políticas y reglas. Ver
Firewall y Reglas del firewall
para el lenguaje completo de reglas.
5. Capa 5 — Guardrails de salida
Después de que el modelo responde (y después de que se completa cualquier ciclo de llamada a herramienta), el gateway ejecuta las reglas de etapa de salida del guardrail vinculado contra el texto de la respuesta antes de que llegue al llamador. Los mismos tipos de regla y acciones aplican que en la Capa 2. Unblock de
salida devuelve HTTP 400 guardrail_blocked y reembolsa la cuota
preconsumida — el llamador no paga nada.
Streaming y enmascarado de salida. Una acción
block se aplica tanto en
respuestas con streaming como sin streaming — en un stream, el escáner corta
en pleno vuelo y emite un reemplazo. Una acción mask en la salida
actualmente solo aplica a respuestas sin streaming; en una respuesta con
streaming el chunk original pasa sin enmascarar. Verifica tu combinación de
etapa/stream en el sandbox del guardrail antes de depender de ello.6. Capa 6 — Auditoría
Cada coincidencia, veredicto y decisión de aprobación se escribe en el rastro de auditoría, correlacionado con la ejecución y la sesión del agente que lo causó. Este no es un paso de aplicación separado — se ejecuta en paralelo con las Capas 2–5 — pero es la capa que hace responsables a las demás. Qué se registra:- Coincidencias de guardrail: tipo de regla, acción, etapa, cadena de detalle y (si Log raw content está habilitado) la subcadena coincidente.
- Eventos del firewall: superficie, nombre de herramienta, veredicto, regla coincidente, código de razón, factores de riesgo y la ejecución/sesión a la que pertenece la llamada.
- Decisiones de aprobación: quién aprobó o rechazó, cuándo y si la regla subyacente cambió entre la retención y la decisión.
- Cambios de política: cada creación, actualización, eliminación y cambio de nivel de autonomía escribe una fila de auditoría versionada.
7. Tabla resumen
| Capa | Qué controla | Qué ve | Resultado en un hit | Dónde configurar |
|---|---|---|---|---|
| 1. Clave con alcance | Identidad, acceso al modelo, gasto, IP, expiración | El token de autenticación de la solicitud | HTTP 4xx antes de que nada se ejecute; sin medición | Consola → API Keys (Developer+) |
| 2. Guardrails de entrada | Contenido del texto de la solicitud | Mensajes del llamador | Bloquear (HTTP 400 guardrail_blocked, sin cargo), enmascarar o marcar | Consola → Guardrails (Developer+) |
| 3. Modelo | — | — | — | Config de enrutamiento / canal |
| 4. Agent Firewall | Llamadas a herramienta, despacho MCP, egress | Nombre de herramienta, argumentos, destino | allow / audit / deny / sanitize / pending_approval / cap_cost | Consola → Firewall (Developer+) |
| 5. Guardrails de salida | Contenido del texto de la respuesta | Respuesta del modelo | Bloquear (HTTP 400, cuota reembolsada), enmascarar o marcar | Consola → Guardrails (Developer+) |
| 6. Auditoría | Atribución y rastro | Todo lo anterior | Entrada de log inmutable | Consola → Matches (Member) / Events & Runs (Developer+) |
8. Orden de resolución de políticas
Para cualquier solicitud, el guardrail activo y la política de firewall se resuelven independientemente:- Adjunto a la clave — si la clave lleva un
guardrail_idexplícito ofirewall_policy_id, esa política vincula (cuando existe y está habilitada). - Valor por defecto del espacio de trabajo — si la clave no tiene adjunto,
el guardrail o política habilitada
is_defaultdel espacio de trabajo aplica. - Ninguno — sin aplicación. La solicitud es byte-idéntica a un espacio de trabajo que nunca habilitó la función.
9. Fail-open y fail-closed
Dos comportamientos — aplicados a casos diferentes.Fail-open (errores transitorios): Si la resolución de políticas encuentra
un error transitorio — un hipo de la DB, un parpadeo de red camino a un
proveedor externo — el gateway degrada a sin aplicación en vez de tumbar el
tráfico. La seguridad se degrada; la disponibilidad se preserva. Configura
fail_open: false en reglas external o llm_judge cuando una verificación
perdida es inaceptable para tu política.Fail-closed (casos ambiguos): Donde no aplicar derrotaría la regla, el
motor falla cerrado: un reporte de egress con un destino irresoluble se niega;
un almacén de aprobaciones inalcanzable retiene la llamada en vez de pasarla;
una skill cuya propiedad no puede resolverse se bloquea. La disponibilidad se
preserva en el camino feliz; la seguridad no se omite silenciosamente en los
casos extremos que importan.10. Profundizaciones
Guardrails
Referencia completa de reglas — tipos, acciones, entidades PII, LLM judge,
grounding y el sandbox de prueba.
Firewall
Modelo de políticas, veredictos, superficies, modo shadow, aprobación HITL
y detección de anomalías.
Reglas del firewall
El lenguaje de coincidencia de reglas — globs de herramienta, cláusulas de
argumentos, listas de egress y saneadores.
Guardrails vs. Firewall
Qué capa captura qué amenaza — y cuándo necesitas ambas.
Alcance, claves y políticas
El modelo completo de claves: qué lleva una clave y cómo se resuelven las
políticas.
Modos de aplicación
Fail-open vs. fail-closed — el árbol de decisión completo.