0Pricing
AI Agents · 강의

에이전트를 위한 환경 변수

os.environ, os.getenv()를 알아보고 소스 코드에 비밀 정보를 절대 하드코딩하면 안 되는 이유를 배웁니다.

에이전트를 위한 환경 변수은(는) CoddyKit의 무료 AI Agents 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 AI Agents 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. AI Agents 강의에는 총 4개의 강의가 포함되어 있습니다.

API 키를 소스 코드에 직접 입력하면 안 되는 이유

API 키를 소스 코드에 직접 입력하는 것은 가장 흔하고 비용이 큰 보안 실수 중 하나입니다. 버전 관리에 커밋된 키는 repository에 접근할 수 있는 모든 사람에게 보입니다. 여기에는 향후 기여자, CI 시스템, 온라인에서 저장소를 발견한 사람까지 포함됩니다.

Git 기록의 문제

나중에 코드에서 직접 입력한 키를 삭제하더라도 Git 기록에는 남아 있습니다. repository를 복제한 사람은 누구나 git log 또는 git show를 실행하여 키를 찾을 수 있습니다. 키는 버전 관리에 절대 들어가서는 안 됩니다.

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[]과 os.getenv() 비교

환경 변수를 읽는 방법은 두 가지입니다. os.environ['KEY']은 변수가 없으면 KeyError를 발생시키므로 필수 키에 유용합니다. os.getenv('KEY', default)는 값이 없으면 기본값을 반환하므로 선택적 설정에 유용합니다.

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}')

시작 시 필수 환경 변수 검증하기

시작할 때 모든 필수 환경 변수를 확인하고 명확한 오류 메시지와 함께 즉시 실패하게 하는 것이 좋습니다. 이렇게 하면 키가 없을 때 에이전트 반복문 내부 깊숙한 곳에서 디버깅하기 어려운 실행 시간 오류가 발생하는 것을 방지할 수 있습니다.

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()

12-Factor App 원칙

12-Factor App 방법론은 현대 소프트웨어의 모범 사례를 정의합니다. 요소 III: 설정을 환경에 저장하십시오. 배포 환경(개발, 스테이징, 프로덕션)에 따라 달라지는 모든 것(API 키, URL, 기능 플래그)은 코드가 아니라 환경 변수에서 가져와야 합니다.

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'])

셸에서 환경 변수 설정하기

export(Mac/Linux) 또는 set(Windows)을 사용하여 터미널 세션에서 환경 변수를 설정하십시오. 해당 세션에서 실행하는 모든 프로그램에서 이 변수를 사용할 수 있습니다.

# 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')

코드 주석에 필수 변수 나열하기

에이전트에 필요한 환경 변수를 소스 코드에 직접 문서화하십시오. 새 개발자는 에이전트 파일의 맨 위를 읽고 정확히 무엇을 구성해야 하는지 알 수 있어야 합니다.

# 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')

중첩된 설정에 안전하게 접근하기

설정 옵션이 많은 에이전트라면 모든 환경 변수를 한곳에서 읽고 검증하는 설정 클래스를 구현하십시오. 이렇게 하면 검증을 한곳으로 모으고 나머지 코드가 더 깔끔해집니다.

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}')

로그에서 키 마스킹하기

원본 API 키를 로그에 절대 기록하지 마십시오. 디버깅을 위해 설정을 기록해야 한다면 마지막 4자를 제외한 모든 부분을 마스킹하십시오. 키가 로드되었다는 것만 확인하면서 키 자체의 노출은 막을 수 있습니다.

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-mini

Docker와 지속적 통합(CI)의 환경 변수

Docker에서는 -e 플래그 또는 --env-file을 사용하여 환경 변수를 전달하십시오. GitHub Actions에서는 보안 비밀로 저장하고 워크플로 YAML에서 참조하십시오. 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')

키가 노출되었을 때 해야 할 일

공개 또는 공유 repository에 API 키를 실수로 커밋했다면 즉시 조치하십시오. 키가 통제 범위를 벗어나는 순간 노출되었다고 간주하십시오. 봇은 커밋 후 몇 초 안에 GitHub에서 키를 검색합니다.

# 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.')

지식 확인: 환경 변수

에이전트의 비밀 정보 관리에 환경 변수를 사용하는 방법에 대한 이해도를 확인하십시오.

복습: 에이전트의 환경 변수

이제 에이전트의 비밀 정보 관리에 올바른 접근 방식을 이해했습니다:

  • API 키를 소스 코드에 직접 입력하지 마십시오. 키는 Git 기록에 영원히 남습니다
  • 필수 변수에는 os.environ['KEY']을, 선택적 변수에는 os.getenv('KEY', default)를 사용하십시오
  • 시작할 때 모든 필수 변수를 명확한 오류 메시지와 함께 검증하십시오
  • 코드 주석과 .env.example에 필수 변수를 문서화하십시오
  • 로그에서 키를 마스킹하고 마지막 4자만 표시하십시오
  • Docker에서는 실행 시 비밀 정보를 주입하고, 지속적 통합 환경에서는 GitHub의 보안 비밀 기능을 사용하십시오
  • 키가 노출되었다면 먼저 폐기한 다음 모든 곳에서 교체하십시오

자주 묻는 질문

“에이전트를 위한 환경 변수” 강의는 무료인가요?

네 — “에이전트를 위한 환경 변수” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 AI Agents 강의 전체를 잠금 해제할 수 있습니다. AI Agents 강의에는 총 4개의 강의가 포함되어 있습니다.

“에이전트를 위한 환경 변수”에서 뭘 배우나요?

os.environ, os.getenv()를 알아보고 소스 코드에 비밀 정보를 절대 하드코딩하면 안 되는 이유를 배웁니다. 브라우저에서 직접 실행하는 실습 코드로 AI Agents을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

AI Agents을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 AI Agents은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.

“에이전트를 위한 환경 변수” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 AI Agents 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 AI Agents 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

  1. 에이전트를 위한 환경 변수
  2. .env 파일 및 python-dotenv
  3. 비밀 정보 교체 및 보안
  4. 개발 및 운영 환경 구성 프로필
← AI Agents(으)로 돌아가기