Profili di configurazione per sviluppo e produzione
Configurazioni specifiche per l’ambiente, feature flag e deployment graduali
Profili di configurazione per sviluppo e produzione è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 4 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é i profili di configurazione sono importanti
Un agente di produzione e un agente di sviluppo dovrebbero comportarsi in modo diverso: livelli di logging diversi, livelli diversi del modello (costi e qualità), database diversi e limiti di frequenza diversi. I profili di configurazione rendono tutto questo automatico: una sola variabile d'ambiente cambia tutte le impostazioni contemporaneamente.
Rilevare l'ambiente con la variabile ENV
Il modello standard consiste nel leggere una variabile ENV (o ENVIRONMENT) che identifica il contesto di distribuzione corrente. Il codice seleziona quindi il profilo di configurazione appropriato in base a questo valore.
import os
# Read the environment identifier
ENV = os.getenv('ENV', 'development').lower()
if ENV not in ('development', 'staging', 'production'):
raise ValueError(
f'Invalid ENV value: "{ENV}". '
f'Must be: development, staging, or production'
)
print(f'Running in {ENV} mode')
# Usage:
# ENV=development python agent.py -> dev settings
# ENV=staging python agent.py -> staging settings
# ENV=production python agent.py -> prod settings
# python agent.py -> defaults to developmentClassi di configurazione per ambiente
Definisca una classe di configurazione di base e delle sottoclassi per ogni ambiente. Ogni sottoclasse sostituisce i valori che differiscono. Questo approccio è più leggibile e garantisce una maggiore sicurezza dei tipi rispetto a un grande dizionario di condizioni.
import os
class BaseConfig:
OPENAI_API_KEY: str = os.environ.get('OPENAI_API_KEY', '')
MAX_STEPS: int = 20
LOG_LEVEL: str = 'INFO'
CACHE_ENABLED: bool = True
CACHE_TTL_SECONDS: int = 3600
class DevelopmentConfig(BaseConfig):
MODEL: str = 'gpt-4o-mini' # cheaper in dev
LOG_LEVEL: str = 'DEBUG' # verbose logging in dev
CACHE_ENABLED: bool = False # fresh results in dev
MAX_STEPS: int = 10 # shorter loops in dev
class StagingConfig(BaseConfig):
MODEL: str = 'gpt-4o-mini'
LOG_LEVEL: str = 'INFO'
MAX_STEPS: int = 20
class ProductionConfig(BaseConfig):
MODEL: str = 'gpt-4o' # best quality in prod
LOG_LEVEL: str = 'WARNING' # less noise in prod
MAX_STEPS: int = 30 # more steps allowed in prod
if __name__ == '__main__':
for cls in (DevelopmentConfig, StagingConfig, ProductionConfig):
c = cls()
print(f'{cls.__name__}: model={c.MODEL} log_level={c.LOG_LEVEL} max_steps={c.MAX_STEPS} cache={c.CACHE_ENABLED}')
Factory di configurazione: selezionare il profilo corretto
Una funzione factory di configurazione legge la variabile ENV e restituisce la classe di configurazione appropriata. Questa singola funzione è l'unico punto in cui viene gestita la logica di selezione dell'ambiente.
import os
def get_config():
env = os.getenv('ENV', 'development').lower()
configs = {
'development': DevelopmentConfig,
'staging': StagingConfig,
'production': ProductionConfig
}
config_class = configs.get(env)
if not config_class:
raise ValueError(f'Unknown environment: {env}')
return config_class()
# Usage throughout your agent:
config = get_config()
print(f'Model: {config.MODEL}')
print(f'Max steps: {config.MAX_STEPS}')
print(f'Log level: {config.LOG_LEVEL}')
# All code uses config.MODEL, config.LOG_LEVEL etc.
# Switching environments requires only changing ENV variablePydantic Settings per una configurazione tipizzata
pydantic-settings offre un metodo potente e sicuro rispetto ai tipi per definire la configurazione. Legge automaticamente le variabili d'ambiente, convalida i tipi e può caricare i dati dai file .env. Lo installi con pip install pydantic-settings.
# pip install pydantic-settings
from pydantic_settings import BaseSettings
from pydantic import Field
from typing import Literal
class AgentSettings(BaseSettings):
# Required fields — raise error if not set
openai_api_key: str
search_api_key: str
# Optional with defaults
env: Literal['development', 'staging', 'production'] = 'development'
model: str = 'gpt-4o-mini'
max_steps: int = Field(default=20, ge=1, le=100) # validated range
log_level: str = 'INFO'
cache_enabled: bool = True
cache_ttl_seconds: int = Field(default=3600, ge=60)
class Config:
env_file = '.env'
case_sensitive = False # OPENAI_API_KEY -> openai_api_key
# settings = AgentSettings() # raises ValidationError if required vars missingPydantic Settings con override specifici per l'ambiente
Combini Pydantic Settings con proprietà calcolate per applicare valori predefiniti specifici dell'ambiente, che possono comunque essere sovrascritti dalle variabili d'ambiente.
from pydantic_settings import BaseSettings
from pydantic import model_validator
import os
class AgentSettings(BaseSettings):
openai_api_key: str
env: str = 'development'
model: str = ''
log_level: str = ''
max_steps: int = 0
@model_validator(mode='after')
def apply_env_defaults(self) -> 'AgentSettings':
env_defaults = {
'development': {'model': 'gpt-4o-mini', 'log_level': 'DEBUG', 'max_steps': 10},
'staging': {'model': 'gpt-4o-mini', 'log_level': 'INFO', 'max_steps': 20},
'production': {'model': 'gpt-4o', 'log_level': 'WARNING', 'max_steps': 30}
}
defaults = env_defaults.get(self.env, env_defaults['development'])
if not self.model: self.model = defaults['model']
if not self.log_level: self.log_level = defaults['log_level']
if not self.max_steps: self.max_steps = defaults['max_steps']
return self
class Config:
env_file = '.env'Feature flag per ambiente
Utilizzi i profili di configurazione per abilitare o disabilitare le funzionalità in base all'ambiente. Ad esempio, abiliti l'interfaccia di debug solo nello sviluppo, utilizzi i pagamenti reali solo in produzione e punti ai servizi sandbox nell'ambiente di staging.
import os
class AgentFeatureFlags:
env = os.getenv('ENV', 'development')
# Enable memory persistence (requires DB)
MEMORY_ENABLED: bool = env in ('staging', 'production')
# Use real payment processing
REAL_PAYMENTS: bool = env == 'production'
# Enable verbose step-by-step output
VERBOSE_STEPS: bool = env == 'development'
# Use cheap model for unit test runs
FORCE_MINI_MODEL: bool = os.getenv('CI') == 'true'
flags = AgentFeatureFlags()
print(f'Memory: {flags.MEMORY_ENABLED}')
print(f'Verbose: {flags.VERBOSE_STEPS}')
print(f'Payments: {flags.REAL_PAYMENTS}')Convalidare la configurazione all'avvio
Convalidi tutta la configurazione all'avvio e stampi un riepilogo, così gli operatori possono verificare che l'agente sia configurato correttamente prima che inizi l'elaborazione. In questo modo evita configurazioni errate non rilevate in produzione.
import os
import sys
def validate_and_print_config(config) -> None:
print(f'=== Agent Configuration ===')
print(f'Environment : {config.env}')
print(f'Model : {config.model}')
print(f'Max steps : {config.max_steps}')
print(f'Log level : {config.log_level}')
print(f'Cache : {"enabled" if config.cache_enabled else "disabled"}')
print(f'OpenAI key : ...{config.openai_api_key[-4:]}')
print('===========================')
# Critical validations
if config.env == 'production' and config.log_level == 'DEBUG':
print('WARNING: DEBUG logging in production exposes sensitive data!')
if not config.openai_api_key:
print('FATAL: OPENAI_API_KEY not set')
sys.exit(1)
print('Configuration validated.')
if __name__ == '__main__':
from types import SimpleNamespace
demo_config = SimpleNamespace(
env='development', model='gpt-4o-mini', max_steps=10,
log_level='DEBUG', cache_enabled=False, openai_api_key='sk-demo-1234'
)
validate_and_print_config(demo_config)
Sovrascrivere i valori di configurazione per ambiente
Nelle pipeline CI/CD, sovrascriva valori di configurazione specifici senza modificare l'intero profilo. Passi singole variabili insieme alla variabile ENV per personalizzare le impostazioni di una distribuzione specifica.
# Staging deployment with custom model override:
# ENV=staging AGENT_MODEL=gpt-4o python agent.py
# Production with reduced max_steps for cost control:
# ENV=production AGENT_MAX_STEPS=15 python agent.py
# CI test run — use production profile but with cheap model:
# ENV=production AGENT_MODEL=gpt-4o-mini CI=true python agent.py
# The config class reads ENV first for the profile,
# then individual overrides take precedence:
import os
env = os.getenv('ENV', 'development')
config = get_config() # loads base profile for env
# Individual overrides applied on top:
if os.getenv('AGENT_MODEL'):
config.MODEL = os.getenv('AGENT_MODEL')
if os.getenv('AGENT_MAX_STEPS'):
config.MAX_STEPS = int(os.getenv('AGENT_MAX_STEPS'))
print(f'Final model: {config.MODEL}')Documentare i profili di configurazione per il team
Documenti chiaramente i profili di configurazione, nei commenti del codice, nel README o in entrambi. I nuovi sviluppatori devono comprendere cosa cambia tra gli ambienti per poter distribuire l'applicazione con sicurezza.
# config_profiles.py — Configuration per environment
#
# | Setting | development | staging | production |
# |----------------|----------------|----------------|-------------|
# | MODEL | gpt-4o-mini | gpt-4o-mini | gpt-4o |
# | MAX_STEPS | 10 | 20 | 30 |
# | LOG_LEVEL | DEBUG | INFO | WARNING |
# | CACHE_ENABLED | False | True | True |
# | MEMORY_DB | SQLite (local) | PostgreSQL | PostgreSQL |
#
# To switch environments:
# ENV=staging python agent.py
#
# To override a single setting:
# ENV=production AGENT_MAX_STEPS=15 python agent.py
print('Config profile table documents all per-environment differences')Configurazione nei test: profilo di test obbligatorio
I test devono essere eseguiti sempre con una configurazione di test specifica, mai con le impostazioni di produzione. Crei una fixture di configurazione per i test che applichi le impostazioni appropriate e impedisca qualsiasi chiamata accidentale alle API di produzione.
import os
import pytest
@pytest.fixture(autouse=True)
def test_environment(monkeypatch):
'Force test configuration for all tests'
monkeypatch.setenv('ENV', 'test')
monkeypatch.setenv('AGENT_MODEL', 'gpt-4o-mini')
monkeypatch.setenv('AGENT_MAX_STEPS', '5') # short loops in tests
monkeypatch.setenv('LOG_LEVEL', 'DEBUG')
monkeypatch.setenv('CACHE_ENABLED', 'false')
# Use a fake API key — tests should mock all LLM calls
monkeypatch.setenv('OPENAI_API_KEY', 'test-key-not-real')
# This fixture runs before every test automatically
# Tests cannot accidentally use production settingsVerifica delle conoscenze: profili di configurazione
Verifichi la Sua comprensione dei profili di configurazione specifici per l'ambiente.
Riepilogo: profili di configurazione per sviluppo e produzione
Ora dispone di una strategia completa per la gestione della configurazione degli agenti nei diversi ambienti:
- Utilizzare una variabile
ENVper identificare il contesto di distribuzione - Definire classi di configurazione per ogni ambiente con valori predefiniti appropriati
- Utilizzare una factory di configurazione per selezionare automaticamente il profilo corretto
- Utilizzare
pydantic-settingsper una configurazione tipizzata e convalidata - Utilizzare i feature flag per abilitare o disabilitare le funzionalità in base all'ambiente
- Convalidare e stampare la configurazione all'avvio, così gli operatori possono verificarne le impostazioni
- Imporre una configurazione di test nelle fixture di pytest per impedire le chiamate alla produzione
Una buona gestione della configurazione consente di distribuire in sicurezza la stessa base di codice negli ambienti di sviluppo, staging e produzione.
Domande Frequenti
La lezione «Profili di configurazione per sviluppo e produzione» è gratuita?
Sì — il testo completo di «Profili di configurazione per sviluppo e produzione» è 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 «Profili di configurazione per sviluppo e produzione»?
Configurazioni specifiche per l’ambiente, feature flag e deployment graduali 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 4 di 4.
Quanto tempo richiede la lezione «Profili di configurazione per sviluppo e produzione»?
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