Environment Variables

Overview

Environment variables are used to configure your agent without hardcoding sensitive information. RunAgent provides secure methods for managing environment variables across development and production.

Local Development

Using .env Files

Create a .env file in your project root:

# .env
OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql://localhost/mydb
REDIS_URL=redis://localhost:6379
DEBUG=true
LOG_LEVEL=info

Load in your agent:

from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

# Access variables
api_key = os.getenv("OPENAI_API_KEY")
debug = os.getenv("DEBUG", "false").lower() == "true"

Best Practices

Never commit .env files

# .gitignore
.env
.env.local
.env.*.local

Provide .env.example

# .env.example
OPENAI_API_KEY=your-api-key-here
DATABASE_URL=postgresql://localhost/mydb
DEBUG=false

Validate required variables

required_vars = ["OPENAI_API_KEY", "DATABASE_URL"]
missing = [var for var in required_vars if not os.getenv(var)]

if missing:
    raise ValueError(f"Missing required environment variables: {missing}")

Configuration in runagent.config.json

Dynamic Substitution

Use ${VAR_NAME} syntax for runtime substitution:

{
  "env_vars": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
    "MODEL_NAME": "gpt-4",
    "TEMPERATURE": "${TEMPERATURE:-0.7}"
  }
}

Variable Types

Dynamic variables - Loaded from environment
"API_KEY": "${API_KEY}"
Static values - Hardcoded (non-sensitive only)
"MODEL_VERSION": "v1.0"
With defaults (coming soon)
"TIMEOUT": "${TIMEOUT:-30}"

Production Deployment

Setting Variables

When deploying, set environment variables:

# Local deployment
OPENAI_API_KEY=sk-... runagent deploy . --local

# Cloud deployment (coming soon)
runagent deploy . \
  --env OPENAI_API_KEY=$OPENAI_API_KEY \
  --env DATABASE_URL=$DATABASE_URL

Security Best Practices

Use secret management services
- AWS Secrets Manager
- Google Secret Manager
- Azure Key Vault
- HashiCorp Vault
Rotate keys regularly
- Set expiration reminders
- Use versioned secrets
- Update without downtime
Limit scope
- Use read-only credentials where possible
- Create service-specific API keys
- Apply principle of least privilege

Common Patterns

Configuration Classes

# config.py
import os
from dataclasses import dataclass

@dataclass
class Config:
    openai_api_key: str
    model_name: str = "gpt-4"
    temperature: float = 0.7
    max_tokens: int = 1000
    
    @classmethod
    def from_env(cls):
        return cls(
            openai_api_key=os.environ["OPENAI_API_KEY"],
            model_name=os.getenv("MODEL_NAME", "gpt-4"),
            temperature=float(os.getenv("TEMPERATURE", "0.7")),
            max_tokens=int(os.getenv("MAX_TOKENS", "1000"))
        )

# Usage
config = Config.from_env()

Environment-Specific Settings

# settings.py
import os

ENV = os.getenv("ENVIRONMENT", "development")

CONFIGS = {
    "development": {
        "debug": True,
        "log_level": "DEBUG",
        "cache_enabled": False
    },
    "staging": {
        "debug": False,
        "log_level": "INFO",
        "cache_enabled": True
    },
    "production": {
        "debug": False,
        "log_level": "WARNING",
        "cache_enabled": True
    }
}

settings = CONFIGS[ENV]

Validation

# validate_env.py
import os
import sys

def validate_environment():
    errors = []
    
    # Required variables
    required = {
        "OPENAI_API_KEY": "OpenAI API key",
        "DATABASE_URL": "Database connection string"
    }
    
    for var, description in required.items():
        if not os.getenv(var):
            errors.append(f"Missing {description} ({var})")
    
    # Validate formats
    api_key = os.getenv("OPENAI_API_KEY", "")
    if api_key and not api_key.startswith("sk-"):
        errors.append("Invalid OpenAI API key format")
    
    if errors:
        print("Environment validation failed:")
        for error in errors:
            print(f"  - {error}")
        sys.exit(1)

# Run validation on startup
validate_environment()

Special Variables

RunAgent System Variables

Variable	Description	Default
`RUNAGENT_LOG_LEVEL`	Logging level	`INFO`
`RUNAGENT_TIMEOUT`	Request timeout	`30`
`RUNAGENT_MAX_RETRIES`	Retry attempts	`3`

Framework-Specific

# LangChain
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "..."

# OpenAI
os.environ["OPENAI_API_KEY"] = "..."
os.environ["OPENAI_ORGANIZATION"] = "..."

Troubleshooting

Variable Not Found

# Debug which variables are available
print("Available environment variables:")
for key, value in os.environ.items():
    if key.startswith("RUNAGENT_") or key in ["OPENAI_API_KEY"]:
        print(f"{key}={value[:5]}...")  # Show only first 5 chars

Loading Order

System environment variables
.env file (local development)
RunAgent configuration (deployment)
Runtime overrides

Common Issues

Quotes in .env files

# Wrong
API_KEY="sk-abc123"

# Correct
API_KEY=sk-abc123

Spaces around equals

# Wrong
API_KEY = sk-abc123

# Correct
API_KEY=sk-abc123

Multiline values

# Use quotes for multiline
PROMPT="This is a
multiline prompt"

Reference

API Reference

SDK Reference

CLI Reference

Configuration

Environment Variables

Overview

Local Development

Using .env Files

Best Practices

Configuration in runagent.config.json

Dynamic Substitution

Variable Types

Production Deployment

Setting Variables

Security Best Practices

Common Patterns

Configuration Classes

Environment-Specific Settings

Validation

Special Variables

RunAgent System Variables

Framework-Specific

Troubleshooting

Variable Not Found

Loading Order

Common Issues

See Also

​Overview

​Local Development

​Using .env Files

​Best Practices

​Configuration in runagent.config.json

​Dynamic Substitution

​Variable Types

​Production Deployment

​Setting Variables

​Security Best Practices

​Common Patterns

​Configuration Classes

​Environment-Specific Settings

​Validation

​Special Variables

​RunAgent System Variables

​Framework-Specific

​Troubleshooting

​Variable Not Found

​Loading Order

​Common Issues

​See Also

Overview

Local Development

Using .env Files

Best Practices

Configuration in runagent.config.json

Dynamic Substitution

Variable Types

Production Deployment

Setting Variables

Security Best Practices

Common Patterns

Configuration Classes

Environment-Specific Settings

Validation

Special Variables

RunAgent System Variables

Framework-Specific

Troubleshooting

Variable Not Found

Loading Order

Common Issues

See Also