agent-env

Environment configuration management for AI agents. A standardized format for managing model settings, tool permissions, memory backends, safety controls, and rate limits across agent deployments.

The Problem

When deploying AI agents, configuration is scattered:

• Model selection in one place
• API keys in environment variables
• Tool permissions in code
• Rate limits in config files
• Safety settings wherever they fit

Different environments (dev, staging, prod) have different requirements, leading to config drift and deployment issues. There's no standard way to:

• Define what an agent is allowed to do
• Ensure consistent configuration across environments
• Validate configuration before deployment
• Compare configuration between environments

The Solution

agent-env provides a single, validated configuration file for AI agents:

version: "1.0"
name: my-agent

model:
  provider: anthropic
  model: claude-3-5-sonnet-20241022
  temperature: 0.7
  maxTokens: 4096

tools:
  - name: web_search
    enabled: true
    permissions:
      read: true
      network: true
  - name: file_write
    enabled: false
    permissions:
      write: true

memory:
  backend: redis
  connectionString: ${REDIS_URL}
  maxEntries: 1000

safety:
  contentFilter: true
  requireApproval:
    actions: [file_write, shell_exec]
  auditLog: true

rateLimit:
  requestsPerMinute: 30
  tokensPerMinute: 50000

secrets:
  apiKey:
    env: ANTHROPIC_API_KEY
    required: true

Installation

npm install agent-env

CLI Usage

Initialize a new configuration

agent-env init my-agent
# Creates .agentenv with sensible defaults

Validate configuration

agent-env validate .agentenv
# Checks schema, ranges, and consistency

Check environment variables

agent-env check .agentenv
# Verifies all required secrets are set

Compare configurations

agent-env diff .agentenv.dev .agentenv.prod
# Shows what's different between environments

Export to different formats

# Export as environment variables
agent-env export .agentenv --format env

# Export as JSON (secrets redacted)
agent-env export .agentenv --format json

Get specific values

agent-env get .agentenv model.provider
# anthropic

agent-env get .agentenv rateLimit
# {"requestsPerMinute": 30, "tokensPerMinute": 50000}

Programmatic Usage

import { loadConfig, isValidConfig } from 'agent-env';

// Load and resolve configuration
const { config, validation, error } = loadConfig('.agentenv');

if (error) {
  console.error('Config error:', error);
  process.exit(1);
}

// Use resolved values
console.log(`Using model: ${config.provider}/${config.model}`);
console.log(`Temperature: ${config.temperature}`);
console.log(`API Key: ${config.apiKey ? '[SET]' : '[MISSING]'}`);

// Check tool permissions
if (config.tools.get('file_write')?.enabled) {
  console.log('File write enabled');
}

Configuration Schema

Model Configuration

model:
  provider: anthropic|openai|google|azure|bedrock|ollama|together|groq|mistral|cohere|custom
  model: model-name
  temperature: 0.0-2.0
  maxTokens: number
  topP: 0.0-1.0
  frequencyPenalty: number
  presencePenalty: number
  stopSequences: [string]

Tool Configuration

tools:
  - name: tool_name
    enabled: true|false
    permissions:
      read: true|false
      write: true|false
      execute: true|false
      network: true|false
    rateLimit:
      maxCalls: number
      windowMs: number
    timeout: number (ms)

Memory Configuration

memory:
  backend: local|redis|postgres|custom
  connectionString: string (supports ${ENV_VAR})
  maxEntries: number
  ttlMs: number
  embedding:
    provider: string
    model: string
    dimensions: number

Safety Configuration

safety:
  contentFilter: true|false
  maxOutputTokens: number
  blockedTopics: [string]
  requireApproval:
    actions: [string]
    threshold: number
  auditLog: true|false

Rate Limit Configuration

rateLimit:
  requestsPerMinute: number
  tokensPerMinute: number
  tokensPerDay: number
  concurrentRequests: number

Secrets

secrets:
  apiKey:
    env: ENV_VAR_NAME
    required: true|false
    default: fallback_value

Configuration Inheritance

Configurations can extend other files:

# .agentenv.prod
extends: .agentenv.base

model:
  temperature: 0.3  # Override for production

safety:
  auditLog: true  # Enable audit logging in prod

Environment Variable Substitution

Use ${VAR_NAME} syntax for environment variables:

memory:
  connectionString: ${REDIS_URL}

context:
  systemPrompt: ${AGENT_SYSTEM_PROMPT}

Validation

agent-env validates:

• Required fields (version, name, model)
• Type correctness (temperature is a number, etc.)
• Value ranges (temperature 0-2, topP 0-1)
• Consistency (no duplicate tool names)
• Provider/model compatibility warnings
• Secret reference validity

Diff Output

Summary: +2 -1 ~3

[Model]
  ~ model.model: claude-3-5-sonnet-20241022 -> claude-opus-4-20250514
  ~ model.temperature: 0.7 -> 0.3

[Safety]
  + safety.auditLog: true

[Tools]
  + shell_exec (added)
  - debug_mode (removed)
  ~ web_search:
      enabled: true -> false

Integration Examples

With LangChain

import { loadConfig } from 'agent-env';
import { ChatAnthropic } from '@langchain/anthropic';

const { config } = loadConfig('.agentenv');

const model = new ChatAnthropic({
  model: config.model,
  temperature: config.temperature,
  maxTokens: config.maxTokens,
  anthropicApiKey: config.apiKey
});

With Vercel AI SDK

import { loadConfig } from 'agent-env';
import { anthropic } from '@ai-sdk/anthropic';

const { config } = loadConfig('.agentenv');

const model = anthropic(config.model, {
  temperature: config.temperature,
  maxTokens: config.maxTokens
});

CI/CD Validation

# .github/workflows/validate-config.yml
- name: Validate agent config
  run: |
    npx agent-env validate .agentenv
    npx agent-env check .agentenv

License

MIT