LLM Configuration

Agent Air loads LLM provider configuration from a YAML file or environment variables. The YAML file takes precedence when it exists and contains valid provider definitions.

Configuration File Location

The configuration file path is specified by config_path() in your AgentConfig implementation:

fn config_path(&self) -> &str {
    "~/.myagent/config.yaml"
}

Paths starting with ~/ are expanded to the user’s home directory. The framework does not create the configuration directory or file automatically. If the path does not exist, the framework falls back to environment variables.

YAML File Format

The configuration file has two top-level fields:

providers:
  - provider: anthropic
    api_key: sk-ant-...
    model: claude-sonnet-4-20250514

  - provider: openai
    api_key: sk-...
    model: gpt-4-turbo-preview

default_provider: anthropic

providers (required)

An array of provider configurations. Each entry requires:

• provider: The provider identifier (see Supported Providers below)
• api_key: Authentication key for the provider API
• model: Model identifier to use for requests (optional for some providers)

default_provider (optional)

Specifies which provider to use when no specific provider is requested. If omitted, the first provider in the list becomes the default.

Supported Providers

Native Providers

These providers have dedicated implementations with full feature support:

OpenAI-Compatible Providers

These providers use the OpenAI API format and are automatically configured with appropriate defaults:

Local Providers

These providers run locally and do not require API keys:

Configuration Examples

Single Provider

providers:
  - provider: anthropic
    api_key: sk-ant-api03-xxxxx
    model: claude-sonnet-4-20250514

Multiple Providers

providers:
  - provider: anthropic
    api_key: sk-ant-api03-xxxxx
    model: claude-sonnet-4-20250514

  - provider: groq
    api_key: gsk_xxxxx
    model: llama-3.3-70b-versatile

default_provider: anthropic

Local Provider

providers:
  - provider: ollama
    api_key: ""
    model: llama3.1

For local providers, the api_key field can be empty but must be present.

Environment Variables

When no YAML configuration file exists or when it is empty, the framework falls back to environment variables. Set the appropriate API key variable to enable a provider.

Native Providers

OpenAI-Compatible Providers

Local Providers

Setting the host variable enables the local provider. No API key is required.

Precedence

Environment variables are only used when:

• The YAML config file does not exist
• The YAML config file cannot be read
• The YAML config file contains no providers

If the YAML file contains valid provider configuration, environment variables are ignored. There is no merging of configuration sources.

When multiple API keys are set via environment variables, the default provider is selected in this order: Anthropic, OpenAI, Google, then OpenAI-compatible providers.

Available Models

Anthropic

OpenAI

Google

Groq

For other OpenAI-compatible providers, refer to the provider’s documentation for available models.

Model-Specific Capabilities

Some features vary by model:

Streaming support:

• Anthropic: Enabled by default
• OpenAI: Disabled by default (can be enabled)
• Google: Enabled by default
• OpenAI-compatible: Varies by provider

Tool use:

• Most modern models support tool use (function calling)
• Check provider documentation for specific model capabilities

Model identifiers are not validated by the framework. Invalid model names result in errors from the provider API when making requests.

API Key Security

File Permissions

Restrict access to configuration files containing API keys:

chmod 600 ~/.myagent/config.yaml

Do Not Commit Keys

Add configuration files to .gitignore:

# Agent configuration with API keys
.myagent/config.yaml
config.yaml

Production Deployments

For production, prefer environment variables or secrets management systems:

• Container orchestration (Kubernetes secrets, Docker secrets)
• Cloud provider secrets managers (AWS Secrets Manager, GCP Secret Manager)
• CI/CD pipeline secrets
• Process managers (systemd environment files)

Key Formats

Error Handling

Configuration errors are represented by ConfigError:

When configuration loading fails, the framework logs a warning and the agent starts without LLM capabilities.

Changing Configuration

Configuration is loaded once at startup. To change providers, models, or API keys:

1. Update the YAML configuration file or environment variable
2. Restart the agent