Agent Configuration

The Don agent supports configuration through both configuration files and command-line flags. Configuration files provide a convenient way to manage multiple model configurations and default settings.

Configuration File

The agent looks for configuration in ~/.don/agent.yaml by default. This file defines model configurations, API keys, and default prompts.

Configuration File Location

The agent configuration file location is determined by the following precedence:

1. DON_AGENT_CONFIG environment variable (if set) - Allows you to specify a custom path
2. Default location: ~/.don/agent.yaml

Example: Using a custom configuration file

# Use a project-specific agent configuration
export DON_AGENT_CONFIG="/path/to/my-project/agent.yaml"
don agent --tools=tools.yaml

# Or set it inline for a single command
DON_AGENT_CONFIG="./custom-agent.yaml" don agent --tools=tools.yaml

This is particularly useful for:

• Testing different agent configurations
• Using project-specific agent settings
• Running multiple agents with different configurations
• CI/CD environments where you want to use a specific config file

Configuration Structure

agent:
  models:
    - model: "gpt-4o"
      class: "openai"
      name: "GPT-4o Agent"
      default: true
      api-key: "${OPENAI_API_KEY}"
      api-url: "https://api.openai.com/v1"
      prompts:
        system:
          - "You are a helpful assistant specialized in system administration."
          - "Always provide clear, step-by-step instructions."

    - model: "gpt-3.5-turbo"
      class: "openai"
      name: "GPT-3.5 Agent"
      default: false
      api-key: "${OPENAI_API_KEY}"
      api-url: "https://api.openai.com/v1"
      prompts:
        system: "You are a helpful assistant."

    - model: "llama3"
      class: "ollama"
      name: "Llama3 Local"
      default: false
      prompts:
        system:
          - "You are a helpful assistant running locally."
          - "Be concise in your responses."

Model Configuration Fields

• model: The model identifier (e.g., "gpt-4o", "gpt-3.5-turbo")
• class: The model provider class ("openai", "ollama", etc.)
• name: A human-readable name for the model configuration
• default: Boolean indicating if this is the default model
• api-key: API key for the model provider (supports environment variable substitution)
• api-url: Base URL for the API endpoint
• prompts.system: Default system prompt for this model (can be a single string or array of strings)

Environment Variable Substitution

API keys support environment variable substitution using the ${VARIABLE_NAME} syntax:

api-key: "${OPENAI_API_KEY}"

Prompt Configuration

The prompts.system field in the configuration accepts either a single string or an array of strings:

# Single system prompt
prompts:
  system: "You are a helpful assistant."

# Multiple system prompts (array format)
prompts:
  system:
    - "You are a helpful assistant."
    - "You specialize in system administration."
    - "Always explain your reasoning."

Important: Only system prompts are supported in the configuration file. User prompts should be provided via the --user-prompt command-line flag and are not stored in the configuration.

System Prompt Merging: When you use the --system-prompt command-line flag, it will be appended to any system prompts defined in the configuration file. This allows you to have base prompts in your config and add context-specific prompts via the command line.

Command-Line Usage

Using Default Model

If you have a default model configured, you can run the agent without specifying a model:

don agent --tools=examples/config.yaml \
    --user-prompt "Help me debug a performance issue"

Overriding Model

You can override the default model by specifying a different one:

don agent --tools=examples/config.yaml \
    --model "gpt-3.5-turbo" \
    --user-prompt "Help me debug a performance issue"

Overriding Configuration

Command-line flags take precedence over configuration file settings:

don agent --tools=examples/config.yaml \
    --model "gpt-4o" \
    --system-prompt "You are an expert system administrator" \
    --openai-api-key "your-api-key" \
    --user-prompt "Help me debug a performance issue"

Note: When you provide a --system-prompt via command line, it will be merged with any system prompts from the configuration file. The system prompts from the config are used first, followed by the command-line system prompt.

Configuration Precedence

Settings are resolved in the following order (highest to lowest precedence):

1. Command-line flags (--model, --openai-api-key, etc.)
2. Environment variables (DON_AGENT_MODEL, OPENAI_API_KEY, etc.)
3. Configuration file settings
4. Default values

Environment Variables

The following environment variables are supported:

• DON_AGENT_MODEL: Default model to use when --model flag is not provided
• OPENAI_API_KEY: OpenAI API key (can be referenced in config with ${OPENAI_API_KEY})

Example:

export DON_AGENT_MODEL="gpt-4o"
don agent --tools=examples/config.yaml \
    --user-prompt "Help me debug a performance issue"

Configuration Management Commands

Don provides commands to manage your agent configuration:

Create Default Configuration

don agent config create

Creates a default configuration file at ~/.don/agent.yaml with sample models and settings. If the file already exists, it will be overwritten with the default configuration template.

The default configuration includes:

• GPT-4o model (set as default) with OpenAI API settings
• Gemma3n model with Ollama configuration
• Environment variable placeholders for API keys
• Basic system prompts

Show Current Configuration

don agent config show [--json]

Displays the current agent configuration in a human-readable format, including:

• All configured models with their settings
• API keys (masked for security)
• Which model is set as default
• System prompts for each model

Flags:

• --json: Output configuration in JSON format for easy parsing by other tools

Example (human-readable):

don agent config show

Agent Configuration:
===================

Model 1:
  Name: GPT-4o Agent
  Model: gpt-4o
  Class: openai
  Default: true
  API Key: your****-key
  API URL: https://api.openai.com/v1
  System Prompt: You are a helpful assistant.

Default Model: GPT-4o Agent (gpt-4o)

Environment Variables

Don agent supports various environment variables for configuration. The most commonly used are:

• DON_AGENT_CONFIG - Custom agent configuration file path (default: ~/.don/agent.yaml)
• DON_AGENT_MODEL - Default LLM model to use
• OPENAI_API_KEY - OpenAI API key for authentication
• OPENAI_API_URL - OpenAI API base URL (for Azure or custom endpoints)
• DON_DIR - Custom Don home directory (default: ~/.don)
• DON_TOOLS_DIR - Custom tools directory (default: ~/.don/tools)
• DON_RAG_CACHE_DIR - Custom RAG cache directory

📖 For complete environment variables documentation, including:

• All supported environment variables across all modes
• Default values and precedence rules
• Platform-specific variables (Windows, Linux, macOS)
• Security best practices
• CI/CD configuration examples

See the Environment Variables Reference

Quick Examples

# Use a custom agent configuration file
export DON_AGENT_CONFIG="/path/to/custom/agent.yaml"
don agent --tools=tools.yaml

# Set default model via environment variable
export DON_AGENT_MODEL="gpt-4o"
don agent --tools=tools.yaml

# Use custom RAG cache directory
export DON_RAG_CACHE_DIR="/fast/ssd/rag-cache"
don agent --tools=tools.yaml --rag=docs

Configuration Precedence

When the agent loads configuration, it follows this precedence order (highest to lowest):

1. Command-line flags (e.g., --model, --api-key, --system-prompt)
2. Agent configuration file (specified by DON_AGENT_CONFIG or default location)
3. Environment variables (e.g., OPENAI_API_KEY referenced in config via ${OPENAI_API_KEY})

This allows you to:

• Define base configuration in the config file
• Override specific settings via command-line flags
• Use environment variables for sensitive data like API keys