Umgebungsvariablen für Agenten
os.environ, os.getenv() und warum Secrets niemals fest im Quellcode hinterlegt werden sollten.
Umgebungsvariablen für Agenten ist eine kostenlose AI Agents-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des AI Agents-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der AI Agents-Kurs umfasst insgesamt 4 Lektionen.
Warum Sie API-Schlüssel nicht hart codieren sollten
API-Schlüssel direkt im Quellcode zu hinterlegen, ist einer der häufigsten und kostspieligsten Sicherheitsfehler. In die Versionsverwaltung eingecheckte Schlüssel sind für alle sichtbar, die Zugriff auf das Repository haben — einschließlich zukünftiger Mitwirkender, CI-Systeme und aller Personen, die das Repository online finden.
Das Problem mit der Git-Historie
Selbst wenn Sie einen hart codierten Schlüssel später aus Ihrem Code löschen, bleibt er in der Git-Historie erhalten. Jeder, der das Repository klont und git log oder git show ausführt, kann ihn finden. Schlüssel dürfen niemals in die Versionsverwaltung gelangen.
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[] vs os.getenv()
Es gibt zwei Möglichkeiten, Umgebungsvariablen auszulesen. os.environ['KEY'] löst KeyError aus, wenn die Variable fehlt — das ist für erforderliche Schlüssel nützlich. os.getenv('KEY', default) gibt bei fehlender Variable einen Standardwert zurück — das ist für optionale Einstellungen nützlich.
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}')Erforderliche Umgebungsvariablen beim Start validieren
Eine bewährte Vorgehensweise besteht darin, beim Start alle erforderlichen Umgebungsvariablen zu prüfen und bei einem Fehler sofort mit einer eindeutigen Fehlermeldung abzubrechen. So verhindern Sie schwer zu diagnostizierende Laufzeitfehler tief in einer Agentenschleife, wenn ein Schlüssel fehlt.
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()
Das 12-Factor-App-Prinzip
Die 12-Factor-App-Methodik definiert bewährte Vorgehensweisen für moderne Software. Factor III: Konfiguration in der Umgebung speichern. Alles, was sich zwischen Bereitstellungen (Entwicklung, Staging, Produktion) unterscheidet — API-Schlüssel, URLs, Feature-Flags — sollte aus Umgebungsvariablen stammen, nicht aus dem Code.
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'])Umgebungsvariablen in der Shell setzen
Setzen Sie Umgebungsvariablen mit export (Mac/Linux) oder set (Windows) in Ihrer Terminalsitzung. Sie stehen jedem Programm zur Verfügung, das in dieser Sitzung ausgeführt wird.
# 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')Erforderliche Variablen in Codekommentaren auflisten
Dokumentieren Sie direkt im Quellcode, welche Umgebungsvariablen Ihr Agent benötigt. Ein neuer Entwickler sollte am Anfang Ihrer Agentendatei nachlesen können, was genau konfiguriert werden muss.
# 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')Verschachtelte Konfiguration sicher abrufen
Erstellen Sie für Agenten mit vielen Konfigurationsoptionen eine Konfigurationsklasse, die alle Umgebungsvariablen zentral ausliest und validiert. Dadurch wird die Validierung zentralisiert und der übrige Code übersichtlicher.
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}')
Schlüssel in Logs maskieren
Protokollieren Sie niemals API-Schlüssel im Klartext. Wenn Sie zu Debugging-Zwecken die Konfiguration protokollieren müssen, maskieren Sie alle bis auf die letzten 4 Zeichen. So können Sie bestätigen, dass der Schlüssel geladen wurde, ohne ihn offenzulegen.
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-miniUmgebungsvariablen in Docker und CI
Übergeben Sie Umgebungsvariablen in Docker mit -e-Flags oder einer --env-file. Speichern Sie sie in GitHub Actions als Secrets und referenzieren Sie sie in der Workflow-YAML-Datei. Bauen Sie sie niemals in das Docker-Image ein.
# 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')Was tun, wenn ein Schlüssel offengelegt wurde
Wenn Sie versehentlich einen API-Schlüssel in ein öffentliches oder gemeinsam genutztes Repository einchecken, handeln Sie sofort. Gehen Sie davon aus, dass der Schlüssel in dem Moment kompromittiert ist, in dem er Ihre Kontrolle verlässt — Bots durchsuchen GitHub innerhalb weniger Sekunden nach einem Commit nach Schlüsseln.
# 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.')Wissenscheck: Umgebungsvariablen
Testen Sie Ihr Verständnis von Umgebungsvariablen für die Verwaltung von Agenten-Secrets.
Zusammenfassung: Umgebungsvariablen für Agenten
Sie kennen nun den richtigen Ansatz für die Verwaltung von Secrets in Agenten:
- Codieren Sie API-Schlüssel niemals fest — sie bleiben für immer in der Git-Historie
- Verwenden Sie
os.environ['KEY']für erforderliche Variablen undos.getenv('KEY', default)für optionale Variablen - Validieren Sie alle erforderlichen Variablen beim Start mit einer eindeutigen Fehlermeldung
- Dokumentieren Sie erforderliche Variablen in Codekommentaren und in
.env.example - Maskieren Sie Schlüssel in Logs — zeigen Sie nur die letzten 4 Zeichen
- Injizieren Sie Secrets zur Laufzeit in Docker; verwenden Sie GitHub Secrets in CI
- Wenn ein Schlüssel offengelegt wurde: widerrufen Sie ihn zuerst und rotieren Sie ihn anschließend überall
Häufig gestellte Fragen
Ist die Lektion „Umgebungsvariablen für Agenten“ kostenlos?
Ja — der vollständige Text von „Umgebungsvariablen für Agenten“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des AI Agents-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der AI Agents-Kurs umfasst insgesamt 4 Lektionen.
Was lerne ich in „Umgebungsvariablen für Agenten“?
os.environ, os.getenv() und warum Secrets niemals fest im Quellcode hinterlegt werden sollten. Du übst AI Agents mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.
Brauche ich Erfahrung, um AI Agents zu starten?
Keine Vorkenntnisse erforderlich. AI Agents auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.
Wie lange dauert die Lektion „Umgebungsvariablen für Agenten“?
Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.
Kann ich in dieser AI Agents-Lektion Code schreiben und ausführen?
Ja. Jede AI Agents-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.
Alle Lektionen in diesem Kurs
- Umgebungsvariablen für Agenten
- .env-Dateien und python-dotenv
- Rotation und Sicherheit von Secrets
- Konfigurationsprofile für Entwicklung und Produktion