Variables de entorno para agentes
os.environ, os.getenv() y por qué nunca debe codificar secretos directamente en el código fuente.
Variables de entorno para agentes es una lección gratuita de AI Agents en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Agents, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Agents incluye 4 lecciones en total.
¿Por qué no incluir las claves de API directamente en el código?
Incluir claves de API directamente en el código fuente es uno de los errores de seguridad más comunes y costosos. Las claves confirmadas en el control de versiones quedan visibles para todas las personas que tienen acceso al repositorio, incluidos futuros colaboradores, sistemas de CI y cualquiera que encuentre el repositorio en Internet.
El problema del historial de Git
Aunque más adelante elimine una clave incluida directamente en el código, esta permanece en el historial de git. Cualquiera que clone el repositorio y ejecute git log o git show puede encontrarla. Las claves no deben entrar nunca en el control de versiones.
import os
os.environ['OPENAI_API_KEY'] = 'sk-proj-abc123def456' # simulate deployment env
OPENAI_API_KEY = os.environ['OPENAI_API_KEY']
print('Key loaded from environment — never hard-coded')os.environ[] frente a os.getenv()
Hay dos formas de leer variables de entorno. os.environ['KEY'] genera KeyError si falta la variable, lo que resulta útil para las claves obligatorias. os.getenv('KEY', default) devuelve un valor predeterminado si falta, lo que resulta útil para las configuraciones opcionales.
import os
os.environ['OPENAI_API_KEY'] = 'sk-proj-demo-key'
try:
openai_key = os.environ['OPENAI_API_KEY']
except KeyError:
print('ERROR: OPENAI_API_KEY environment variable is not set!')
raise
model = os.getenv('AGENT_MODEL', 'gpt-4o-mini')
timeout = float(os.getenv('AGENT_TIMEOUT', '30'))
log_level = os.getenv('LOG_LEVEL', 'INFO')
max_steps = int(os.getenv('AGENT_MAX_STEPS', '20'))
print(f'Model: {model}, Timeout: {timeout}s, Log: {log_level}')Validación de las variables de entorno obligatorias al iniciar
Una buena práctica consiste en comprobar todas las variables de entorno obligatorias al iniciar y detenerse de inmediato con un mensaje de error claro. Esto evita fallos difíciles de depurar en lo más profundo de un bucle de agente cuando falta una clave.
import os
import sys
REQUIRED_VARS = [
'OPENAI_API_KEY',
'SEARCH_API_KEY',
'DATABASE_URL'
]
def check_required_env_vars():
missing = [var for var in REQUIRED_VARS if not os.getenv(var)]
if missing:
print('FATAL: Missing required environment variables:')
for var in missing:
print(f' - {var}')
print('\nSet these in your .env file or shell environment.')
sys.exit(1)
print(f'All {len(REQUIRED_VARS)} required environment variables are set.')
# Call this at the very start of your agent:
# check_required_env_vars()
if __name__ == '__main__':
for var in REQUIRED_VARS:
os.environ.setdefault(var, 'demo-value')
check_required_env_vars()
El principio de The 12-Factor App
La metodología The 12-Factor App define buenas prácticas para el software moderno. Factor III: almacenar la configuración en el entorno. Todo lo que varía entre implementaciones (desarrollo, preparación y producción), como las claves de API, las URL y los indicadores de funcionalidades, debe proceder de variables de entorno y no del código.
import os
os.environ['OPENAI_API_KEY'] = 'sk-proj-demo'
os.environ['SEARCH_API_KEY'] = 'tvly-demo'
os.environ['DATABASE_URL'] = 'postgresql://user:pass@localhost/agentdb'
config = {
'openai_key': os.environ['OPENAI_API_KEY'],
'search_key': os.environ['SEARCH_API_KEY'],
'database_url': os.environ['DATABASE_URL'],
'redis_url': os.getenv('REDIS_URL', 'redis://localhost:6379'),
'enable_caching': os.getenv('ENABLE_CACHING', 'true') == 'true',
'max_results': int(os.getenv('MAX_RESULTS', '10')),
'log_level': os.getenv('LOG_LEVEL', 'INFO'),
'env': os.getenv('ENV', 'development')
}
print('Config loaded from environment:', config['env'])Configuración de variables de entorno en el shell
Configure las variables de entorno en la sesión de su terminal con export (Mac/Linux) o set (Windows). Estarán disponibles para cualquier programa que ejecute en esa sesión.
# Mac/Linux (bash/zsh):
# export OPENAI_API_KEY='sk-proj-your-key-here'
# export AGENT_MODEL='gpt-4o-mini'
# python agent.py
# Windows (Command Prompt):
# set OPENAI_API_KEY=sk-proj-your-key-here
# python agent.py
# Windows (PowerShell):
# $env:OPENAI_API_KEY = 'sk-proj-your-key-here'
# python agent.py
# One-liner (temporary, only for this command):
# OPENAI_API_KEY='sk-proj-...' python agent.py
print('Shell exports set env vars for the current session only')Enumeración de las variables obligatorias en comentarios del código
Documente qué variables de entorno necesita su agente directamente en el código fuente. Un nuevo desarrollador debería poder leer el principio del archivo del agente y saber exactamente qué debe configurar.
# agent.py
#
# REQUIRED ENVIRONMENT VARIABLES:
# OPENAI_API_KEY OpenAI API key (get from platform.openai.com)
# SEARCH_API_KEY Tavily search API key (get from tavily.com)
#
# OPTIONAL ENVIRONMENT VARIABLES:
# AGENT_MODEL LLM model (default: gpt-4o-mini)
# AGENT_MAX_STEPS Max loop iterations (default: 20)
# LOG_LEVEL Logging verbosity: DEBUG|INFO|WARNING (default: INFO)
# DATABASE_URL PostgreSQL URL (default: none, disables memory storage)
#
# EXAMPLE SETUP:
# cp .env.example .env
# Edit .env with your keys
# python agent.py --query 'Your question'
print('Document required variables at the top of each agent file')Acceso seguro a la configuración anidada
Para los agentes que tienen muchas opciones de configuración, cree una clase de configuración que lea y valide todas las variables de entorno en un solo lugar. Esto centraliza la validación y hace que el resto del código sea más limpio.
import os
class AgentConfig:
def __init__(self):
self.openai_key = self._require('OPENAI_API_KEY')
self.search_key = self._require('SEARCH_API_KEY')
self.model = os.getenv('AGENT_MODEL', 'gpt-4o-mini')
self.max_steps = int(os.getenv('AGENT_MAX_STEPS', '20'))
self.log_level = os.getenv('LOG_LEVEL', 'INFO')
self.env = os.getenv('ENV', 'development')
def _require(self, key: str) -> str:
value = os.getenv(key)
if not value:
raise EnvironmentError(
f'Required environment variable {key} is not set. '
f'See .env.example for setup instructions.'
)
return value
# config = AgentConfig() # raises clear error if any key is missing
# client = openai.OpenAI(api_key=config.openai_key)
if __name__ == '__main__':
os.environ.setdefault('OPENAI_API_KEY', 'sk-demo-1234')
os.environ.setdefault('SEARCH_API_KEY', 'demo-search-key')
config = AgentConfig()
print(f'Model: {config.model}, max_steps: {config.max_steps}, env: {config.env}')
Enmascarado de claves en los registros
No registre nunca las claves de API sin enmascarar. Si necesita registrar la configuración para depurar, enmascare todos los caracteres salvo los 4 últimos. Así confirmará que la clave se ha cargado sin exponerla.
import os
def mask_key(key: str) -> str:
if not key or len(key) < 8:
return '****'
return '*' * (len(key) - 4) + key[-4:]
def log_config_summary(config: dict):
print('Agent configuration:')
for name, value in config.items():
if 'key' in name.lower() or 'secret' in name.lower() or 'token' in name.lower():
print(f' {name}: {mask_key(value)}')
else:
print(f' {name}: {value}')
config = {
'openai_key': os.getenv('OPENAI_API_KEY', ''),
'model': 'gpt-4o-mini',
'max_steps': '20'
}
log_config_summary(config)
# openai_key: ****abcd
# model: gpt-4o-miniVariables de entorno en Docker y CI
En Docker, pase las variables de entorno mediante las opciones -e o un --env-file. En GitHub Actions, guárdelas como Secrets y haga referencia a ellas en el YAML del flujo de trabajo. No las incluya nunca en la imagen de Docker.
# Docker run with env vars:
# docker run -e OPENAI_API_KEY='sk-...' -e AGENT_MODEL='gpt-4o-mini' myagent:latest
# Docker with an env file:
# docker run --env-file .env myagent:latest
# GitHub Actions workflow (secrets stored in repo settings):
# env:
# OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
# SEARCH_API_KEY: ${{ secrets.SEARCH_API_KEY }}
# docker-compose.yml:
# services:
# agent:
# image: myagent:latest
# env_file:
# - .env
print('Never bake secrets into Docker images — always inject at runtime')Qué hacer cuando se expone una clave
Si confirma accidentalmente una clave de API en un repositorio público o compartido, actúe de inmediato. Dé por hecho que la clave está comprometida en el momento en que deja de estar bajo su control: los bots buscan claves en GitHub a los pocos segundos de una confirmación.
# Immediate response if a key is exposed:
# 1. REVOKE the key immediately (provider dashboard)
# OpenAI: platform.openai.com/api-keys -> Delete key
# Anthropic: console.anthropic.com -> API Keys
# 2. Generate a new key
# 3. Update your .env file with the new key
# 4. Rotate in all environments (staging, prod)
# Remove from git history (does NOT guarantee removal from forks/clones):
# git filter-branch or git-filter-repo to rewrite history
# Force push to all branches
# Note: Rewriting git history cannot undo exposure
# if others have already cloned or forked the repo
print('Revoke immediately. Do not just remove from code — rotate the key.')Comprobación de conocimientos: variables de entorno
Compruebe sus conocimientos sobre las variables de entorno para gestionar los secretos de los agentes.
Repaso: variables de entorno para agentes
Ahora comprende el enfoque correcto para gestionar secretos en agentes:
- No incluya nunca claves de API directamente en el código: terminan para siempre en el historial de git
- Use
os.environ['KEY']para las variables obligatorias yos.getenv('KEY', default)para las opcionales - Valide todas las variables obligatorias al iniciar y muestre un mensaje de error claro
- Documente las variables obligatorias en comentarios del código y en
.env.example - Enmascare las claves en los registros y muestre solo los 4 últimos caracteres
- Inyecte los secretos en tiempo de ejecución en Docker; use GitHub Secrets en CI
- Si se expone una clave: revoque primero y, después, rótela en todas partes
Preguntas frecuentes
¿La lección «Variables de entorno para agentes» es gratis?
Sí — el texto completo de «Variables de entorno para agentes» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Agents, actualiza a CoddyKit PRO. El curso de AI Agents incluye 4 lecciones en total.
¿Qué aprenderé en «Variables de entorno para agentes»?
os.environ, os.getenv() y por qué nunca debe codificar secretos directamente en el código fuente. Practicas AI Agents con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar AI Agents?
No se requiere experiencia previa. AI Agents en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.
¿Cuánto tiempo toma la lección «Variables de entorno para agentes»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de AI Agents?
Sí. Cada lección de AI Agents incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Variables de entorno para agentes
- Archivos .env y python-dotenv
- Rotación y seguridad de secretos
- Perfiles de configuración para desarrollo y producción