개발 및 운영 환경 구성 프로필
환경별 구성, 기능 플래그, 단계적 배포를 다룹니다.
개발 및 운영 환경 구성 프로필은(는) CoddyKit의 무료 AI Agents 강의입니다. 이것은 4개 중 4번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 AI Agents 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. AI Agents 강의에는 총 4개의 강의가 포함되어 있습니다.
Config 프로필이 중요한 이유
운영 에이전트와 개발 에이전트는 서로 다르게 동작해야 합니다. 로그 기록 수준, 모델 등급(비용과 품질), 데이터베이스, 요청률 제한이 각각 달라야 합니다. 구성 프로필을 사용하면 이 작업을 자동화할 수 있으며, 환경 변수 하나로 모든 설정을 한 번에 전환할 수 있습니다.
ENV 변수로 환경 감지
일반적인 패턴은 현재 배포 환경을 식별하는 ENV(또는 ENVIRONMENT) 변수를 읽는 것입니다. 그런 다음 이 값을 기준으로 적절한 구성 프로필을 선택합니다.
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 development환경별 Config 클래스
기본 구성 클래스와 각 환경에 해당하는 하위 클래스를 정의합니다. 각 하위 클래스에서는 서로 다른 값만 재정의합니다. 이 방식은 조건문으로 구성된 큰 사전보다 읽기 쉽고 타입 안정성이 높습니다.
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}')
Config 팩토리: 올바른 프로필 선택
Config 팩토리 함수는 ENV 변수를 읽고 적절한 구성 클래스를 반환합니다. 환경 전환 로직을 아는 곳을 이 하나의 함수로 제한할 수 있습니다.
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 variable타입이 지정된 구성을 위한 Pydantic Settings
pydantic-settings는 구성을 정의할 수 있는 강력하고 타입 안정적인 방법을 제공합니다. 환경 변수를 자동으로 읽고, 타입을 검증하며, .env 파일에서 값을 불러올 수 있습니다. 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 missing환경별 재정의가 적용된 Pydantic Settings
Pydantic Settings를 계산된 속성과 결합하면 환경별 기본값을 적용하면서도 환경 변수로 해당 값을 재정의할 수 있습니다.
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'환경별 기능 플래그
구성 프로필을 사용하여 환경별로 기능을 활성화하거나 비활성화합니다. 예를 들어 개발 환경에서만 디버그 UI를 활성화하고, 운영 환경에서만 실제 결제를 사용하며, 스테이징 환경에서는 샌드박스 서비스로 연결할 수 있습니다.
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}')시작 시 구성 검증
시작할 때 모든 구성을 검증하고 요약 정보를 출력하여 운영자가 에이전트가 처리를 시작하기 전에 올바르게 구성되었는지 확인할 수 있도록 합니다. 이를 통해 운영 환경에서 조용히 잘못 구성되는 문제를 방지할 수 있습니다.
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)
환경별 Config 값 재정의
CI/CD 배포 과정에서는 전체 프로필을 변경하지 않고 특정 구성 값만 재정의할 수 있습니다. 특정 배포에 맞게 설정을 사용자 지정하려면 ENV 변수와 함께 개별 변수를 전달합니다.
# 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}')팀원을 위한 Config 프로필 문서화
코드 주석이나 README 또는 둘 다에 구성 프로필을 명확하게 문서화합니다. 새 개발자는 자신 있게 배포할 수 있도록 환경마다 무엇이 달라지는지 이해해야 합니다.
# 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: 강제 테스트 프로필
테스트는 항상 특정 테스트 구성을 사용해야 하며, 운영 설정을 사용해서는 안 됩니다. 적절한 설정을 적용하고 실수로 운영 API를 호출하지 않도록 방지하는 테스트 구성 fixture를 만듭니다.
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 settings지식 확인: 구성 프로필
환경별 구성 프로필에 대한 이해도를 확인합니다.
복습: 개발 및 운영을 위한 구성 프로필
이제 여러 환경의 에이전트를 위한 완전한 구성 관리 전략을 갖추었습니다:
ENV변수를 사용하여 배포 환경 식별- 적절한 기본값을 사용하는 환경별 구성 클래스 정의
- Config 팩토리를 사용하여 올바른 프로필 자동 선택
- 타입이 안전하고 검증 가능한 구성을 위해
pydantic-settings사용 - 기능 플래그를 사용하여 환경별 기능 활성화 또는 비활성화
- 시작할 때 구성을 검증하고 출력하여 운영자가 설정을 확인할 수 있도록 함
- 운영 호출을 방지하도록 pytest fixture에서 테스트 구성 강제
우수한 구성 관리는 동일한 코드베이스를 개발, 스테이징, 운영 환경에 안전하게 배포할 수 있도록 해 줍니다.
자주 묻는 질문
“개발 및 운영 환경 구성 프로필” 강의는 무료인가요?
네 — “개발 및 운영 환경 구성 프로필” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 AI Agents 강의 전체를 잠금 해제할 수 있습니다. AI Agents 강의에는 총 4개의 강의가 포함되어 있습니다.
“개발 및 운영 환경 구성 프로필”에서 뭘 배우나요?
환경별 구성, 기능 플래그, 단계적 배포를 다룹니다. 브라우저에서 직접 실행하는 실습 코드로 AI Agents을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.
AI Agents을(를) 시작하는 데 경험이 필요한가요?
사전 경험은 필요하지 않습니다. CoddyKit의 AI Agents은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 4번째 강의입니다.
“개발 및 운영 환경 구성 프로필” 강의는 얼마나 걸리나요?
대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.
이 AI Agents 강의에서 코드를 작성하고 실행할 수 있나요?
네. 모든 AI Agents 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.
이 강의의 모든 강의
- 에이전트를 위한 환경 변수
- .env 파일 및 python-dotenv
- 비밀 정보 교체 및 보안
- 개발 및 운영 환경 구성 프로필