Skip to content

Configuration Reference

agentomatic logo

Platform, Agent, and Environment Configuration

Agentomatic has two configuration surfaces that deliberately do not silently merge into one another:

  • The generated main.py and agentomatic run consume documented AGENTOMATIC_* deployment variables and pass them as explicit AgentPlatform arguments.
  • PlatformSettings supplies nested provider, embedding, artifact, ingestion, and audit settings to the subsystems that use it. It reads process environment variables and .env files.

Pass explicit AgentPlatform(...) arguments when configuring an application you construct yourself; do not assume that every PlatformSettings field changes every platform constructor argument.

🔀 Configuration Hierarchy

For a PlatformSettings value, process environment variables override .env values, which override built-in defaults. Explicit Python constructor arguments are passed directly to AgentPlatform and therefore take precedence for that specific platform option.

flowchart LR
    A["Explicit Python<br/>AgentPlatform arguments"] --> B["Platform configuration"]
    C["Process environment"] --> D["PlatformSettings"]
    E[".env file"] --> D
    F["Built-in defaults"] --> D
    D --> G["Settings-backed subsystems"]

    style A fill:#fff3e0,stroke:#f57c00
    style C fill:#c8e6c9,stroke:#388e3c
    style E fill:#e1f5fe,stroke:#0288d1
    style F fill:#f3e5f5,stroke:#7b1fa2
Priority Surface Example
1 Explicit platform arguments AgentPlatform(log_level="DEBUG")
2 Process environment export LLM__MODEL=... or export AGENTOMATIC_LOG_LEVEL=DEBUG
3 .env file in project root LLM__MODEL=...
4 (lowest) Built-in defaults "INFO", "mistral:7b", etc.

Production Best Practice

Use environment variables or .env files for deployment-specific values (secrets, URLs, ports). Use Python constructor arguments for structural decisions (middleware toggles, storage backend selection).

⚙️ Platform Constructor Reference

When initializing AgentPlatform.from_folder() (or the direct AgentPlatform() constructor), you can pass the following keyword arguments:

from agentomatic import AgentPlatform
from agentomatic.storage import SQLAlchemyStore

platform = AgentPlatform.from_folder(
    "agents/",
    plugins_dir="plugins/",
    endpoints_dir="endpoints/",
    ingestion_dir="ingestion/",
    # -- Metadata --
    title="My Custom Agent Platform",
    description="Enterprise Assistant APIs",
    version="1.0.0",
    # -- Networking --
    api_prefix="/api/v1",
    package_prefix="",
    cors_origins=["https://dashboard.mycompany.com"],
    # -- Observability --
    log_level="INFO",
    enable_logging=True,
    enable_metrics=True,
    enable_telemetry=True,
    enable_feedback=True,
    # -- Storage --
    store=SQLAlchemyStore("postgresql+asyncpg://user:pass@localhost/db"),
    # -- Security --
    enable_auth=True,
    auth_api_key="sk_live_51hG...",
    enable_rate_limit=True,
    rate_limit_requests=100,
    rate_limit_window=60,
    rate_limit_trust_proxy_headers=True,  # only behind a trusted proxy
    # -- Memory --
    max_history_messages=50,
    summarize_after=30,
    # -- Studio --
    enable_studio=False,
    # -- Production security and operations --
    enable_jwt_auth=True,
    enable_zero_trust=True,
    require_auth_globally=True,
    enable_control_plane=True,
    control_token="ops-secret",
    # -- Tasks, connections, and plugin artifact lifecycle --
    enable_tasks=True,
    task_max_concurrency=8,
    logs_history=True,
    plugin_autoreload=True,
    plugin_autoreload_interval=5.0,
)

Complete Parameter Table

Parameter Type Default Description
agents_dir str \| Path "agents/" Filesystem path to scan for agent packages.
plugins_dir str \| Path "plugins/" Filesystem path to scan for ML plugin packages.
endpoints_dir str \| Path "endpoints/" Filesystem path to scan for custom endpoint packages.
ingestion_dir str \| Path "ingestion/" Filesystem path to scan for ingestion packages.
title str "Agentomatic Platform" Display title shown in Swagger docs (/docs) and Redoc.
description str "Multi-agent API platform..." Description displayed in Swagger UI.
version str "1.0.0" Semantic version string shown in API docs and root.
api_prefix str "/api/v1" Global URL prefix for all agent endpoints.
package_prefix str "" Python import prefix for agent modules. Auto-detected from agents_dir name if empty.
cors_origins list[str] \| None ["*"] Allowed CORS origins. Defaults to allowing all.
log_level str "INFO" Log verbosity: DEBUG, INFO, WARNING, ERROR.
settings PlatformSettings \| None None Optional pre-configured PlatformSettings object.
store BaseStore \| None None Storage backend instance (e.g. MemoryStore, SQLAlchemyStore).
enable_logging bool True Add structured request-logging middleware.
enable_auth bool False Add API-key authentication middleware.
auth_api_key str "" API key token (required when enable_auth=True).
enable_rate_limit bool False Add rate-limiting middleware.
rate_limit_requests int 100 Max requests per window per client IP.
rate_limit_window int 60 Sliding window duration in seconds.
rate_limit_trust_proxy_headers bool False Trust X-Forwarded-For only when a trusted proxy overwrites it.
enable_metrics bool False Mount Prometheus metrics at /metrics.
enable_feedback bool True Enable feedback collection endpoints per agent.
enable_telemetry bool True Auto-configure OpenTelemetry tracing.
enable_studio bool False Mount the Studio debug API and UI at /studio/ and /studio/ui/.
middleware list[tuple] \| None None Custom middleware list: [(MiddlewareCls, {kwargs}), ...].
max_history_messages int 50 Maximum messages loaded into agent context.
summarize_after int 30 Message threshold before auto-summarization kicks in.
stack str \| StackConfig \| None auto-detect Active named stack or explicit stack configuration.
stacks_dir str \| Path "stacks/" Directory containing stack YAML files.
enable_jwt_auth bool False Enable JWT/OAuth2 bearer-token validation.
jwt_config JWTConfig \| None None JWT validation configuration; required with enable_jwt_auth=True.
enable_zero_trust bool False Enforce per-agent security policies.
require_auth_globally bool False Require authenticated claims for every agent request when zero trust is enabled.
enable_control_plane bool False Mount the production control-plane API.
control_token str "" Optional secret required by mutating control-plane operations.
connections list[Any] \| None None Platform-wide database, vector, HTTP, or custom connection definitions.
enable_connections_context bool True Attach the routed agent's connection manager to request.state.connections.
enable_tasks bool True Enable the durable task/execution subsystem.
task_store TaskStore \| None None Optional durable task-store implementation.
task_max_concurrency int 8 Maximum concurrent task workers.
logs_history bool False Persist invocation history when a durable store is available.
allow_logsllm_analysis bool False Expose opt-in LLM analysis over persisted invocation logs.
plugin_autoreload bool \| None settings / False Watch artifact promotions and reload registered ML plugins safely.
plugin_autoreload_interval float \| None settings / 5.0 Seconds between artifact-pointer checks; must be greater than zero.

🌐 Environment Variables Reference

The generated project and agentomatic run expose deployment configuration through direct AGENTOMATIC_* variables. PlatformSettings is a separate, nested model used by the subsystems described below.

Direct AGENTOMATIC_ Variables

These are the deployment variables consumed by the generated main.py and by agentomatic run. For an explicit AgentPlatform(...) constructor, pass the corresponding Python argument instead. The CLI flags take precedence for the directory, host, port, and stack values passed to agentomatic run.

Variable Maps To Default Description
AGENTOMATIC_HOST / AGENTOMATIC_PORT main.py __main__ 0.0.0.0 / 8000 Server bind values; agentomatic run exposes --host / --port
AGENTOMATIC_AGENTS_DIR agents_dir agents/ Agent package directory in generated main.py
AGENTOMATIC_PLUGINS_DIR / AGENTOMATIC_ENDPOINTS_DIR / AGENTOMATIC_INGESTION_DIR component directories plugins/ / endpoints/ / ingestion/ Auto-discovery directories in generated main.py
AGENTOMATIC_STACKS_DIR / AGENTOMATIC_STACK stack discovery / active stack stacks/ / unset Stack YAML directory and selected stack
AGENTOMATIC_TITLE / AGENTOMATIC_LOG_LEVEL title / log_level project title / INFO Platform title and log verbosity
AGENTOMATIC_ENABLE_STUDIO / AGENTOMATIC_ENABLE_METRICS feature switches true / true Mount Studio and metrics
AGENTOMATIC_ENABLE_AUTH / AGENTOMATIC_API_KEY API-key authentication false / empty Enable API-key auth and set its secret
AGENTOMATIC_ENABLE_JWT / AGENTOMATIC_REQUIRE_AUTH JWT / global auth false / false Enable JWT and require credentials globally
AGENTOMATIC_ENABLE_CONTROL_PLANE / AGENTOMATIC_CONTROL_TOKEN control plane true / empty in generated main.py; false in CLI fallback Mount control-plane routes and protect mutations
AGENTOMATIC_ENABLE_RATE_LIMIT / AGENTOMATIC_RATE_LIMIT_TRUST_PROXY_HEADERS rate limiting false / false Enable the limiter; trust forwarded client IPs only behind a trusted proxy
AGENTOMATIC_LOGS_HISTORY / DATABASE_URL invocation history / storage false / empty Persist logs and threads using an async SQLAlchemy URL
AGENTOMATIC_EPHEMERAL_THREADS thread-store fallback true With no store=, MEMORY connection or database URL, keep conversation threads in a bounded in-memory store (1000 threads, lost on restart) so Studio chat and /chat history work out of the box. 0 disables it — thread routes then answer 400 Thread storage not configured
AGENTOMATIC_ARTIFACT_ROOT artifact_root .local/artifacts Versioned plugin/model artifact bundles
AGENTOMATIC_PLUGIN_AUTORELOAD plugin_autoreload false Watch the promoted artifact version and reload plugins safely
AGENTOMATIC_PLUGIN_AUTORELOAD_INTERVAL plugin_autoreload_interval 5 Seconds between artifact-pointer checks
AGENTOMATIC_RUNS_ROOT runs_root .local/runs Scratch directory for pipeline/task outputs
AGENTOMATIC_TASK_EVENT_LOG task-event replay backend memory none disables replay; any registered provider name also works
AGENTOMATIC_TASK_EVENTS_PER_TASK / AGENTOMATIC_TASK_EVENT_TASKS / AGENTOMATIC_TASK_EVENT_MAX_MB task-event retention 512 / 1024 / 32 Caps how much history /tasks/{id}/events can replay. The MB ceiling is what protects a container's memory limit
AGENTOMATIC_STREAM_REPLAY /invoke/stream frame retention true 0 streams without retaining anything
AGENTOMATIC_STREAM_FRAMES / AGENTOMATIC_STREAM_COUNT / AGENTOMATIC_STREAM_MAX_MB stream retention 512 / 256 / 64 Caps what GET /invoke/stream/{id} can replay
AGENTOMATIC_AUDIT_LOG audit_log "" (disabled) JSONL op-audit sink path (non-PII metadata only)
AGENTOMATIC_AUDIT_HASH_KEY — API key or process-local key HMAC key for audit correlation references
AGENTOMATIC_CHUNK_SIZE_TOKENS chunk_size_tokens 1200 Default ingestion chunk size
AGENTOMATIC_CHUNK_OVERLAP_TOKENS chunk_overlap_tokens 150 Default ingestion chunk overlap
AGENTOMATIC_MIN_QUALITY_SCORE min_quality_score 0.70 Ingestion quality warning threshold

PlatformSettings Nested Variables

The PlatformSettings Pydantic model supports nested environment variables using double-underscore (__) as delimiter:

# PlatformSettings uses no prefix: nested values use __.
# The generated main.py separately consumes the AGENTOMATIC_* variables above.
# LLM provider configuration
export LLM__PROVIDER=openai
export LLM__MODEL=gpt-4o
export LLM__TEMPERATURE=0.1
export LLM__MAX_TOKENS=4096
export LLM__OPENAI_API_KEY=sk-...

# Azure OpenAI
export LLM__PROVIDER=azure
export LLM__AZURE_API_KEY=your-key
export LLM__AZURE_API_BASE=https://your-resource.openai.azure.com
export LLM__AZURE_DEPLOYMENT_NAME=gpt-4o

# Ollama (default)
export LLM__PROVIDER=ollama
export LLM__MODEL=mistral:7b
export LLM__OLLAMA_BASE_URL=http://localhost:11434

# Vertex AI
export LLM__PROVIDER=vertex
export LLM__VERTEX_PROJECT=my-gcp-project
export LLM__VERTEX_LOCATION=us-central1

# Database connection
export DB__URL=postgresql+asyncpg://user:pass@localhost:5432/agent_db
export DB__POOL_SIZE=10
export DB__MAX_OVERFLOW=20
export DB__POOL_TIMEOUT=30
export DB__ECHO=false

# Embedding provider
export EMBEDDING__PROVIDER=ollama
export EMBEDDING__MODEL=nomic-embed-text
export EMBEDDING__DIMENSION=768

# Feature toggles
export FEATURES__ENABLE_STREAMING=true
export FEATURES__ENABLE_A2A=true
export FEATURES__ENABLE_METRICS=true
export FEATURES__ENABLE_RATE_LIMIT=false
export FEATURES__ENABLE_AUTH=false
export FEATURES__ENABLE_DB=false
export FEATURES__ENABLE_FEEDBACK=true
export FEATURES__MAX_CONCURRENT_AGENTS=10
export FEATURES__REQUEST_TIMEOUT=30.0
export FEATURES__LLM_RETRY_COUNT=3
export FEATURES__LLM_RETRY_DELAY=1.0
export FEATURES__CIRCUIT_BREAKER_THRESHOLD=5
export FEATURES__CIRCUIT_BREAKER_TIMEOUT=60.0

# Authentication
export AUTH__API_KEY=sk_prod_your_secret_key

# Rate limiting
export RATE_LIMIT__REQUESTS=300
export RATE_LIMIT__WINDOW_SECONDS=60

📋 PlatformSettings Class Reference

The PlatformSettings class is a Pydantic BaseSettings model that aggregates all nested configuration sections:

Section Class Prefix Description
Root PlatformSettings — App name, environment, log level, API version
llm LLMSettings LLM__ LLM provider, model, API keys
embedding EmbeddingSettings EMBEDDING__ Embedding provider and model
db DatabaseSettings DB__ Database URL and connection pool
features FeatureSettings FEATURES__ Feature flags and limits
auth AuthSettings AUTH__ API key authentication
rate_limit RateLimitSettings RATE_LIMIT__ Rate limiting configuration

Using PlatformSettings Directly

from agentomatic.config.settings import PlatformSettings, get_settings

# Auto-loads from env vars and .env
settings = get_settings()

print(settings.llm.provider)          # "ollama"
print(settings.llm.model)             # "mistral:7b"
print(settings.features.enable_auth)  # False
print(settings.db.url)                # "sqlite+aiosqlite:///data/platform.db"

# Pass to platform
platform = AgentPlatform.from_folder("agents/", settings=settings)

.env File Example

Create a .env file in your project root:

# .env — loaded automatically by PlatformSettings
APP_NAME=My Production Platform
APP_ENV=production
LOG_LEVEL=WARNING

# LLM Configuration
LLM__PROVIDER=openai
LLM__MODEL=gpt-4o
LLM__OPENAI_API_KEY=sk-proj-...
LLM__TEMPERATURE=0.1
LLM__MAX_TOKENS=4096

# Database
DB__URL=postgresql+asyncpg://postgres:secret@db:5432/agentomatic
DB__POOL_SIZE=20
DB__MAX_OVERFLOW=40

# Security
AUTH__API_KEY=sk_prod_super_secret
FEATURES__ENABLE_AUTH=true
FEATURES__ENABLE_RATE_LIMIT=true
RATE_LIMIT__REQUESTS=200
RATE_LIMIT__WINDOW_SECONDS=60

🤖 Per-Agent Configuration

Each agent can define its own configuration via config.py. This is independent of the platform-level settings and allows each agent to have unique parameters.

Defining Agent Config

# agents/my_agent/config.py
from pydantic import BaseModel, Field

class MyAgentConfig(BaseModel):
    """Agent-specific configuration."""

    prompt_version: str = Field("v1", description="Active prompt version")
    temperature: float = Field(0.2, ge=0.0, le=2.0)
    max_tokens: int = Field(2048, ge=1)
    llm_model: str = Field("ollama/mistral:7b")
    enable_memory: bool = Field(True, description="Use conversation memory")
    top_k_documents: int = Field(5, description="RAG retrieval count")

Accessing Agent Config at Runtime

# Inside your agent's nodes.py
from agentomatic import AgentRegistry

async def process(state: dict) -> dict:
    config = AgentRegistry().get("my_agent").config
    temperature = config.temperature
    model = config.llm_model
    # Use in LLM call...
    return {"response": "..."}

Config API Endpoint

When a config is detected, it's automatically exposed:

GET /api/v1/my_agent/config

{
  "prompt_version": "v1",
  "temperature": 0.2,
  "max_tokens": 2048,
  "llm_model": "ollama/mistral:7b",
  "enable_memory": true,
  "top_k_documents": 5
}

🚀 platform.run() Configuration

The run() method accepts server-level parameters:

platform = AgentPlatform.from_folder("agents/")
app = platform.build()

# Or run directly with uvicorn
platform.run(
    host="0.0.0.0",
    port=8000,
    reload=False,
    workers=4,
    # Extra kwargs passed to uvicorn.run()
    ssl_keyfile="/path/to/key.pem",
    ssl_certfile="/path/to/cert.pem",
)
Parameter Type Default Description
host str "0.0.0.0" Bind address
port int 8000 Bind port
reload bool False Auto-reload on code changes (dev only)
workers int 1 Number of uvicorn worker processes
**kwargs Any — Extra arguments passed to uvicorn.run()

📦 Docker / Production Example

services:
  agentomatic:
    build: .
    ports:
      - "8000:8000"
    environment:
      - AGENTOMATIC_LOG_LEVEL=WARNING
      - AGENTOMATIC_ENABLE_METRICS=true
      - AGENTOMATIC_ENABLE_AUTH=true
      - AGENTOMATIC_API_KEY=${API_KEY}
      - AGENTOMATIC_ENABLE_RATE_LIMIT=true
      - AGENTOMATIC_LOGS_HISTORY=true
      - DATABASE_URL=postgresql+asyncpg://postgres:secret@db:5432/agents
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: agents
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

apiVersion: v1
kind: ConfigMap
metadata:
  name: agentomatic-config
data:
  AGENTOMATIC_LOG_LEVEL: "WARNING"
  AGENTOMATIC_ENABLE_AUTH: "true"
  AGENTOMATIC_ENABLE_METRICS: "true"
  AGENTOMATIC_LOGS_HISTORY: "true"
  DATABASE_URL: "postgresql+asyncpg://user:pass@pg-service:5432/agents"

❓ Troubleshooting

My environment variables aren't being loaded

Check these common causes:

  1. .env file location: Must be in the project root (same directory as main.py)
  2. Variable shape: Generated-platform variables start with AGENTOMATIC_ (for example, AGENTOMATIC_LOG_LEVEL); PlatformSettings variables use their documented nested form (for example, LLM__MODEL)
  3. Priority: Environment variables always override .env file values
  4. Restart required: .env changes require a server restart (no hot-reload)
CORS errors from my frontend

Pass your frontend's origin to cors_origins:

platform = AgentPlatform.from_folder(
    "agents/",
    cors_origins=["http://localhost:3000", "https://app.example.com"],
)
Topic Link
Middleware (auth, rate limiting) Middleware
Storage backends Storage Backends
Configuration stacks Stacks
Security & JWT Security
LLM providers & failover LLM Providers
CLI run command options CLI Reference