Zmienne środowiskowe dla agentów
os.environ, os.getenv() oraz powody, dla których nie należy umieszczać sekretów na stałe w kodzie źródłowym.
Zmienne środowiskowe dla agentów to bezpłatna lekcja AI Agents na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Agents, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Agents zawiera 4 lekcji w sumie.
Dlaczego nie wpisywać kluczy API na stałe?
Wpisywanie kluczy API bezpośrednio w kodzie źródłowym to jeden z najczęstszych i najbardziej kosztownych błędów w zakresie bezpieczeństwa. Klucze zatwierdzone w systemie kontroli wersji są widoczne dla wszystkich osób mających dostęp do repozytorium — w tym przyszłych współtwórców, systemów CI i każdego, kto znajdzie repozytorium online.
Problem z historią Git
Nawet jeśli później usuniesz klucz wpisany na stałe z kodu, pozostanie on w historii Git. Każdy, kto sklonuje repozytorium i uruchomi git log lub git show, może go znaleźć. Klucze nigdy nie mogą trafić do systemu kontroli wersji.
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[] a os.getenv()
Istnieją dwa sposoby odczytywania zmiennych środowiskowych. os.environ['KEY'] zgłasza KeyError, jeśli zmiennej brakuje — jest to przydatne w przypadku wymaganych kluczy. os.getenv('KEY', default) zwraca wartość domyślną, jeśli zmiennej brakuje — jest to przydatne w przypadku opcjonalnych ustawień.
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}')Sprawdzanie wymaganych zmiennych środowiskowych przy uruchamianiu
Dobrą praktyką jest sprawdzanie wszystkich wymaganych zmiennych środowiskowych przy uruchamianiu i natychmiastowe przerywanie działania z czytelnym komunikatem o błędzie. Zapobiega to trudnym do zdiagnozowania awariom w czasie działania, występującym głęboko w pętli agenta, gdy brakuje klucza.
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()
Zasada 12-Factor App
Metodologia 12-Factor App definiuje dobre praktyki tworzenia nowoczesnego oprogramowania. Czynnik III: przechowuj konfigurację w środowisku. Wszystko, co różni się między wdrożeniami (programistycznym, testowym i produkcyjnym) — klucze API, adresy URL, flagi funkcji — powinno pochodzić ze zmiennych środowiskowych, a nie z kodu.
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'])Ustawianie zmiennych środowiskowych w powłoce
Ustaw zmienne środowiskowe w sesji terminala za pomocą export (Mac/Linux) lub set (Windows). Są one dostępne dla każdego programu uruchomionego w tej sesji.
# 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')Wymienianie wymaganych zmiennych w komentarzach kodu
Należy bezpośrednio w kodzie źródłowym udokumentować, których zmiennych środowiskowych wymaga agent. Nowy programista powinien móc przeczytać początek pliku agenta i dokładnie wiedzieć, co należy skonfigurować.
# 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')Bezpieczny dostęp do zagnieżdżonej konfiguracji
W przypadku agentów z wieloma opcjami konfiguracji należy utworzyć klasę konfiguracji, która w jednym miejscu odczytuje i sprawdza poprawność wszystkich zmiennych środowiskowych. Centralizuje to walidację i upraszcza pozostałą część kodu.
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}')
Maskowanie kluczy w logach
Nigdy nie należy logować rzeczywistych kluczy API. Jeśli logowanie konfiguracji jest potrzebne do debugowania, należy zamaskować wszystkie znaki oprócz 4 ostatnich. Potwierdza to, że klucz został wczytany, bez ujawniania go.
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-miniZmienne środowiskowe w Dockerze i CI
W Dockerze należy przekazywać zmienne środowiskowe za pomocą flag -e lub pliku --env-file. W GitHub Actions należy przechowywać je jako sekrety i odwoływać się do nich w pliku YAML workflow. Nigdy nie należy wbudowywać ich w obraz Dockera.
# 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')Co zrobić po ujawnieniu klucza
Jeśli przez przypadek zatwierdzisz klucz API w publicznym lub współdzielonym repozytorium, należy natychmiast podjąć działanie. Należy założyć, że klucz został przejęty w chwili, gdy przestał być pod Twoją kontrolą — boty skanują GitHub w poszukiwaniu kluczy w ciągu kilku sekund od zatwierdzenia zmian.
# 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.')Sprawdzenie wiedzy: zmienne środowiskowe
Sprawdź swoją znajomość zmiennych środowiskowych używanych do zarządzania sekretami agentów.
Podsumowanie: zmienne środowiskowe dla agentów
Rozumiesz już prawidłowe podejście do zarządzania sekretami agentów:
- Nigdy nie wpisuj kluczy API na stałe — na zawsze trafiają do historii Git
- Używaj
os.environ['KEY']dla wymaganych zmiennych orazos.getenv('KEY', default)dla opcjonalnych - Sprawdzaj wszystkie wymagane zmienne przy uruchamianiu i wyświetlaj czytelny komunikat o błędzie
- Dokumentuj wymagane zmienne w komentarzach kodu i pliku
.env.example - Maskuj klucze w logach — pokazuj tylko 4 ostatnie znaki
- Wstrzykuj sekrety w czasie działania Dockera; w CI używaj sekretów GitHub
- Jeśli klucz zostanie ujawniony: najpierw go unieważnij, a następnie wszędzie zmień
Często zadawane pytania
Czy lekcja „Zmienne środowiskowe dla agentów” jest bezpłatna?
Tak — pełny tekst „Zmienne środowiskowe dla agentów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Agents, przejdź na CoddyKit PRO. Kurs AI Agents zawiera 4 lekcji w sumie.
Co nauczysz się w „Zmienne środowiskowe dla agentów”?
os.environ, os.getenv() oraz powody, dla których nie należy umieszczać sekretów na stałe w kodzie źródłowym. Ćwiczysz AI Agents z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć AI Agents?
Nie wymagamy żadnego doświadczenia. AI Agents w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.
Ile czasu zajmuje lekcja „Zmienne środowiskowe dla agentów”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji AI Agents?
Tak. Każda lekcja AI Agents zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Zmienne środowiskowe dla agentów
- Pliki .env i python-dotenv
- Rotacja sekretów i bezpieczeństwo
- Profile konfiguracji dla środowisk deweloperskich i produkcyjnych