Skip to main content

Main Configuration

The main configuration file (agentmap_config.yaml) contains all core AgentMap settings including LLM providers, intelligent routing, memory management, execution policies, and performance optimization. This guide covers every configuration option with examples and best practices.

📁 Configuration File Loading​

AgentMap uses automatic configuration discovery with the following precedence order:

1. Explicit --config flag (Highest Priority)​

agentmap run --config /path/to/custom_config.yaml

Explicitly specified config files take absolute precedence.

2. agentmap_config.yaml in current directory (Auto-Discovered)​

# Place agentmap_config.yaml in your working directory
cd /your/project
agentmap run  # Automatically discovers and uses ./agentmap_config.yaml

If no explicit config is provided, AgentMap automatically checks for agentmap_config.yaml in the current working directory.

3. System defaults (Lowest Priority)​

# If no config file found, uses built-in defaults
agentmap run

When no config file is found, AgentMap uses sensible system defaults.

Configuration Discovery Logging​

AgentMap always logs which configuration source is being used:

[2024-08-06 10:30:15] INFO: Using configuration from: auto-discovered: /project/agentmap_config.yaml

Quick Setup​

  1. Initialize config template:

    agentmap init-config

  2. Edit the generated agentmap_config.yaml

  3. Run commands without --config flag:

    agentmap run --csv examples/lesson1.csv

📋 Complete Configuration Structure​

# Core configuration
csv_path: "examples/SingleNodeGraph.csv"
autocompile: true
storage_config_path: "agentmap_config_storage.yaml"

# Directory paths
paths:
  custom_agents: "agentmap/custom_agents"
  functions: "agentmap/custom_functions"
  csv_repository: "workflows"

# LLM configuration with multiple providers
llm:
  openai:
    api_key: "env:OPENAI_API_KEY"
    model: "gpt-4o-mini"
    temperature: 0.7
  anthropic:
    api_key: "env:ANTHROPIC_API_KEY"
    model: "claude-sonnet-4-6"
    temperature: 0.7
  google:
    api_key: "env:GOOGLE_API_KEY"
    model: "gemini-2.5-flash"
    temperature: 0.7

# Intelligent routing system
routing:
  enabled: true
  routing_matrix:
    # Provider × Complexity matrix
  task_types:
    # Application-specific task definitions
  complexity_analysis:
    # Automatic complexity detection
  cost_optimization:
    # Cost management settings
  fallback:
    # Error handling and defaults

# Memory configuration
memory:
  enabled: false
  default_type: "buffer"
  buffer_window_size: 5
  max_token_limit: 2000
  memory_key: "conversation_memory"

# Execution tracking and success policies
execution:
  tracking:
    enabled: true
    track_outputs: true
    track_inputs: true
  success_policy:
    type: "all_nodes"
    critical_nodes: []
    custom_function: ""

# Logging configuration
logging:
  version: 1
  file_path: null
  formatters:
    # Custom formatters
  handlers:
    # Log handlers
  root:
    level: INFO
    handlers: [console]

# Environment variable overrides
environment_overrides:
  routing_enabled: ${AGENTMAP_ROUTING_ENABLED:true}
  default_task_type: ${AGENTMAP_DEFAULT_TASK_TYPE:general}

🔧 Core Configuration​

Basic Settings​

# Required: Path to your main workflow CSV file
csv_path: "examples/SingleNodeGraph.csv"

# Optional: Automatically compile graphs on startup (default: true)
autocompile: true

# Optional: Path to storage configuration file (default: "storage_config.yaml")
storage_config_path: "agentmap_config_storage.yaml"

Configuration Details:

  • csv_path: Must end with .csv extension, validated by Pydantic
  • autocompile: Enables automatic workflow compilation for faster execution
  • storage_config_path: Separate file for storage provider configurations

📁 Paths Configuration​

paths:
  # Directory for custom agent implementations
  custom_agents: "agentmap/custom_agents"
  
  # Directory for custom function implementations  
  functions: "agentmap/custom_functions"
  
  # Directory for compiled workflow graphs (performance optimization)
  compiled_graphs: "agentmap/compiled_graphs"
  
  # Repository directory for storing workflow CSV files
  csv_repository: "workflows"

Path Configuration Best Practices:

  • Use relative paths for portability across environments
  • Ensure directories exist or AgentMap will create them automatically
  • Consider using environment-specific paths for different deployments

🔐 Secrets Management​

Never commit API keys to version control

agentmap_config.yaml may contain sensitive credentials (LLM API keys, JWT secrets, database URLs). Do not commit it with api keys — The recommended approach is to use environment variables instead. Then you are able to check in the file to save your configuration.

Add config file to .gitignore if using secrets in the file.​

# .gitignore
agentmap_config.yaml
.env

Keep a agentmap_config.yaml.example (or use agentmap init-config output) with placeholder values checked in for reference.

Set secrets in a .env file at your project root (also excluded from git):

# .env  — never commit this file
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...

Then reference them in agentmap_config.yaml using the ${VAR:default} syntax:

llm:
  openai:
    api_key: "${OPENAI_API_KEY}"

Loading .env at runtime​

AgentMap does not auto-load .env files — the variables must be present in the process environment before the app starts. Source them in your shell or run script:

# Option 1 — source before running
set -a && source .env && set +a
agentmap run

# Option 2 — prefix the command
env $(grep -v '^#' .env | xargs) agentmap run

For programmatic use, add python-dotenv to your project and call load_dotenv() before importing AgentMap:

from dotenv import load_dotenv
load_dotenv()  # loads .env into os.environ

from agentmap import AgentMap

Environment-specific configuration​

For multi-environment deployments, use separate .env files and override the config path:

# Development
cp .env.development .env && agentmap run

# Production — inject vars from your secret manager (e.g. AWS Secrets Manager, Vault)
agentmap run --config /etc/agentmap/prod_config.yaml

🤖 LLM Provider Configuration​

For complete LLM provider setup, resilience configuration, and routing matrix details, see LLM Configuration.

Multi-Provider Setup​

llm:
  openai:
    api_key: "env:OPENAI_API_KEY"    # Environment variable reference
    model: "gpt-4o-mini"           # Default model
    temperature: 0.7                 # Creativity parameter (0.0-2.0)

  anthropic:
    api_key: "env:ANTHROPIC_API_KEY"
    model: "claude-sonnet-4-6"
    temperature: 0.7

  google:
    api_key: "env:GOOGLE_API_KEY"
    model: "gemini-2.5-flash"
    temperature: 0.7

🎯 LLM Routing Configuration​

AgentMap's intelligent routing system automatically selects the optimal LLM provider and model based on task complexity, cost optimization, and performance requirements.

Routing Matrix​

routing:
  enabled: true
  
  # Core routing table: (provider, complexity) → model
  routing_matrix:
    anthropic:
      low: "claude-3-haiku-20240307"
      medium: "claude-sonnet-4-6"
      high: "claude-opus-4-6"
      critical: "claude-opus-4-6"
    
    openai:
      low: "gpt-4o-mini"
      medium: "gpt-4-turbo"
      high: "gpt-4"
      critical: "gpt-4"
    
    google:
      low: "gemini-2.5-flash"
      medium: "gemini-2.5-flash"
      high: "gemini-2.5-pro"
      critical: "gemini-2.5-pro"

Task Types​

Define application-specific task categories with routing preferences:

routing:
  task_types:
    # General purpose tasks
    general:
      description: "General purpose tasks"
      provider_preference: ["anthropic", "openai", "google"]
      default_complexity: "medium"
      complexity_keywords:
        high: ["analyze", "complex", "detailed", "comprehensive"]
        critical: ["urgent", "critical", "important", "decision"]
    
    # Creative content generation
    creative_writing:
      description: "Creative content generation and storytelling"
      provider_preference: ["anthropic", "openai"]
      default_complexity: "high"
      complexity_keywords:
        medium: ["write", "create", "story"]
        high: ["creative", "narrative", "imaginative", "artistic"]
        critical: ["masterpiece", "publication", "professional"]
    
    # Technical analysis and coding
    code_analysis:
      description: "Code review, analysis, and technical documentation"
      provider_preference: ["openai", "anthropic"]
      default_complexity: "medium"
      complexity_keywords:
        low: ["simple", "basic", "review"]
        medium: ["analyze", "refactor", "optimize"]
        high: ["architecture", "design", "complex algorithm"]
        critical: ["security", "production", "critical bug"]
    
    # Customer service interactions
    customer_service:
      description: "Customer service interactions and support"
      provider_preference: ["anthropic", "openai"]
      default_complexity: "medium"
      complexity_keywords:
        low: ["greeting", "simple question", "faq"]
        medium: ["support", "help", "issue"]
        high: ["complaint", "escalation", "complex problem"]
        critical: ["urgent", "emergency", "executive"]
    
    # Data analysis and insights
    data_analysis:
      description: "Data processing, analysis, and insights"
      provider_preference: ["openai", "google", "anthropic"]
      default_complexity: "medium"
      complexity_keywords:
        low: ["simple", "summary", "basic stats"]
        medium: ["analyze", "trends", "patterns"]
        high: ["deep analysis", "insights", "correlations"]
        critical: ["predictive", "strategic", "business critical"]

Complexity Analysis​

Automatic complexity detection based on multiple factors:

routing:
  complexity_analysis:
    # Prompt length thresholds (characters)
    prompt_length_thresholds:
      low: 100      # < 100 chars = low complexity
      medium: 300   # 100-300 chars = medium complexity
      high: 800     # 300-800 chars = high complexity
      # > 800 chars = critical complexity
    
    # Enable different analysis methods
    methods:
      prompt_length: true
      keyword_analysis: true
      context_analysis: true
      memory_analysis: true
    
    # Keyword weighting for complexity calculation
    keyword_weights:
      complexity_keywords: 0.4
      task_specific_keywords: 0.3
      prompt_structure: 0.3
    
    # Context analysis settings
    context_analysis:
      memory_size_threshold: 10
      input_field_count_threshold: 5

Cost Optimization​

routing:
  cost_optimization:
    enabled: true
    # Prefer cheaper models when complexity allows
    prefer_cost_effective: true
    # Maximum cost tier (low, medium, high, critical)
    max_cost_tier: "high"

Fallback Configuration​

routing:
  fallback:
    # Default provider when preferences unavailable
    default_provider: "anthropic"
    # Default model when routing fails
    default_model: "claude-3-haiku-20240307"
    # Retry with lower complexity if model unavailable
    retry_with_lower_complexity: true

Performance Settings​

routing:
  performance:
    # Cache routing decisions for identical inputs
    enable_routing_cache: true
    # Cache TTL in seconds
    cache_ttl: 300
    # Maximum cache size
    max_cache_size: 1000

🧠 Memory Configuration​

Configure conversation memory for stateful workflows:

memory:
  # Enable/disable memory functionality
  enabled: false
  
  # Memory type: "buffer", "buffer_window", "summary", "token_buffer"
  default_type: "buffer"
  
  # Number of previous messages to remember (buffer_window type)
  buffer_window_size: 5
  
  # Maximum tokens before summarization (token_buffer type)
  max_token_limit: 2000
  
  # Key name for memory in workflow state
  memory_key: "conversation_memory"

Memory Types​

Buffer Memory:

  • Stores all conversation history
  • Best for: Short conversations, complete context needed

Buffer Window Memory:

  • Stores last N messages
  • Best for: Ongoing conversations, limited context

Summary Memory:

  • Automatically summarizes old messages
  • Best for: Long conversations, key information retention

Token Buffer Memory:

  • Manages memory based on token count
  • Best for: Cost-sensitive applications, token limits

⚙️ Execution Configuration​

Control workflow execution behavior and tracking:

execution:
  # What to record during execution
  tracking:
    enabled: true
    track_outputs: true    # Record node outputs
    track_inputs: true     # Record node inputs
  
  # How to determine workflow success
  success_policy:
    type: "all_nodes"      # "all_nodes", "final_node", "critical_nodes", "custom"
    critical_nodes: []     # List of critical node names
    custom_function: ""    # Custom success evaluation function

Success Policy Types​

all_nodes (default):

  • Workflow succeeds only if all nodes complete successfully
  • Best for: Critical workflows, data processing pipelines

final_node:

  • Workflow succeeds if the final node completes successfully
  • Best for: Output-focused workflows, reporting systems

critical_nodes:

  • Workflow succeeds if specified critical nodes complete successfully
  • Best for: Complex workflows with optional steps

custom:

  • Use custom function to evaluate success
  • Best for: Complex business logic, custom success criteria

📝 Logging Configuration​

Comprehensive logging setup using Python's logging configuration:

logging:
  version: 1
  disable_existing_loggers: false
  
  # Optional: Log to file
  file_path: "/var/log/agentmap/app.log"
  
  # Log formatters
  formatters:
    default:
      format: "[%(asctime)s] [%(levelname)s] %(name)s: %(message)s"
    detailed:
      format: "[%(asctime)s] [%(levelname)s] [%(filename)s:%(lineno)d] %(name)s: %(message)s"
  
  # Log handlers
  handlers:
    console:
      class: logging.StreamHandler
      formatter: default
      level: DEBUG
    
    file:
      class: logging.FileHandler
      filename: "/var/log/agentmap/app.log"
      formatter: detailed
      level: INFO
  
  # Root logger configuration
  root:
    level: INFO
    handlers: [console, file]
  
  # Logger-specific settings
  loggers:
    agentmap.routing:
      level: DEBUG
      handlers: [console]
      propagate: false
    
    agentmap.storage:
      level: WARNING
      handlers: [file]
      propagate: false

Log Levels​

  • TRACE: Most detailed, development only
  • DEBUG: Detailed debugging information
  • INFO: General operational information
  • WARNING: Warning messages, potential issues
  • ERROR: Error messages, failures

🌍 Environment Variable Overrides​

Use environment variables to override configuration at runtime:

environment_overrides:
  # Routing system
  routing_enabled: ${AGENTMAP_ROUTING_ENABLED:true}
  default_task_type: ${AGENTMAP_DEFAULT_TASK_TYPE:general}
  cost_optimization: ${AGENTMAP_COST_OPTIMIZATION:true}
  routing_cache_enabled: ${AGENTMAP_ROUTING_CACHE:true}
  
  # Performance settings
  max_concurrent_requests: ${AGENTMAP_MAX_CONCURRENT:10}
  request_timeout: ${AGENTMAP_REQUEST_TIMEOUT:30}
  
  # Development settings
  debug_mode: ${AGENTMAP_DEBUG:false}
  verbose_logging: ${AGENTMAP_VERBOSE:false}

Environment Variable Syntax​

# With default value
setting: ${ENV_VAR:default_value}

# Without default (required)
setting: ${ENV_VAR}

# Boolean values
enabled: ${ENABLE_FEATURE:true}

# Numeric values
port: ${PORT:8080}

🔒 Authentication Configuration​

Configure authentication and authorization:

authentication:
  # JWT configuration
  jwt:
    secret_key: "env:JWT_SECRET_KEY"
    algorithm: "HS256"
    expiration_hours: 24
  
  # API key authentication
  api_keys:
    enabled: true
    header_name: "X-API-Key"
    keys:
      - "env:API_KEY_1"
      - "env:API_KEY_2"
  
  # Supabase integration
  supabase:
    url: "env:SUPABASE_URL"
    api_key: "env:SUPABASE_API_KEY"
    jwt_secret: "env:SUPABASE_JWT_SECRET"
  
  # Permission system
  permissions:
    require_auth: true
    default_permissions: ["read"]
    admin_permissions: ["read", "write", "delete", "admin"]

🚀 Performance Optimization​

Configure performance and resource management:

performance:
  # Connection pooling
  connection_pool:
    max_connections: 100
    pool_timeout: 30
    retry_attempts: 3
  
  # Caching
  cache:
    enabled: true
    type: "memory"      # "memory", "redis", "file"
    ttl: 3600          # Time to live in seconds
    max_size: 1000     # Maximum cache entries
  
  # Rate limiting
  rate_limiting:
    enabled: false
    requests_per_minute: 60
    burst_size: 10
  
  # Timeouts
  timeouts:
    llm_request: 30    # LLM request timeout
    storage_operation: 10    # Storage operation timeout
    workflow_execution: 300  # Total workflow timeout

🏢 Host Application Configuration​

Configure integration with host applications:

host_application:
  # Service discovery
  service_discovery:
    enabled: true
    protocol: "http"
    discovery_interval: 30
  
  # Service injection
  services:
    custom_service:
      type: "http"
      endpoint: "http://localhost:8080/api"
      authentication:
        type: "bearer"
        token: "env:CUSTOM_SERVICE_TOKEN"
    
    database_service:
      type: "database"
      connection_string: "env:DATABASE_URL"
      pool_size: 10
  
  # Protocol configuration
  protocols:
    http:
      timeout: 30
      retry_attempts: 3
      headers:
        User-Agent: "AgentMap/1.0"
    
    grpc:
      timeout: 15
      keepalive_interval: 30

✅ Configuration Validation​

AgentMap automatically validates configuration using Pydantic models:

Validation Rules​

  • Required Fields: csv_path must be provided and end with .csv
  • Numeric Ranges: temperature must be between 0.0 and 2.0
  • Default Values: All optional fields have sensible defaults

Validation Examples​

# ✅ Valid configuration
temperature: 0.7

# ❌ Invalid configuration
temperature: 3.0  # Error: temperature must be <= 2.0

# ✅ Valid success policy
success_policy:
  type: "all_nodes"

# ❌ Invalid success policy  
success_policy:
  type: "invalid_type"  # Error: must be one of: all_nodes, final_node, critical_nodes, custom

🔄 Hot Reloading​

Some configuration changes can be applied without restart:

Hot Reloadable Settings​

  • Environment variable overrides
  • Logging levels
  • Routing preferences
  • Cache settings

Restart Required Settings​

  • Core paths configuration
  • Storage provider settings
  • Authentication configuration
  • LLM provider credentials

📖 Next Steps​

  1. Secure your secrets - Add agentmap_config.yaml and .env to .gitignore before your first commit
  2. Configure Storage - Set up your data persistence layer
  3. Review Examples - See complete configuration examples
  4. Test Configuration - Validate your setup before deployment

Ready to configure storage providers? Continue to the Storage Configuration guide.