Guardrails de producción para agentes de IA con autonomía segura
Guardrails de producción para agentes de IA que protegen secretos, exigen confirmaciones, registran auditorías, limitan el acceso, estructuran errores y permiten workflows de despliegue autónomo seguro.
Los guardrails de producción para agentes de IA deben resistir algo más que un prompt educado. Un agente de coding autónomo puede malinterpretar un objetivo, repetir una operación, exponer una credencial en su explicación o continuar después de una respuesta ambigua. Por eso, la seguridad en producción debe existir en la interfaz ejecutable, el modelo de autorización y el registro de auditoría, no solo en las instrucciones.
Dockup combina orientación de comportamiento en su skill de Claude Code y Codex con enforcement a nivel de CLI: los secretos se enmascaran, las operaciones destructivas requieren --yes, los fallos devuelven códigos estables, los despliegues pueden esperar hasta alcanzar un estado terminal y las mutaciones aparecen en el registro de auditoría.
¿Por qué deben aplicarse los guardrails por debajo del prompt?
Un prompt es una política útil, pero no constituye un límite de seguridad. El contexto del agente puede truncarse, las instrucciones pueden entrar en conflicto y el modelo puede elegir una interpretación incorrecta. La herramienta subyacente debe dificultar o impedir los comportamientos inseguros.
Considera una solicitud de eliminación. Un diseño débil expone un comando que elimina de inmediato y depende de que el agente recuerde preguntar. Un diseño más sólido rechaza la operación a menos que se incluya un flag de confirmación independiente.
Dockup utiliza el patrón más sólido:
dockup up production/api --prune --json
Sin una confirmación explícita, se rechaza la limpieza destructiva y el JSON incluye code:"needs_confirm". No se elimina nada mediante prune. El agente debe mostrar ese resultado a una persona, recibir aprobación y volver a ejecutar deliberadamente:
dockup up production/api --prune --yes --json
Esto es defense in depth. El skill de Dockup indica al agente que se detenga, mientras que la CLI impide la ejecución accidental incluso si se omite la instrucción.
¿Cómo protege el enmascarado de secretos a los agentes autónomos?
Los agentes suelen incluir la salida de los comandos en su razonamiento o respuesta final. Si una operación de lectura devuelve un token de producción, el secreto puede acabar en el historial del chat, los logs, la telemetría, las capturas de pantalla o las notas de un incidente copiadas.
Una interfaz de configuración segura separa los metadatos de los secretos de sus valores. Dockup devuelve las claves de las variables de entorno y el indicador isSecret, pero los valores almacenados de los secretos son null o aparecen enmascarados.
dockup env list -s production/api --json
El agente puede establecer un secreto sin recuperarlo posteriormente:
dockup env set API_KEY="$API_KEY" \
--secret \
-s production/api \
--json
El enmascarado de secretos no elimina la necesidad de gestionar cuidadosamente los procesos. El valor original sigue existiendo en el entorno del shell durante la operación de configuración. Evita set -x, no hagas echo de la variable y no construyas strings de comandos que queden capturados por un logging detallado.
Las contraseñas de bases de datos, API keys, tokens de registry, credenciales SSH y credenciales de Windows RDP deben tratarse como outputs de un solo uso o de acceso restringido. Un agente debería almacenarlos en un secret manager aprobado o pasarlos directamente al siguiente proceso sin reproducirlos en texto.
El enfoque más amplio a nivel de aplicación se explica en security best practices.
¿Cómo debe funcionar la aprobación de acciones destructivas?
No todas las mutaciones requieren el mismo nivel de formalidad. Un modelo de autonomía útil separa las operaciones según su reversibilidad y blast radius:
| Nivel | Ejemplo | Comportamiento predeterminado del agente |
|---|---|---|
| Solo lectura | Listar servicios, consultar el estado, ver logs | Ejecutar y resumir |
| Escritura reversible | Establecer una variable, activar un despliegue | Ejecutar dentro del scope aprobado |
| Recuperación operativa | Reiniciar, volver a ejecutar un despliegue anterior | Ejecutar si el runbook lo permite; informar de las evidencias |
| Destructiva | Destruir un servicio, eliminar una base de datos, abandonar un proyecto | Detenerse y solicitar aprobación explícita |
| Destructiva amplia | Aplicar --prune, transferir la propiedad | Requerir confirmación humana específica para el objetivo |
La aprobación explícita debe incluir el objetivo exacto y la consecuencia. «Sí, continuar» es menos preciso que «Eliminar staging/old-api y los recursos de servicio asociados». El agente no debe reutilizar una aprobación concedida para otro comando u objetivo.
Dockup config as code es aditivo de forma predeterminada. dockup up no elimina las variables de entorno ni los dominios que no aparezcan en el manifest. Para eliminar elementos es necesario usar explícitamente el flag --prune:
dockup plan production/api --json
dockup up production/api --prune --json
El plan es de solo lectura y debe revisarse primero. Incluso con --prune, los secretos, servicios, bases de datos y volúmenes están protegidos frente a esta ruta de limpieza del manifest. Consulta dockup.yaml config as code para conocer el workflow completo.
¿Cómo ayudan los errores estructurados a limitar la autonomía?
Un agente necesita un conjunto finito de ramas seguras. Los mensajes de texto libre son útiles para las personas, pero los códigos de error estables hacen que la primera respuesta sea determinista.
| Código | Respuesta correcta |
|---|---|
not_logged_in | Detenerse y obtener una credencial válida |
not_linked | Resolver el objetivo o pasarlo explícitamente |
no_target | Ejecutar el descubrimiento de servicios; nunca inventar un slug |
needs_confirm | Solicitar aprobación humana |
deploy_trigger_failed | Informar de por qué no se pudo iniciar la operación |
deploy_failed | Inspeccionar los build logs |
deploy_timeout | Informar de la incertidumbre sobre un estado no terminal |
Un despliegue debe esperar hasta alcanzar un estado terminal:
dockup deploy production/api --wait --json
El timeout predeterminado es de 900 segundos. El código de salida 0 demuestra que el despliegue alcanzó el estado correcto. Un código distinto de cero impide que el agente continúe con cambios de dominio, migraciones o anuncios como si producción estuviera lista.
Este diseño se analiza en AI agent CLI design. El principio es sencillo: la herramienta debe hacer explícito cualquier resultado ambiguo.
¿Qué debe registrar un log de auditoría?
La autonomía sin atribución es deuda operativa. Un registro de auditoría de producción debe responder quién actuó, qué interfaz utilizó, qué objetivo cambió, si fue una lectura o una escritura, cuándo ocurrió y si tuvo éxito.
Dockup registra las acciones realizadas desde la CLI, la UI y la API. Los operadores pueden consultar las mutaciones recientes:
dockup audit --writes --json
dockup audit --number 30 --json
dockup audit --search domains --json
El informe del propio agente debe complementar el registro de la plataforma. Incluye:
- El objetivo
project/serviceresuelto. - La categoría del comando, sin valores secretos.
- Los IDs de despliegue o recursos devueltos por la plataforma.
- El código de salida y el estado estructurado.
- Las evidencias recopiladas después de la mutación.
- Cualquier aprobación recibida para realizar acciones destructivas.
- La incertidumbre restante o las acciones de seguimiento.
Los registros de auditoría no sirven únicamente para buscar culpables después de un incidente. Permiten que otra persona o agente reconstruya el estado sin repetir comandos arriesgados.
¿Cómo pueden los equipos aumentar la autonomía del agente de forma segura?
Empieza con acceso de lectura y un servicio de bajo riesgo. Amplía el alcance solo cuando el agente demuestre que descubre correctamente los objetivos, mantiene una buena higiene de secretos, gestiona las ramas de error y genera informes adecuados.
Una progresión práctica es:
Etapa 1: Observar
Permite consultar listados de servicios, estados, historial de despliegues, build logs, runtime logs, uptime, uso y resultados de security scans. Compara el resumen del agente con el JSON original.
Etapa 2: Desplegar en un objetivo fijo
Permite desplegar un servicio con --wait. Exige un health check y un informe estructurado de finalización. No concedas permisos de eliminación ni permisos de equipo.
Etapa 3: Gestionar configuración reversible
Permite actualizar variables secretas y no secretas, configurar health checks y establecer custom domains conforme a un runbook revisado. Exige volver a desplegar después de cambiar el entorno.
Etapa 4: Ejecutar acciones de recuperación
Permite reiniciar o hacer rollback solo cuando el agente seleccione un ID de despliegue conocido y exacto, y conserve las evidencias del fallo.
Etapa 5: Acciones destructivas protegidas por aprobación
Mantén los flags destructivos detrás de una aprobación humana explícita, incluso cuando la credencial permita técnicamente utilizarlos. Usa API keys con scope siempre que sea posible y revisa periódicamente el registro de auditoría.
La instalación del skill del agente refuerza estos comportamientos:
npm install -g dockup-cli
dockup skill install
dockup skill status --json
La referencia de Dockup CLI documenta el comportamiento aplicado de los comandos. El agente debe verificar su schema local en lugar de basarse en un ejemplo recordado.
Checklist de revisión de guardrails
Antes de conceder acceso a producción, responde a cada pregunta:
- ¿Puede el agente descubrir objetivos exactos sin hacer suposiciones?
- ¿Los valores secretos están enmascarados en todas las rutas de lectura?
- ¿Toda mutación fallida devuelve un valor distinto de cero?
- ¿Las operaciones largas pueden esperar hasta alcanzar un estado terminal?
- ¿Las acciones destructivas están bloqueadas sin confirmación explícita?
- ¿Las credenciales tienen scope y se proporcionan fuera de los prompts?
- ¿Se puede localizar cada mutación en un registro de auditoría?
- ¿Existe un procedimiento de rollback o recuperación probado?
- ¿Pueden divergir las versiones del skill y del ejecutable?
- ¿El informe final separa los hechos de la incertidumbre?
Un «no» es una tarea de diseño, no una tarea de redacción de prompts. La autonomía en producción solo debe crecer a medida que aumentan las garantías subyacentes.
Prueba los guardrails como casos de fallo
Una revisión no está completa hasta que el equipo provoca deliberadamente los límites. Ejecuta un despliegue con un token no válido, solicita un objetivo desconocido, permite que falle un build de prueba, establece un timeout muy corto e intenta ejecutar un comando destructivo sin confirmación. Cada caso debe producir un valor de salida distinto de cero y un código estable, no filtrar secretos ni provocar mutaciones imprevistas.
Estas pruebas convierten los guardrails de producción para agentes de IA en garantías observables. Repítelas después de actualizar la CLI o las políticas, igual que repetirías las pruebas de autenticación y autorización de una aplicación. Un guardrail que solo existe en una presentación no protegerá un release desatendido.
Lleva el workflow a producción
Instala el skill, revisa sus instrucciones y prueba todos los guardrails, incluido un comando destructivo bloqueado, antes de emitir un token de producción.
npm install -g dockup-cli
dockup skill install
El primer comando instala la CLI. El segundo instala el skill de Dockup compatible con Claude Code y Codex. Empieza gratis en app.dockup.ai.
FAQ
¿Bastan las instrucciones del prompt para mantener seguro a un agente de IA en producción?
No. Los prompts ayudan a orientar el comportamiento, pero los controles críticos, como el enmascarado de secretos, las confirmaciones, la autorización, los códigos de salida y el registro de auditoría, deben aplicarse desde la herramienta y la plataforma.
¿Cómo bloquea Dockup las operaciones destructivas?
Los comandos destructivos se niegan a ejecutarse sin el flag explícito --yes y devuelven el código estructurado needs_confirm, lo que permite que el agente se detenga y pregunte a una persona.
¿Puede un agente de IA leer los valores de las variables de entorno secretas desde Dockup?
Los valores secretos almacenados aparecen enmascarados en la salida. El agente puede ver la clave y el indicador de secreto, y puede sustituir el valor, pero no recibe el secreto almacenado.
¿Por qué son importantes los códigos de error estructurados para la autonomía?
Limitan al agente a ramas de recuperación conocidas, como solicitar autenticación, descubrir el objetivo exacto, leer build logs o pedir confirmación.
¿Cómo debería empezar un equipo a conceder acceso a producción?
Empieza con operaciones de solo lectura, permite después desplegar en un único objetivo de bajo riesgo y amplía a la configuración reversible y la recuperación solo cuando el agente informe de forma constante sobre evidencias verificables.