Perfis de configuração para desenvolvimento e produção
Configurações específicas do ambiente, sinalizadores de funcionalidades e implantações em etapas.
Perfis de configuração para desenvolvimento e produção é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.
Por que os perfis de Config são importantes
Um agente de produção e um agente de desenvolvimento devem se comportar de maneiras diferentes: níveis de registro diferentes, níveis de modelo diferentes (custo versus qualidade), bancos de dados diferentes e limites de taxa diferentes. Os perfis de configuração tornam isso automático — uma variável de ambiente altera todas as configurações de uma só vez.
Detecção do ambiente com a variável ENV
O padrão habitual consiste em ler uma variável ENV (ou ENVIRONMENT) que identifica o contexto de implantação atual. Em seguida, o código seleciona o perfil de configuração apropriado com base nesse valor.
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 developmentClasses de Config por ambiente
Defina uma classe de configuração base e subclasses para cada ambiente. Cada subclasse substitui os valores que forem diferentes. Essa abordagem é mais legível e oferece mais segurança de tipos do que um dicionário grande de condicionais.
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}')
Fábrica de Config: selecionando o perfil correto
Uma função de fábrica de configuração lê a variável ENV e retorna a classe de configuração apropriada. Essa única função é o único lugar que conhece a lógica de alternância de 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 variableConfigurações do Pydantic para configuração tipada
pydantic-settings oferece uma maneira poderosa e segura quanto aos tipos de definir configurações. Ele lê automaticamente as variáveis de ambiente, valida os tipos e pode carregar dados de arquivos .env. Instale-o com 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 missingConfigurações do Pydantic com substituições específicas do ambiente
Combine o Pydantic Settings com propriedades calculadas para aplicar valores padrão específicos do ambiente que ainda possam ser substituídos por variáveis de 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'Sinalizadores de recursos por ambiente
Use perfis de configuração para ativar ou desativar recursos por ambiente. Por exemplo, ative a interface de depuração apenas no desenvolvimento, use pagamentos reais somente em produção e aponte para serviços isolados em ambiente de testes durante a homologação.
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}')Validação da configuração na inicialização
Valide toda a configuração na inicialização e mostre um resumo para que os operadores possam confirmar se o agente está configurado corretamente antes de começar o processamento. Isso evita erros silenciosos de configuração em produção.
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)
Substituindo valores de configuração por ambiente
Em fluxos de CI/CD, substitua valores específicos de configuração sem alterar o perfil inteiro. Passe variáveis individuais junto com a variável ENV para personalizar as configurações de uma implantação específica.
# 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}')Documentando perfis de configuração para a equipe
Documente seus perfis de configuração com clareza — nos comentários do código, no README ou em ambos. Os novos desenvolvedores precisam entender o que muda entre os ambientes para poder implantar com segurança.
# 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')Config em testes: perfil de teste obrigatório
Os testes devem sempre ser executados com uma configuração de teste específica — nunca com configurações de produção. Crie um fixture de configuração de teste que aplique as definições apropriadas e impeça chamadas acidentais às APIs de produção.
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ção de conhecimento: perfis de configuração
Teste sua compreensão sobre os perfis de configuração específicos de cada ambiente.
Recapitulação: perfis de configuração para desenvolvimento e produção
Agora você tem uma estratégia completa de gerenciamento de configuração para agentes em diferentes ambientes:
- Use uma variável
ENVpara identificar o contexto de implantação - Defina classes de configuração por ambiente com valores padrão apropriados
- Use uma fábrica de configuração para selecionar automaticamente o perfil correto
- Use
pydantic-settingspara obter uma configuração segura quanto aos tipos e validada - Use sinalizadores de recursos para ativar ou desativar recursos por ambiente
- Valide e mostre a configuração na inicialização para que os operadores possam verificar as definições
- Force uma configuração de teste nos fixtures do pytest para impedir chamadas de produção
Um bom gerenciamento de configuração é o que permite implantar com segurança a mesma base de código em desenvolvimento, homologação e produção.
Aprenda AI Agents com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 60
- Aulas
- 239
Perguntas Frequentes
A aula “Perfis de configuração para desenvolvimento e produção” é grátis?
Sim — o texto completo de “Perfis de configuração para desenvolvimento e produção” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.
O que vou aprender em “Perfis de configuração para desenvolvimento e produção”?
Configurações específicas do ambiente, sinalizadores de funcionalidades e implantações em etapas. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar AI Agents?
Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Perfis de configuração para desenvolvimento e produção”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de AI Agents?
Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Variáveis de ambiente para agentes
- Arquivos .env e python-dotenv
- Rotação e segurança de segredos
- Perfis de configuração para desenvolvimento e produção