Skip to content

Configuration Reference

Jump to bottom
alexheifetz edited this page Sep 22, 2025 · 1 revision

Configuration Reference

Complete reference for configuring Embabel Agent Framework applications, covering all available properties, environment variables, and configuration patterns.

Configuration Architecture

Embabel uses a layered configuration approach with clear separation between platform internals and application configuration:

  • Platform Properties (embabel.agent.platform.*) - Internal framework behavior
  • Application Properties (embabel.agent.*) - Business logic and deployment configuration
  • Module Properties (embabel.shell.*, etc.) - Module-specific settings

Platform Properties Reference

Agent Platform Core

Namespace: embabel.agent.platform.*

# Agent scanning and discovery
embabel.agent.platform.scanning.annotation=true
embabel.agent.platform.scanning.packages=com.embabel.agent

# Agent ranking and selection
embabel.agent.platform.ranking.max-attempts=5
embabel.agent.platform.ranking.backoff-millis=100

# Autonomy and confidence thresholds
embabel.agent.platform.autonomy.agent-confidence-cut-off=0.6
embabel.agent.platform.autonomy.goal-confidence-cut-off=0.6

# Process ID generation
embabel.agent.platform.process-id-generation.include-version=false
embabel.agent.platform.process-id-generation.include-agent-name=false

# LLM operations and prompts
embabel.agent.platform.llm-operations.prompts.maybe-prompt-template=maybe_prompt_contribution
embabel.agent.platform.llm-operations.prompts.generate-examples-by-default=true
embabel.agent.platform.llm-operations.data-binding.max-attempts=10
embabel.agent.platform.llm-operations.data-binding.fixed-backoff-millis=10

# Server-sent events
embabel.agent.platform.sse.max-buffer-size=100
embabel.agent.platform.sse.max-process-buffers=1000

# Testing and development  
embabel.agent.platform.test.mock-mode=false

Model Provider Platform Settings

Namespace: embabel.agent.platform.models.*

# Anthropic provider
embabel.agent.platform.models.anthropic.max-attempts=10
embabel.agent.platform.models.anthropic.backoff-millis=5000

# OpenAI provider
embabel.agent.platform.models.openai.max-attempts=10
embabel.agent.platform.models.openai.backoff-millis=5000

Application Properties Reference

Logging and Personality

Namespace: embabel.agent.logging.*

# Personality configuration
embabel.agent.logging.personality=default
embabel.agent.logging.verbosity=info
embabel.agent.logging.enable-runtime-switching=false

Available personalities:

  • default - Standard Embabel logging
  • starwars - Star Wars themed with ASCII art
  • severance - Lumon Industries corporate style
  • hitchhiker - Hitchhiker's Guide to the Galaxy references
  • montypython - Monty Python humor and quotes
  • colossus - 1970s sci-fi computer aesthetic

Infrastructure Configuration

Neo4j Integration

Namespace: embabel.agent.infrastructure.neo4j.*

embabel.agent.infrastructure.neo4j.enabled=false
embabel.agent.infrastructure.neo4j.uri=${NEO4J_URI:bolt://localhost:7687}
embabel.agent.infrastructure.neo4j.authentication.username=${NEO4J_USERNAME:}
embabel.agent.infrastructure.neo4j.authentication.password=${NEO4J_PASSWORD:}

MCP (Model Context Protocol) Integration

Namespace: embabel.agent.infrastructure.mcp.*

embabel.agent.infrastructure.mcp.enabled=false
embabel.agent.infrastructure.mcp.client.name=embabel
embabel.agent.infrastructure.mcp.client.version=1.0.0
embabel.agent.infrastructure.mcp.client.request-timeout=30s
embabel.agent.infrastructure.mcp.client.type=SYNC

Observability and Monitoring

Namespace: embabel.agent.infrastructure.observability.*

embabel.agent.infrastructure.observability.enabled=false

# AI observations
embabel.agent.infrastructure.observability.ai.chat.observations.enabled=true
embabel.agent.infrastructure.observability.ai.chat.observations.log-prompt=true
embabel.agent.infrastructure.observability.ai.chat.observations.log-completion=true
embabel.agent.infrastructure.observability.ai.chat.observations.include-completion=true
embabel.agent.infrastructure.observability.ai.chat.observations.include-prompt=true
embabel.agent.infrastructure.observability.ai.chat.observations.include-error-logging=true

# Tracing configuration
embabel.agent.infrastructure.observability.tracing.enabled=true
embabel.agent.infrastructure.observability.tracing.sampling-probability=1.0
embabel.agent.infrastructure.observability.tracing.zipkin-endpoint=${ZIPKIN_ENDPOINT:http://localhost:9411/api/v2/spans}

# Management endpoints
embabel.agent.infrastructure.observability.management.endpoints.web-exposure-include=*
embabel.agent.infrastructure.observability.management.endpoint.env.show-values=always
embabel.agent.infrastructure.observability.management.endpoint.env.show-details=always
embabel.agent.infrastructure.observability.management.endpoint.health.show-details=always
embabel.agent.infrastructure.observability.management.observations.enabled=true
embabel.agent.infrastructure.observability.management.observations.web-response-enabled=true

Module-Specific Properties

Shell Configuration

Namespace: embabel.shell.*

embabel.shell.enabled=false
embabel.shell.line-length=140
embabel.shell.chat.confirm-goals=true
embabel.shell.chat.bind-conversation=false

Migration Properties

Migration Detection System

Namespace: embabel.agent.platform.migration.*

# Enable migration detection (disabled by default for zero production overhead)
embabel.agent.platform.migration.scanning.enabled=false

# Packages to scan for deprecated property usage
embabel.agent.platform.migration.scanning.include-packages=com.embabel.agent,com.embabel.agent.shell

# Additional packages to exclude from scanning
embabel.agent.platform.migration.scanning.additional-excludes=

# Enable automatic JAR package exclusion for performance
embabel.agent.platform.migration.scanning.auto-exclude-jar-packages=true

# Warning configuration
embabel.agent.platform.migration.warnings.enabled=true
embabel.agent.platform.migration.warnings.individual-logging=true

OpenAI-Compatible Providers

Embabel supports any OpenAI-compatible API provider by configuring the base URL and API key:

Azure OpenAI Service

OPENAI_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment
OPENAI_API_KEY=your-azure-api-key

Groq

OPENAI_BASE_URL=https://api.groq.com/openai/v1
OPENAI_API_KEY=your-groq-api-key

DeepSeek

OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_API_KEY=your-deepseek-api-key

Together AI

OPENAI_BASE_URL=https://api.together.xyz/v1
OPENAI_API_KEY=your-together-api-key

Custom OpenAI-Compatible Server

OPENAI_BASE_URL=http://your-server:8080/v1
OPENAI_API_KEY=your-custom-api-key
OPENAI_COMPLETIONS_PATH=/custom/chat/completions  # If different from default

Optional Cloud Provider API Keys

Note: These are completely optional. Embabel works great with local models!

# Optional - enables OpenAI cloud models (GPT-4, etc.)
export OPENAI_API_KEY=your_openai_api_key

# Optional - enables Anthropic cloud models (Claude, etc.)
export ANTHROPIC_API_KEY=your_anthropic_api_key

# Optional - enables AWS Bedrock models (requires AWS credentials)
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=your_aws_access_key
export AWS_SECRET_ACCESS_KEY=your_aws_secret_key

# Optional - for examples that demonstrate cloud features
export EMBABEL_API_KEY=brahmsian

Infrastructure Credentials (when enabled)

# Neo4j Integration (when embabel.agent.infrastructure.neo4j.enabled=true)
export NEO4J_URI=bolt://your-neo4j-server:7687
export NEO4J_USERNAME=your_neo4j_username
export NEO4J_PASSWORD=your_neo4j_password

# MCP Server API Keys (for specific tools when enabled)
export BRAVE_API_KEY=your_brave_search_api_key              # Brave search MCP
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_github_token    # GitHub MCP
export GOOGLE_MAPS_API_KEY=your_google_maps_key             # Google Maps MCP

# Observability (when embabel.agent.infrastructure.observability.enabled=true)
export ZIPKIN_ENDPOINT=http://your-zipkin:9411/api/v2/spans  # Tracing endpoint

Optional Environment Variables

# Agent behavior
export EMBABEL_AGENT_LOGGING_PERSONALITY=starwars
export EMBABEL_AGENT_LOGGING_VERBOSITY=debug

# Platform tuning
export EMBABEL_AGENT_PLATFORM_AUTONOMY_AGENT_CONFIDENCE_CUT_OFF=0.8
export EMBABEL_AGENT_PLATFORM_RANKING_MAX_ATTEMPTS=10

# Infrastructure toggles
export EMBABEL_AGENT_INFRASTRUCTURE_NEO4J_ENABLED=true
export EMBABEL_AGENT_INFRASTRUCTURE_MCP_ENABLED=true
export EMBABEL_AGENT_INFRASTRUCTURE_OBSERVABILITY_ENABLED=true

# Shell configuration
export EMBABEL_SHELL_ENABLED=true
export EMBABEL_SHELL_LINELENGTH=120

# Migration detection (disabled by default)
export EMBABEL_AGENT_PLATFORM_MIGRATION_SCANNING_ENABLED=true

Configuration by Environment

Development Environment

# application-development.yml
embabel:
  agent:
    platform:
      test:
        mock-mode: true              # Use mock services
    logging:
      personality: starwars          # Fun logging for development
      verbosity: debug               # Detailed logging
    infrastructure:
      neo4j:
        enabled: true
        uri: bolt://localhost:7687
        authentication:
          username: ${NEO4J_USERNAME:neo4j}
          password: ${NEO4J_PASSWORD:dev}
      observability:
        enabled: true
        tracing:
          sampling-probability: 1.0   # Full sampling in dev
          zipkin-endpoint: http://localhost:9411/api/v2/spans
  shell:
    enabled: true                    # Interactive development

spring:
  profiles:
    active: development

Testing Environment

# application-test.yml  
embabel:
  agent:
    platform:
      test:
        mock-mode: true              # Always mock in tests
    logging:
      personality: default           # Clean test output
      verbosity: warn                # Minimal logging
    infrastructure:
      neo4j:
        enabled: false               # Disable external dependencies
      mcp:
        enabled: false
      observability:
        enabled: false
  shell:
    enabled: false                   # No interactive shell in tests

Production Environment

# application-production.yml
embabel:
  agent:
    platform:
      test:
        mock-mode: false             # Real services only
    logging:
      personality: default           # Professional logging
      verbosity: info                # Balanced logging
    infrastructure:
      neo4j:
        enabled: true
        uri: ${NEO4J_URI:}           # Required from environment
        authentication:
          username: ${NEO4J_USERNAME:}
          password: ${NEO4J_PASSWORD:}
      mcp:
        enabled: true
        servers:
          github:
            command: docker
            args: ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "mcp/github"]
            env:
              GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PERSONAL_ACCESS_TOKEN:}
      observability:
        enabled: true
        tracing:
          sampling-probability: 0.1   # Reduced sampling in prod
          zipkin-endpoint: ${ZIPKIN_ENDPOINT:}
  shell:
    enabled: false                   # No interactive shell in production

spring:
  profiles:
    active: production

logging:
  level:
    com.embabel: INFO
    org.springframework: WARN

Configuration Precedence (Highest to Lowest)

  1. Environment Variables - EMBABEL_AGENT_LOGGING_PERSONALITY=starwars
  2. System Properties - -Dembabel.agent.logging.personality=starwars
  3. Application Properties - application.yml values
  4. Platform Defaults - agent-platform.properties defaults
  5. Framework Defaults - Hardcoded fallbacks

Security Best Practices

Never Hardcode Secrets

# ❌ NEVER DO THIS
embabel:
  agent:
    infrastructure:
      neo4j:
        authentication:
          password: "hardcoded-password"  # Security vulnerability!

# ✅ SECURE APPROACH
embabel:
  agent:
    infrastructure:
      neo4j:
        authentication:
          password: ${NEO4J_PASSWORD:}    # Must be provided via environment

Use Secrets Management in Production

# Development (local environment)
export NEO4J_PASSWORD=dev_password

# Production (from AWS Secrets Manager)
export NEO4J_PASSWORD=$(aws secretsmanager get-secret-value \
  --secret-id prod/neo4j/password \
  --query SecretString --output text)

# Production (from Kubernetes secret)
# NEO4J_PASSWORD is mounted from secret volume

Environment-Specific Credentials

# application-development.yml
embabel:
  agent:
    infrastructure:
      neo4j:
        uri: bolt://localhost:7687
        authentication:
          username: ${NEO4J_USERNAME:dev_user}
          password: ${NEO4J_PASSWORD:dev_password}

# application-production.yml  
embabel:
  agent:
    infrastructure:
      neo4j:
        uri: ${NEO4J_URI:}                    # Required
        authentication:
          username: ${NEO4J_USERNAME:}        # Required  
          password: ${NEO4J_PASSWORD:}        # Required

Property Validation

Built-in Validation

@ConfigurationProperties("embabel.agent.infrastructure.neo4j")
@Validated
data class Neo4jConfiguration(
    var enabled: Boolean = false,
    
    @field:NotBlank(message = "Neo4j URI must be provided when enabled")
    var uri: String = "",
    
    @field:Valid
    var authentication: AuthConfig = AuthConfig()
) {
    data class AuthConfig(
        @field:NotBlank(message = "Neo4j username must be provided")
        var username: String = "",
        
        @field:NotBlank(message = "Neo4j password must be provided") 
        var password: String = ""
    )
}

Custom Validation

@Component
class ConfigurationValidator {
    
    @PostConstruct
    fun validateConfiguration() {
        validateApiKeys()
        validateEndpoints()
        validateBusinessRules()
    }
    
    private fun validateApiKeys() {
        if (System.getenv("OPENAI_API_KEY").isNullOrBlank()) {
            throw IllegalStateException("OPENAI_API_KEY environment variable is required")
        }
    }
}

IDE Support

Auto-completion Configuration

Add to your src/main/resources/META-INF/spring-configuration-metadata.json:

{
  "properties": [
    {
      "name": "embabel.agent.logging.personality",
      "type": "java.lang.String",
      "description": "The personality theme for agent logging output",
      "defaultValue": "default",
      "hints": {
        "values": [
          {"value": "default", "description": "Standard Embabel logging"},
          {"value": "starwars", "description": "Star Wars themed logging"},
          {"value": "severance", "description": "Lumon Industries themed logging"},
          {"value": "hitchhiker", "description": "Hitchhiker's Guide themed logging"},
          {"value": "montypython", "description": "Monty Python themed logging"},
          {"value": "colossus", "description": "1970s sci-fi themed logging"}
        ]
      }
    },
    {
      "name": "embabel.agent.infrastructure.neo4j.enabled",
      "type": "java.lang.Boolean",
      "description": "Enable Neo4j integration for graph database functionality",
      "defaultValue": false
    }
  ]
}

IDE Auto-Completion Support

Enable IntelliJ IDEA and VS Code auto-completion for Embabel properties:

Add Configuration Processor

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

Rebuild and Restart IDE

  1. Clean and rebuild your project: mvn clean compile
  2. Restart your IDE to pick up the new configuration metadata
  3. Auto-completion works in application.yml and application.properties

Available Auto-Completions

  • embabel.agent.logging.personality - Dropdown with valid values (starwars, severance, etc.)
  • embabel.agent.infrastructure.neo4j.* - All Neo4j configuration options
  • embabel.agent.infrastructure.mcp.* - MCP server configuration
  • embabel.shell.* - Shell configuration options

Custom Configuration Metadata

Add your own auto-completion hints:

// src/main/resources/META-INF/additional-spring-configuration-metadata.json
{
  "properties": [
    {
      "name": "myapp.agent.timeout",
      "type": "java.time.Duration",
      "description": "Timeout for agent operations",
      "defaultValue": "30s"
    }
  ]
}

Troubleshooting Configuration

Common Issues

Property Not Being Applied

# Check property resolution
java -jar app.jar --debug

# Verify environment variables
env | grep EMBABEL

# Check Spring Boot configuration properties report
java -jar app.jar --spring.config.location=classpath:application.yml

Missing Required Properties

Error: Neo4j username must be provided when enabled

Solution:

export NEO4J_USERNAME=your_username
export NEO4J_PASSWORD=your_password

Profile Configuration Conflicts

WARN: DEPRECATED: Profile 'neo' is deprecated

Solution: Remove profile usage and migrate to property-based config:

# Remove:
spring:
  profiles:
    active: neo

# Replace with:
embabel:
  agent:
    infrastructure:
      neo4j:
        enabled: true

Configuration Debugging

Enable Configuration Logging

logging:
  level:
    org.springframework.boot.context.config: DEBUG
    org.springframework.core.env: DEBUG

Dump All Properties

# Add actuator dependency
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

# Enable configprops endpoint
management:
  endpoints:
    web:
      exposure:
        include: configprops

# View at: http://localhost:8080/actuator/configprops

Migration from Profile-Based Configuration

See PROFILES_MIGRATION_GUIDE.md for detailed migration instructions.

Quick Migration Summary

Old Profile New Property Description
spring.profiles.active=starwars embabel.agent.logging.personality=starwars Personality selection
spring.profiles.active=shell embabel.shell.enabled=true Shell activation
spring.profiles.active=neo embabel.agent.infrastructure.neo4j.enabled=true Neo4j integration
spring.profiles.active=docker-desktop embabel.agent.infrastructure.mcp.enabled=true MCP integration

Enable Migration Detection

# Enable comprehensive migration detection
export EMBABEL_AGENT_PLATFORM_MIGRATION_SCANNING_ENABLED=true

# Restart application to see migration warnings
java -jar app.jar

This will show warnings for any deprecated profile or property usage in your configuration.

For more configuration examples and patterns, see:

(c) Embabel Software Inc 2024-2025.

Clone this wiki locally