Secretos y variables de entorno para agentes IA en producción

Tu agente ya pasó el despliegue. Ahora necesita llamar a la API de OpenAI, leer tu base de datos y firmar webhooks. Cada una de esas credenciales es un secreto, y un secreto filtrado significa: factura inesperada, abuso de cuota, o acceso completo a tu infraestructura. El manejo de secretos no es un detalle de configuración: es la parte de seguridad que decide si un agente filtrado es un incidente o una madrugada cambiando llaves. Las fuentes oficiales fueron consultadas el 3 de septiembre de 2026.

Si tu foco es limitar lo que el agente puede tocar a nivel de sistema, sandboxing y permisos cubre esa capa; esta guía cubre la capa de credenciales. El resto de operación (coste, deploy, evals) vive en el hub de seguridad, coste y operación.

Definición citable

Una variable de entorno es un valor de configuración que el runtime inyecta a tu proceso: URLs, flags, niveles de log. Un secreto es una credencial cuyo conocimiento otorga acceso: API keys, tokens, contraseñas, claves privadas. La distinción práctica es simple: si filtrar el valor le da acceso a alguien, es un secreto. La guía de OWASP sobre gestión de secretos parte de esa línea: los secretos no deben transmitirse por red sin cifrar ni almacenarse sin cifrar dentro del código, y su gestión exige minimizar dónde viven, evitar mezclarlos entre entornos y rotarlos con control.

Qué cuenta como secreto (y qué no)

Valor	¿Secreto?	Por qué
API key del proveedor del modelo (OpenAI, Anthropic…)	Sí	Quien la tenga gasta tu saldo y usa tu cuota
Token de bot de Telegram / Slack / WhatsApp	Sí	Permite leer y escribir en tus canales
Cadena de conexión a Postgres / MySQL	Sí	Suele incluir usuario y contraseña
Clave privada (JWT signing, RSA, SSH)	Sí	Otorga identidad, no solo acceso
Signing secret de webhooks (Stripe, GitHub)	Sí	Permite forjar webhooks válidos
URL pública de tu API o webhook	No	Es configuración, no credencial
Nivel de log, flag de features, hostname	No	Filtrarse no da acceso a nada
Modelo por defecto, temperatura	No	Parámetros de producto

Regla de decisión: el proveedor del modelo te da la llave más peligrosa. Es la que se agota primero en un abuso porque los agentes la usan en cada turno, en bucle.

Las tres reglas base

1. El secreto solo vive en el gestor de la plataforma. No en el código, no en .env commiteado, no en el Dockerfile, no en la doc del repo.
2. Por plataforma, no por servidor. Secretos distintos para producción, preview y desarrollo. Un leak en preview no debe dar acceso a producción.
3. Mínimo privilegio. El agente de soporte no necesita la llave de facturación. Si la herramienta no separa scopes, al menos separa proyectos y presupuestos.

OWASP además recomienda no incrustar secretos en variables de entorno heredadas por procesos hijos y revisar qué cadenas de herramientas loguean el entorno completo. Un agente con shell —la configuración más común de agentes de código— imprime su entorno con un printenv, así que darle shell al agente le da acceso a todo lo que el proceso puede leer.

Cómo se inyectan en cada plataforma

Plataforma	Cómo se define	Cómo llega al runtime	Nota clave
Vercel	Dashboard o vercel env add	Inyectada en build y runtime; vercel env pull para descargarla en local	Se asigna por entorno: Production, Preview y Development por separado; una variable marcada Sensitive no se puede volver a leer en el dashboard
Cloudflare Workers	wrangler secret put NOMBRE	Binding cifrado dentro del Worker, no una variable del shell	Secrets y variables van por separado; los cambios activan un redeploy del Worker
Docker / VPS con Swarm	docker secret create	Montado como archivo en /run/secrets/<nombre>, no como variable de entorno	Secretos solo con Swarm; sin Swarm quedan variables de entorno planas o archivos gestionados a mano
GitHub Actions	gh secret set o Settings	secrets.NOMBRE en el workflow, enmascarada en logs	El runner nunca imprime el valor: la salida se reemplaza por ***

Errores comunes que exponen tu API key

• Commitear el .env. El histórico de git guarda todo; borrar el archivo en el último commit no borra el secreto del pasado. Si se filtró: rotar primero, limpiar el repo después.
• Enviarlo al frontend. En Next.js, solo lo que empieza con NEXT_PUBLIC_ llega al navegador. Prefijar una API key con NEXT_PUBLIC_ la publica en el bundle.
• Loguear el error completo. Muchos SDKs imprimen headers o la URL con el token al fallar. Sanitiza errores antes de mandarlos a logs, Sentry o al propio chat del usuario.
• Pegar el secreto en un issue, ticket o chat del agente. Y el más nuevo: pegarlo en el prompt del agente. Un agente con web search o telemetría puede filtrarlo a servicios de terceros.
• Reusar la misma llave en todos los proyectos. Un leak compromete todo. Una llave por proyecto acota el daño.

Rotación: el plan que sí se ejecuta

• Trigger inmediato: sospecha de leak, salida de un integrante del equipo, o una llave que apareció en logs.
• Trigger programado: rotación trimestral para las llaves críticas. En plataformas con bindings cifrados (Workers, Actions) rotar es un comando; en un VPS plano es tocar archivos con cuidado.
• Ventana de doble llave: crea la llave nueva antes de borrar la vieja, despliega, verifica, y solo entonces revoca la anterior. Revocar primero = downtime.
• Auditoría: en los dashboards de los proveedores revisa uso por llave. Una llave con tráfico que no reconoces es un leak en curso.

Checklist antes de Production

• Ningún secreto en el código ni en el histórico de git
• Secretos separados por entorno (Production / Preview / Development)
• La API key del modelo tiene límite de gasto en su dashboard
• Logs sanitizados: ningún valor de secrets.* ni headers de auth impresos
• Plan de rotación escrito: quién, cuándo y cómo se revoca
• El agente no recibe secretos en su prompt, solo por bindings del runtime

---

Siguiente paso: si vas a montar tu agente en un VPS, combina esta guía con sandboxing y permisos para agentes de código — las credenciales limitan quién puede actuar como tu agente; el sandbox limita qué puede tocar una vez dentro. Si todavía no tienes runtime, el curso gratuito deja un agente corriendo para practicar la inyección de secretos sin filtrarlos.