Environment Variables Reference

Complete reference of all environment variables for configuring AgentField control plane and agents

This page provides a complete reference of environment variables for building and deploying multi-agent systems with AgentField.

Configuration Precedence

All AgentField components follow this configuration order (highest to lowest priority):

  1. Environment variables (overrides everything)
  2. Config file (agentfield.yaml or via AGENTFIELD_CONFIG_FILE)
  3. Code defaults (fallback values)

Quick Find

Common variables you'll need for different scenarios:

ScenarioEssential Variables
Local DevelopmentAGENTFIELD_PORT, AGENTFIELD_STORAGE_MODE=local
Production Control PlaneAGENTFIELD_DATABASE_URL, AGENTFIELD_PORT, AGENTFIELD_STORAGE_MODE=postgres
Containerized AgentsAGENT_CALLBACK_URL, PORT, OPENAI_API_KEY
Python Agent PerformanceAGENTFIELD_ASYNC_MAX_CONCURRENT_EXECUTIONS, UVICORN_WORKERS
Go Agent AI IntegrationOPENAI_API_KEY or OPENROUTER_API_KEY, AI_MODEL

Control Plane Configuration

Essential Server Settings

These variables configure the AgentField control plane server.

VariableTypeDefaultDescription
AGENTFIELD_PORTinteger8080HTTP server port where control plane listens
AGENTFIELD_MODEstringlocalDeployment mode: local (single machine) or cloud (distributed)
AGENTFIELD_CONFIG_FILEstring./config/agentfield.yamlPath to YAML configuration file
AGENTFIELD_HOMEstring~/.agentfieldAgentField home directory for data and config

Example: Basic Setup

AGENTFIELD_PORT=8080
AGENTFIELD_MODE=local

See also: af server command, CLI Configuration

Storage Configuration

Control where AgentField stores its data (agents, executions, workflows).

VariableTypeDefaultDescription
AGENTFIELD_STORAGE_MODEstringlocalStorage backend: local (SQLite+BoltDB), postgres, or cloud
AGENTFIELD_STORAGE_LOCAL_DATABASE_PATHstring./agentfield_local.dbSQLite database file path (local mode only)
AGENTFIELD_STORAGE_LOCAL_KV_STORE_PATHstring./agentfield_local.boltBoltDB key-value store path (local mode only)

Production Recommendation

Use storage-mode=postgres for production deployments. Local storage (SQLite) is intended for development only and doesn't support concurrent access or high availability.

Example: Local Development

AGENTFIELD_STORAGE_MODE=local
AGENTFIELD_STORAGE_LOCAL_DATABASE_PATH=/var/agentfield/data.db

Example: Production PostgreSQL

AGENTFIELD_STORAGE_MODE=postgres
AGENTFIELD_DATABASE_URL="postgres://user:pass@db.example.com:5432/agentfield?sslmode=require"

See also: Production Best Practices, CLI Configuration

PostgreSQL Configuration

For production deployments using PostgreSQL as the storage backend.

Connection String

Three Ways to Set Connection

You can use any of these three variables - they all work the same way:

  • AGENTFIELD_DATABASE_URL (recommended)
  • AGENTFIELD_POSTGRES_URL
  • AGENTFIELD_STORAGE_POSTGRES_URL
VariableTypeRequiredDescription
AGENTFIELD_DATABASE_URLstringYesFull PostgreSQL connection string
Format: postgres://user:pass@host:port/db?sslmode=disable

Example:

AGENTFIELD_DATABASE_URL="postgres://agentfield:password@db.example.com:5432/agentfield?sslmode=require"

Connection Components

Alternatively, configure PostgreSQL using individual components:

VariableTypeDescription
AGENTFIELD_STORAGE_POSTGRES_HOSTstringPostgreSQL server hostname or IP
AGENTFIELD_STORAGE_POSTGRES_PORTintegerPostgreSQL server port (typically 5432)
AGENTFIELD_STORAGE_POSTGRES_DATABASEstringDatabase name
AGENTFIELD_STORAGE_POSTGRES_USERstringPostgreSQL username
AGENTFIELD_STORAGE_POSTGRES_PASSWORDstringPostgreSQL password
AGENTFIELD_STORAGE_POSTGRES_SSLMODEstringSSL mode: disable, require, verify-ca, or verify-full

Example: Component-based Configuration

AGENTFIELD_STORAGE_MODE=postgres
AGENTFIELD_STORAGE_POSTGRES_HOST=db.example.com
AGENTFIELD_STORAGE_POSTGRES_PORT=5432
AGENTFIELD_STORAGE_POSTGRES_DATABASE=agentfield
AGENTFIELD_STORAGE_POSTGRES_USER=agentfield
AGENTFIELD_STORAGE_POSTGRES_PASSWORD=password
AGENTFIELD_STORAGE_POSTGRES_SSLMODE=require

Performance Tuning

VariableTypeDefaultDescription
AGENTFIELD_STORAGE_POSTGRES_MAX_CONNECTIONSinteger25Maximum database connection pool size
AGENTFIELD_STORAGE_POSTGRES_MAX_IDLE_CONNECTIONSinteger5Maximum idle connections to keep open
AGENTFIELD_STORAGE_POSTGRES_CONNECTION_TIMEOUTduration30sTimeout for establishing database connections
AGENTFIELD_STORAGE_POSTGRES_QUERY_TIMEOUTduration30sTimeout for individual database queries

High-Traffic Deployments

For production systems handling 100+ agents or high request volumes, increase connection pool size:

AGENTFIELD_STORAGE_POSTGRES_MAX_CONNECTIONS=100
AGENTFIELD_STORAGE_POSTGRES_MAX_IDLE_CONNECTIONS=25

Duration Format: Use Go duration syntax: 30s, 5m, 1h30m

See also: Production Best Practices

Web UI Configuration

Control the built-in AgentField dashboard.

VariableTypeDefaultDescription
AGENTFIELD_UI_ENABLEDbooleantrueEnable/disable the built-in web dashboard
AGENTFIELD_UI_DIST_PATHstring./web/client/distPath to UI built assets (production mode)

Example: API-Only Deployment (No UI)

AGENTFIELD_UI_ENABLED=false

API & Security Configuration

Configure CORS settings for the AgentField API.

VariableTypeDefaultDescription
AGENTFIELD_API_CORS_ALLOWED_ORIGINSstringhttp://localhost:3000,http://localhost:5173,http://localhost:8080CORS allowed origins (comma-separated)
AGENTFIELD_API_CORS_ALLOWED_METHODSstringGET,POST,PUT,DELETE,OPTIONSCORS allowed HTTP methods (comma-separated)
AGENTFIELD_API_CORS_ALLOWED_HEADERSstringOrigin,Content-Type,Accept,Authorization,X-Requested-WithCORS allowed headers (comma-separated)
AGENTFIELD_API_CORS_EXPOSED_HEADERSstringContent-Length,X-Total-CountCORS exposed headers (comma-separated)
AGENTFIELD_API_CORS_ALLOW_CREDENTIALSbooleantrueAllow cookies and credentials in CORS requests

Example: Production CORS Setup

AGENTFIELD_API_CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
AGENTFIELD_API_CORS_ALLOW_CREDENTIALS=true

Python SDK Configuration

Agent Server Settings

Configure how Python agents expose their HTTP server.

VariableTypeDefaultDescription
AGENT_CALLBACK_URLstring(auto-discovered)Critical for containers: URL where control plane can reach this agent
Example: http://my-agent:8000
PORTinteger8000Agent server port (standard for Railway, Heroku, Render)
AGENTFIELD_AUTO_PORTbooleanfalseEnable automatic port assignment (useful for local multi-agent testing)
AGENTFIELD_AGENT_MAX_CONCURRENT_CALLSinteger(varies)Maximum concurrent calls this agent can handle

Docker/Kubernetes: Must Set AGENT_CALLBACK_URL

When running agents in containers, you MUST set AGENT_CALLBACK_URL to the network-accessible URL so the control plane can call back to your agent.

Common patterns:

  • Docker Compose: http://agent-service-name:8000
  • Kubernetes: http://agent-service.namespace.svc.cluster.local:8000
  • Docker Desktop: http://host.docker.internal:8000 (agent on host, control plane in container)

See Docker Deployment Guide for detailed examples.

Example: Containerized Agent

AGENT_CALLBACK_URL=http://my-agent.internal:8000
PORT=8000

Example: Local Testing with Multiple Agents

AGENTFIELD_AUTO_PORT=true  # Automatically assigns ports 8000, 8001, 8002...

See also: Python SDK Configuration, Docker Networking

Async Execution Performance

Control how Python agents poll the control plane for execution results.

Polling Intervals

VariableTypeDefaultDescription
AGENTFIELD_ASYNC_INITIAL_POLL_INTERVALfloat0.03Initial poll interval in seconds (30ms) - very fast for quick tasks
AGENTFIELD_ASYNC_FAST_POLL_INTERVALfloat0.08Fast poll interval (80ms) - for tasks under 1 second
AGENTFIELD_ASYNC_MEDIUM_POLL_INTERVALfloat0.4Medium poll interval (400ms) - for tasks under 10 seconds
AGENTFIELD_ASYNC_SLOW_POLL_INTERVALfloat1.5Slow poll interval (1.5s) - for long-running tasks
AGENTFIELD_ASYNC_MAX_POLL_INTERVALfloat4.0Maximum poll interval (4s) - prevents excessive polling

Adaptive Polling

The Python SDK uses adaptive polling - it starts fast and gradually slows down if the execution takes longer. These defaults work well for most use cases. Only tune if you have specific latency requirements.

Timeouts

VariableTypeDefaultDescription
AGENTFIELD_ASYNC_MAX_EXECUTION_TIMEOUTfloat21600.0Maximum execution timeout in seconds (6 hours)
AGENTFIELD_ASYNC_DEFAULT_EXECUTION_TIMEOUTfloat7200.0Default execution timeout in seconds (2 hours)
AGENTFIELD_ASYNC_POLLING_TIMEOUTfloat20.0Timeout for individual poll requests (20s)

Concurrency & Batching

VariableTypeDefaultDescription
AGENTFIELD_ASYNC_MAX_CONCURRENT_EXECUTIONSinteger4096Maximum concurrent executions to track
AGENTFIELD_ASYNC_MAX_ACTIVE_POLLSinteger512Maximum concurrent polling operations
AGENTFIELD_ASYNC_CONNECTION_POOL_SIZEinteger64HTTP connection pool size for control plane API calls
AGENTFIELD_ASYNC_BATCH_SIZEinteger100Maximum executions to check in single batch request

Example: High-Performance Agent

AGENTFIELD_ASYNC_MAX_CONCURRENT_EXECUTIONS=8192
AGENTFIELD_ASYNC_CONNECTION_POOL_SIZE=128
AGENTFIELD_ASYNC_BATCH_SIZE=200

See also: Async Execution Architecture, Performance Tuning

Feature Flags

VariableTypeDefaultDescription
AGENTFIELD_ASYNC_ENABLE_ASYNC_EXECUTIONbooleantrueMaster switch for async execution (disable to force sync mode)
AGENTFIELD_ASYNC_ENABLE_BATCH_POLLINGbooleantrueEnable batch status checking (more efficient)
AGENTFIELD_ASYNC_ENABLE_RESULT_CACHINGbooleantrueCache execution results to reduce API calls
AGENTFIELD_ASYNC_FALLBACK_TO_SYNCbooleantrueAutomatically retry as sync request if async fails
AGENTFIELD_ASYNC_ENABLE_EVENT_STREAMbooleanfalseUse Server-Sent Events (SSE) for real-time updates (experimental)

Example: Force Synchronous Mode (for debugging)

AGENTFIELD_ASYNC_ENABLE_ASYNC_EXECUTION=false

Event Streaming (SSE)

Server-Sent Events provide real-time execution updates (experimental feature).

VariableTypeDefaultDescription
AGENTFIELD_ASYNC_EVENT_STREAM_PATHstring/api/ui/v1/executions/eventsSSE endpoint path
AGENTFIELD_ASYNC_EVENT_STREAM_RETRY_BACKOFFfloat3.0Seconds to wait before reconnecting after stream error
AGENTFIELD_ASYNC_COMPLETED_EXECUTION_RETENTION_SECONDSfloat600.0How long to retain completed execution results (10 minutes)

Uvicorn Web Server

Configure the Uvicorn ASGI server that runs Python agents.

VariableTypeDefaultDescription
UVICORN_WORKERSinteger1Number of Uvicorn worker processes (for multi-core scaling)
UVICORN_LOG_LEVELstringwarningUvicorn log level: debug, info, warning, error, critical

Multi-Core Production Setup

To utilize multiple CPU cores, increase worker count:

UVICORN_WORKERS=4  # Use 4 CPU cores

Rule of thumb: Set to (2 × CPU cores) + 1

Example: Production Configuration

UVICORN_WORKERS=4
UVICORN_LOG_LEVEL=info

Python SDK Logging

Control logging verbosity and behavior in the Python SDK.

VariableTypeDefaultDescription
AGENTFIELD_LOG_LEVELstringWARNINGSDK log level: DEBUG, INFO, WARNING, ERROR, SILENT
AGENTFIELD_LOG_TRUNCATEinteger200Maximum log message length before truncation
AGENTFIELD_LOG_PAYLOADSbooleanfalseShow full request/response payloads in logs (very verbose)
AGENTFIELD_LOG_TRACKINGbooleanfalseShow execution tracking messages
AGENTFIELD_LOG_FIREbooleanfalseShow fire-and-forget workflow messages

Example: Verbose Logging for Debugging

AGENTFIELD_LOG_LEVEL=DEBUG
AGENTFIELD_LOG_PAYLOADS=true
AGENTFIELD_LOG_TRACKING=true

Example: Production Logging (Quiet)

AGENTFIELD_LOG_LEVEL=INFO
AGENTFIELD_LOG_TRUNCATE=500

See also: Python SDK Configuration

Go SDK Configuration

AI Integration

Configure AI/LLM providers for Go-based agents.

VariableTypeDefaultDescription
OPENAI_API_KEYstring—OpenAI API key for GPT models
OPENROUTER_API_KEYstring—OpenRouter API key (if set, auto-switches to OpenRouter)
AI_BASE_URLstringhttps://api.openai.com/v1Base URL for OpenAI-compatible API
AI_MODELstringgpt-4oDefault LLM model name

OpenRouter Support

If OPENROUTER_API_KEY is set, the Go SDK automatically uses OpenRouter instead of OpenAI, giving you access to models from Anthropic, Google, Meta, and more.

Example: Using OpenAI

OPENAI_API_KEY=sk-proj-...
AI_MODEL=gpt-4o-mini

Example: Using OpenRouter

OPENROUTER_API_KEY=sk-or-v1-...
AI_MODEL=anthropic/claude-3-5-sonnet-20241022

Example: Using Custom OpenAI-Compatible API

OPENAI_API_KEY=your-key
AI_BASE_URL=https://your-llm-api.com/v1
AI_MODEL=custom-model

See also: Go SDK Overview, Go SDK Agent Package

Docker Deployment Variables

PostgreSQL Container

When running PostgreSQL in Docker (for development or simple deployments).

VariableTypeDefaultDescription
POSTGRES_USERstringagentfieldPostgreSQL superuser username
POSTGRES_PASSWORDstringagentfieldPostgreSQL superuser password
POSTGRES_DBstringagentfieldDefault database name

Example: Docker Compose

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: agentfield
      POSTGRES_PASSWORD: secure_password
      POSTGRES_DB: agentfield

See also: Docker Deployment Guide

Quick Start Examples

1. Local Development (Minimal)

Control Plane:

AGENTFIELD_PORT=8080
AGENTFIELD_MODE=local
AGENTFIELD_STORAGE_MODE=local

Python Agent:

OPENAI_API_KEY=sk-...
AGENTFIELD_LOG_LEVEL=INFO

2. Production (PostgreSQL + Multiple Agents)

Control Plane:

AGENTFIELD_PORT=8080
AGENTFIELD_MODE=cloud
AGENTFIELD_STORAGE_MODE=postgres
AGENTFIELD_DATABASE_URL="postgres://user:pass@db.example.com:5432/agentfield?sslmode=require"
AGENTFIELD_STORAGE_POSTGRES_MAX_CONNECTIONS=100
AGENTFIELD_UI_ENABLED=true
AGENTFIELD_API_CORS_ALLOWED_ORIGINS=https://app.example.com

Python Agent:

AGENT_CALLBACK_URL=http://agent-1.internal:8000
PORT=8000
UVICORN_WORKERS=4
AGENTFIELD_ASYNC_MAX_CONCURRENT_EXECUTIONS=2048
AGENTFIELD_LOG_LEVEL=INFO
OPENAI_API_KEY=sk-...

3. Docker/Kubernetes Deployment

Control Plane:

AGENTFIELD_PORT=8080
AGENTFIELD_STORAGE_MODE=postgres
AGENTFIELD_DATABASE_URL="postgres://user:pass@postgres-service:5432/agentfield?sslmode=disable"

Python Agent:

AGENT_CALLBACK_URL=http://my-agent-service:8000
PORT=8000
AGENTFIELD_LOG_LEVEL=INFO
OPENAI_API_KEY=sk-...

See also: Quick Start Guide, Docker Guide, Production Best Practices

Important Notes

Boolean Values

  • Python SDK: Use string values "true" or "false"
  • Go/Control Plane: Use unquoted boolean true or false
# Python SDK
AGENTFIELD_ASYNC_ENABLE_ASYNC_EXECUTION=true

# Go/Control Plane
AGENTFIELD_UI_ENABLED=true

Duration Format

Use Go duration syntax for timeout and interval values:

  • 30s = 30 seconds
  • 5m = 5 minutes
  • 1h30m = 1 hour 30 minutes
  • 2h = 2 hours

Connection String Aliases

These three variables are equivalent for PostgreSQL connection:

  • AGENTFIELD_DATABASE_URL (recommended)
  • AGENTFIELD_POSTGRES_URL
  • AGENTFIELD_STORAGE_POSTGRES_URL

Container Networking

Critical: Set AGENT_CALLBACK_URL in Containers

When running agents in Docker, Kubernetes, or any containerized environment, you MUST set AGENT_CALLBACK_URL to a network-accessible URL. The control plane cannot use localhost to reach containerized agents.

Common mistakes:

  • ❌ http://localhost:8000 (won't work in containers)
  • ❌ Omitting the variable (auto-discovery fails in containers)
  • ✅ http://agent-service:8000 (Docker Compose service name)
  • ✅ http://agent.namespace.svc.cluster.local:8000 (Kubernetes)

See Docker Deployment Guide for detailed examples.