Переменные окружения для агентов
os.environ, os.getenv() и объяснение, почему секреты нельзя напрямую записывать в исходный код.
«Переменные окружения для агентов» — бесплатный урок AI Agents на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Agents, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Agents содержит 4 уроков всего.
Почему не следует встраивать ключи API в код?
Жестко заданные непосредственно в исходном коде ключи API — одна из самых распространенных и дорогостоящих ошибок безопасности. Ключи, добавленные в систему контроля версий, видны всем, у кого есть доступ к repository, включая будущих участников разработки, системы непрерывной интеграции и любого, кто найдет репозиторий в сети.
Проблема истории 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 факторами
Методология приложения с 12 факторами определяет лучшие практики для современного программного обеспечения. Фактор III: храните конфигурацию в окружении. Все, что меняется между развертываниями (разработка, промежуточная среда, production), — ключи 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 в журнал. Если для отладки нужно записать конфигурацию, скройте все символы, кроме последних четырех. Это подтверждает, что ключ загружен, не раскрывая его.
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 и непрерывной интеграции
В 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')Что делать при раскрытии ключа
Если Вы случайно добавили ключ API в общедоступный или общий repository, действуйте немедленно. Считайте ключ скомпрометированным в тот момент, когда он покинул Ваш контроль, — боты сканируют 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 - Маскируйте ключи в журналах — показывайте только последние четыре символа
- Передавайте секреты в Docker во время выполнения; используйте секреты GitHub в непрерывной интеграции
- Если ключ раскрыт: сначала отзовите его, затем замените во всех местах
Часто задаваемые вопросы
Урок «Переменные окружения для агентов» бесплатный?
Да — полный текст урока «Переменные окружения для агентов» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Agents, подпишись на CoddyKit PRO. Курс AI Agents содержит 4 уроков всего.
Чему я научусь в уроке «Переменные окружения для агентов»?
os.environ, os.getenv() и объяснение, почему секреты нельзя напрямую записывать в исходный код. Ты практикуешь AI Agents с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать AI Agents?
Предыдущий опыт не требуется. AI Agents на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.
Сколько времени занимает урок «Переменные окружения для агентов»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке AI Agents?
Да. Каждый урок AI Agents включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Переменные окружения для агентов
- Файлы .env и python-dotenv
- Ротация секретов и безопасность
- Профили конфигурации для разработки и продакшена