Variáveis de ambiente para agentes
os.environ, os.getenv() e por que nunca codificar segredos diretamente no código-fonte.
Variáveis de ambiente para agentes é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.
Por que não codificar chaves de API diretamente?
Codificar chaves de API diretamente no código-fonte é um dos erros de segurança mais comuns e dispendiosos. As chaves confirmadas no controle de versão ficam visíveis para todas as pessoas que têm acesso ao repository — incluindo futuros colaboradores, sistemas de integração contínua e qualquer pessoa que encontre o repositório on-line.
O problema do histórico do git
Mesmo que você exclua posteriormente uma chave codificada no código, ela continuará no histórico do git. Qualquer pessoa que clone o repository e execute git log ou git show poderá encontrá-la. As chaves nunca devem entrar no controle de versão.
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[] versus os.getenv()
Há duas formas de ler variáveis de ambiente. os.environ['KEY'] gera KeyError se a variável estiver ausente — útil para chaves obrigatórias. os.getenv('KEY', default) retorna um valor padrão quando a variável está ausente — útil para configurações opcionais.
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}')Validando variáveis de ambiente obrigatórias na inicialização
Uma prática recomendada é verificar todas as variáveis de ambiente obrigatórias na inicialização e falhar rapidamente com uma mensagem de erro clara. Isso evita falhas difíceis de depurar durante a execução, em pontos profundos de um laço de agente, quando uma chave está ausente.
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()
O princípio do aplicativo de 12 fatores
A metodologia 12-Factor App define práticas recomendadas para softwares modernos. Fator III: armazene a configuração no ambiente. Tudo o que varia entre implantações (desenvolvimento, preparação, produção) — chaves de API, URLs e sinalizadores de funcionalidades — deve vir de variáveis de ambiente, não do código.
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'])Definindo variáveis de ambiente no shell
Defina variáveis de ambiente na sessão do terminal com export (Mac/Linux) ou set (Windows). Elas ficam disponíveis para qualquer programa executado nessa sessão.
# 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')Listando variáveis obrigatórias nos comentários do código
Documente quais variáveis de ambiente seu agente exige diretamente no código-fonte. Uma pessoa desenvolvedora nova deve conseguir ler o início do arquivo do agente e saber exatamente o que precisa configurar.
# 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')Acessando configurações aninhadas com segurança
Para agentes com muitas opções de configuração, crie uma classe de configuração que leia e valide todas as variáveis de ambiente em um único lugar. Isso centraliza a validação e deixa o restante do código mais limpo.
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}')
Mascarando chaves nos registros
Nunca registre chaves de API em texto puro. Se precisar registrar a configuração para fins de depuração, mascare todos os caracteres, exceto os 4 últimos. Assim, você confirma que a chave foi carregada sem expô-la.
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-miniVariáveis de ambiente no Docker e na CI
No Docker, passe variáveis de ambiente com sinalizadores -e ou com um --env-file. No GitHub Actions, armazene-as como segredos e faça referência a elas no YAML do fluxo de trabalho. Nunca as incorpore à imagem do 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')O que fazer quando uma chave é exposta
Se você confirmar acidentalmente uma chave de API em um repository público ou compartilhado, aja imediatamente. Considere que a chave foi comprometida no momento em que saiu do seu controle — bots examinam o GitHub em busca de chaves poucos segundos depois de uma confirmação.
# 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.')Verificação de conhecimento: variáveis de ambiente
Teste sua compreensão das variáveis de ambiente para o gerenciamento de segredos de agentes.
Recapitulação: variáveis de ambiente para agentes
Agora você entende a abordagem correta para o gerenciamento de segredos de agentes:
- Nunca codifique chaves de API diretamente — elas permanecem no histórico do git para sempre
- Use
os.environ['KEY']para variáveis obrigatórias eos.getenv('KEY', default)para variáveis opcionais - Valide todas as variáveis obrigatórias na inicialização com uma mensagem de erro clara
- Documente as variáveis obrigatórias nos comentários do código e em
.env.example - Masque as chaves nos registros — mostre somente os 4 últimos caracteres
- Injete os segredos em tempo de execução no Docker; use os segredos do GitHub na CI
- Se uma chave for exposta: revogue-a primeiro e depois faça a rotação em todos os lugares
Perguntas Frequentes
A aula “Variáveis de ambiente para agentes” é grátis?
Sim — o texto completo de “Variáveis de ambiente para agentes” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.
O que vou aprender em “Variáveis de ambiente para agentes”?
os.environ, os.getenv() e por que nunca codificar segredos diretamente no código-fonte. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar AI Agents?
Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.
Quanto tempo leva a aula “Variáveis de ambiente para agentes”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de AI Agents?
Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Variáveis de ambiente para agentes
- Arquivos .env e python-dotenv
- Rotação e segurança de segredos
- Perfis de configuração para desenvolvimento e produção