Variabili d’ambiente per gli agenti
os.environ, os.getenv() e motivi per non inserire mai i segreti direttamente nel codice sorgente
Variabili d’ambiente per gli agenti è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.
Perché non codificare direttamente le chiavi API?
Codificare direttamente le chiavi API nel codice sorgente è uno degli errori di sicurezza più comuni e costosi. Le chiavi inserite nel sistema di controllo versione sono visibili a chiunque abbia accesso al repository, inclusi i futuri collaboratori, i sistemi CI e chiunque trovi il repository online.
Il problema della cronologia Git
Anche se in seguito elimina una chiave codificata direttamente dal codice, questa rimane nella cronologia Git. Chiunque cloni il repository ed esegua git log o git show può trovarla. Le chiavi non devono mai entrare nel sistema di controllo versione.
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[] vs os.getenv()
Esistono due modi per leggere le variabili d'ambiente. os.environ['KEY'] solleva KeyError se la variabile manca, ed è quindi utile per le chiavi obbligatorie. os.getenv('KEY', default) restituisce un valore predefinito se la variabile manca, ed è quindi utile per le impostazioni facoltative.
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}')Convalidare le variabili d'ambiente obbligatorie all'avvio
Una buona pratica consiste nel controllare tutte le variabili d'ambiente obbligatorie all'avvio e interrompere subito l'esecuzione con un messaggio di errore chiaro. In questo modo si evitano errori di runtime difficili da diagnosticare nel mezzo di un ciclo dell'agente, quando manca una chiave.
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()
Il principio della 12-Factor App
La metodologia 12-Factor App definisce le buone pratiche per il software moderno. Fattore III: memorizzare la configurazione nell'ambiente. Tutto ciò che varia tra le distribuzioni (sviluppo, staging, produzione), ovvero chiavi API, URL e flag delle funzionalità, dovrebbe provenire da variabili d'ambiente e non dal codice.
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'])Impostare le variabili d'ambiente nella shell
Imposti le variabili d'ambiente nella sessione del terminale con export (Mac/Linux) o set (Windows). Saranno disponibili per qualsiasi programma eseguito in quella sessione.
# 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')Elencare le variabili obbligatorie nei commenti del codice
Documenti le variabili d'ambiente richieste dall'agente direttamente nel codice sorgente. Un nuovo sviluppatore dovrebbe poter leggere l'inizio del file dell'agente e sapere esattamente che cosa configurare.
# 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')Accedere in sicurezza alla configurazione annidata
Per gli agenti con molte opzioni di configurazione, crei una classe di configurazione che legga e convalidi tutte le variabili d'ambiente in un unico punto. In questo modo la convalida viene centralizzata e il resto del codice risulta più ordinato.
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}')
Mascherare le chiavi nei log
Non registri mai nei log le chiavi API in chiaro. Se deve registrare la configurazione per il debugging, mascheri tutti i caratteri tranne gli ultimi 4. In questo modo può verificare che la chiave sia stata caricata senza esporla.
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-miniVariabili d'ambiente in Docker e CI
In Docker, passi le variabili d'ambiente con i flag -e o con un --env-file. In GitHub Actions, le memorizzi come Secrets e vi faccia riferimento nel file YAML del workflow. Non le includa mai nell'immagine 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')Cosa fare quando una chiave viene esposta
Se inserisce accidentalmente una chiave API in un repository pubblico o condiviso, intervenga immediatamente. Consideri la chiave compromessa dal momento stesso in cui esce dal suo controllo: i bot analizzano GitHub alla ricerca di chiavi entro pochi secondi dalla pubblicazione di un commit.
# 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.')Verifica delle conoscenze: variabili d'ambiente
Verifichi la comprensione delle variabili d'ambiente per la gestione dei segreti degli agenti.
Riepilogo: variabili d'ambiente per gli agenti
Ora conosce l'approccio corretto alla gestione dei segreti per gli agenti:
- Non codifichi mai direttamente le chiavi API: rimangono per sempre nella cronologia Git
- Utilizzi
os.environ['KEY']per le variabili obbligatorie eos.getenv('KEY', default)per quelle facoltative - Convalidi tutte le variabili obbligatorie all'avvio con un messaggio di errore chiaro
- Documenti le variabili obbligatorie nei commenti del codice e in
.env.example - Mascheri le chiavi nei log, mostrando solo gli ultimi 4 caratteri
- Inietti i segreti a runtime in Docker; utilizzi GitHub Secrets nella CI
- Se una chiave viene esposta: la revochi prima, quindi la ruoti ovunque
Domande Frequenti
La lezione «Variabili d’ambiente per gli agenti» è gratuita?
Sì — il testo completo di «Variabili d’ambiente per gli agenti» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.
Cosa imparerò in «Variabili d’ambiente per gli agenti»?
os.environ, os.getenv() e motivi per non inserire mai i segreti direttamente nel codice sorgente Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Agents?
Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.
Quanto tempo richiede la lezione «Variabili d’ambiente per gli agenti»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Agents?
Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Variabili d’ambiente per gli agenti
- File .env e python-dotenv
- Rotazione e sicurezza dei segreti
- Profili di configurazione per sviluppo e produzione