Full HCL configuration reference — LLM providers, models, queue, search, storage, and agent behavior

Providers & Configuration

All configuration is defined in a single HCL file (or JSON). This page is the canonical reference for every config field.

A3S Code uses HCL configuration format exclusively. The env() function reads environment variables at parse time.

Basic Configuration

default_model = "anthropic/claude-sonnet-4-20250514"

providers {
  name    = "anthropic"
  api_key = "sk-ant-..."

  models {
    id        = "claude-sonnet-4-20250514"
    name      = "Claude Sonnet 4"
    family    = "claude-sonnet"
    tool_call = true
  }
}

Multiple Providers

Define as many providers as needed. Switch between them at session creation via provider/model:

default_model = "anthropic/claude-sonnet-4-20250514"

providers {
  name    = "anthropic"
  api_key = "sk-ant-..."

  models {
    id        = "claude-sonnet-4-20250514"
    name      = "Claude Sonnet 4"
    tool_call = true
  }

  models {
    id        = "claude-haiku-4-20250514"
    name      = "Claude Haiku 4"
    tool_call = true
  }
}

providers {
  name    = "openai"
  api_key = "sk-..."

  models {
    id        = "gpt-4o"
    name      = "GPT-4o"
    tool_call = true
  }

  models {
    id        = "gpt-4o-mini"
    name      = "GPT-4o Mini"
    tool_call = true
  }
}

Then select at runtime:

// Use default model (anthropic/claude-sonnet-4-20250514)
let session = agent.session("/project", None)?;

// Use a different model
let session = agent.session("/project", Some(
    SessionOptions::new().with_model("openai/gpt-4o")
))?;

Per-Model API Key & Base URL

Models under the same provider can have different api_key and base_url. This is useful for:

API key rotation — different keys for different models
Proxy endpoints — route specific models through a proxy or gateway
Regional endpoints — different base URLs for latency or compliance

providers {
  name     = "anthropic"
  api_key  = "sk-ant-default-key..."          # default for all models
  base_url = "https://api.anthropic.com"      # default base URL

  models {
    id        = "claude-sonnet-4-20250514"
    name      = "Claude Sonnet 4"
    tool_call = true
    # inherits provider api_key and base_url
  }

  models {
    id        = "claude-sonnet-4-20250514-eu"
    name      = "Claude Sonnet 4 (EU)"
    api_key   = "sk-ant-eu-key..."              # override
    base_url  = "https://eu.api.anthropic.com"  # override
    tool_call = true
  }
}

providers {
  name    = "openai"
  api_key = "sk-team-key..."

  models {
    id        = "gpt-4o"
    name      = "GPT-4o"
    tool_call = true
    # inherits provider api_key
  }

  models {
    id        = "gpt-4o-mini"
    name      = "GPT-4o Mini"
    api_key   = "sk-personal-key..."   # different key for this model
    tool_call = true
  }
}

Provider-level api_key and base_url are defaults. Model-level values override them.

Model Fields

Prop

Type

Provider Fields

Prop

Type

Full Configuration Reference

Complete HCL config with all available fields:

# === LLM (required) ===
default_model = "anthropic/claude-sonnet-4-20250514"

# === Agent Behavior ===
max_tool_rounds  = 20          # default: 50
thinking_budget  = 4096        # reasoning token budget

# === Extensions ===
skill_dirs = ["./skills"]      # *.md skill files
agent_dirs = ["./agents"]      # *.yaml/*.md agent files

# === Storage ===
storage_backend = "file"       # "memory" | "file" | "custom"
sessions_dir    = "/tmp/a3s"   # session persistence path
storage_url     = "redis://localhost:6379"

# === Providers ===
providers {
  name    = "anthropic"
  api_key = env("ANTHROPIC_API_KEY")

  models {
    id          = "claude-sonnet-4-20250514"
    name        = "Claude Sonnet 4"
    family      = "claude-sonnet"
    tool_call   = true
    temperature = true
    reasoning   = false
    cost {
      input       = 3.0
      output      = 15.0
      cache_read  = 0.3
      cache_write = 3.75
    }
    limit {
      context = 200000
      output  = 8192
    }
  }
}

providers {
  name    = "openai"
  api_key = env("OPENAI_API_KEY")

  models {
    id        = "gpt-4o"
    name      = "GPT-4o"
    tool_call = true
  }

  models {
    id        = "gpt-4o-proxy"
    name      = "GPT-4o (via Proxy)"
    api_key   = "sk-proxy-key..."                 # per-model override
    base_url  = "https://proxy.example.com/v1"    # per-model override
    tool_call = true
  }
}

# === Queue (optional) ===
queue {
  query_max_concurrency    = 5    # default: 5
  execute_max_concurrency  = 2    # default: 2
  generate_max_concurrency = 1    # default: 1
  enable_metrics           = true
  enable_dlq               = true

  retry_policy {
    strategy         = "exponential"  # "fixed" | "exponential"
    max_retries      = 3
    initial_delay_ms = 100
  }
}

# === Search (optional) ===
search {
  timeout = 30

  health {
    max_failures    = 3
    suspend_seconds = 60
  }

  engine {
    ddg {
      enabled = true
      weight  = 1.5
    }
    wiki {
      enabled = true
      weight  = 1.2
    }
    brave {
      enabled = true
      weight  = 1.0
      timeout = 20
    }
  }
}

Config Fields

Prop

Type

The `env()` Function

Use env("VAR_NAME") to read environment variables at config parse time:

providers {
  name    = "anthropic"
  api_key = env("ANTHROPIC_API_KEY")
}

This avoids hardcoding secrets in config files.

JSON Format

The same config in JSON (camelCase field names):

{
  "defaultModel": "anthropic/claude-sonnet-4-20250514",
  "providers": [
    {
      "name": "anthropic",
      "apiKey": "sk-ant-...",
      "models": [
        {
          "id": "claude-sonnet-4-20250514",
          "name": "Claude Sonnet 4",
          "toolCall": true
        },
        {
          "id": "claude-sonnet-4-20250514-eu",
          "name": "Claude Sonnet 4 (EU)",
          "apiKey": "sk-ant-eu-key...",
          "baseUrl": "https://eu.api.anthropic.com",
          "toolCall": true
        }
      ]
    }
  ]
}

Providers & Configuration

On this page