Skip to main content

AI Agents Configuration Library

I stand with Israel

A robust Python library for managing AI agent configurations with Pydantic validation, environment variable substitution, and internal reference resolution. Perfect for building scalable AI applications with complex tool integrations and deployment flexibility.

Python 3.12+ Pydantic V2 License: MIT

Hire Me

Please send email if you consider hiring me.

buymeacoffee

Give a Star! ⭐

If you like or are using this project to learn or start your solution, please give it a star. Thanks!

🚀 Quick Start

Installation

# Install with uv (recommended)
uv add agents-config

# Or with pip
pip install agents-config

# Install development version from GitHub
pip install git+https://github.com/kdcllc/agents_config.git

# For development work
git clone https://github.com/kdcllc/agents_config.git
cd agents_config
uv sync --all-extras

Basic Usage

from agents_config.config_loader import ConfigLoader

# Load configuration from YAML file
config = ConfigLoader.load_from_file("ai-config.yaml")

# Access models, agents, and tools
model = config.get_model("gpt-4")
agent = config.get_agent("search-agent")
print(f"Agent: {agent.description}")

Run the Demo

# See the library in action
uv run main.py

# Or with python
python main.py

🎯 Key Features

  • 🔧 Pydantic V2 Validation: Type-safe configuration with automatic validation
  • 🌍 Environment Variables: ${env:VAR_NAME} substitution for secrets and deployment configs
  • 🔗 Internal References: ${ref:path.to.value} resolution for DRY configurations
  • 🛠️ Multi-Tool Support: OpenAPI tools, Azure AI Foundry agents, custom integrations
  • 📦 Flexible Models: Support for Azure OpenAI, OpenAI, Ollama, and custom providers
  • ✅ Cross-Reference Validation: Ensures agents reference valid models and tools
  • 🔄 Programmatic Configuration: Create configs in code or load from YAML

📖 Configuration Structure

YAML Configuration Example

version: '1.0'

# Models define AI providers and their configurations
models:
  gpt-4:
    provider: azure_openai
    id: gpt-4-turbo
    version: '1.0'
    config:
      api_key: ${env:AZURE_OPENAI_KEY}
      endpoint: ${env:AZURE_OPENAI_ENDPOINT}
      deployment: my-deployment
    params:
      temperature: 0.7
      max_tokens: 4096

# Tools define external integrations
tools:
  ai_foundry:
    default_project_endpoint: ${env:AZURE_AI_FOUNDRY_ENDPOINT}
    tools:
      search_tool:
        version: '1.0'
        type: bing
        description: 'Web search via Azure AI Foundry'
        connection_ids:
          - ${env:BING_CONNECTION_ID}
        config:
          project_endpoint: ${ref:tools.ai_foundry.default_project_endpoint}

# Agents combine models and tools for specific tasks
agents:
  search-agent:
    version: '1.0'
    name: 'Search Agent'
    description: 'AI agent for web searches'
    model:
      name: gpt-4
      temperature: 0.5
    tools:
      - ${ref:tools.ai_foundry.tools.search_tool}
    platform: azure_openai
    system_prompt:
      version: '1.0'
      path: prompts/search-agent.md

🔧 Core Components

1. ConfigLoader

The main entry point for loading and validating configurations.

from agents_config.config_loader import ConfigLoader

# Load from YAML file
config = ConfigLoader.load_from_file("config.yaml")

# Load from dictionary
config_dict = {"version": "1.0", "models": {...}}
config = ConfigLoader.load_from_dict(config_dict)

# Validate environment variables
missing_vars = ConfigLoader.validate_environment_variables(config)
if missing_vars:
    print(f"Missing environment variables: {missing_vars}")

# Create example configuration
ConfigLoader.save_example_config("example-config.yaml")

2. Environment Variable Substitution

Automatically resolves ${env:VAR_NAME} patterns in your configuration:

models:
  gpt-4:
    config:
      api_key: ${env:AZURE_OPENAI_KEY} # → Resolves to actual API key
      endpoint: ${env:AZURE_OPENAI_ENDPOINT} # → Resolves to actual endpoint
import os
os.environ["AZURE_OPENAI_KEY"] = "your-api-key"
os.environ["AZURE_OPENAI_ENDPOINT"] = "https://your-endpoint.com"

config = ConfigLoader.load_from_file("config.yaml")
# Environment variables are automatically resolved

3. Internal Reference Resolution

Use ${ref:path.to.value} to reference other parts of your configuration:

shared_config:
  database_url: 'postgresql://localhost:5432/mydb'
  timeout: 30

models:
  gpt-4:
    config:
      database_url: ${ref:shared_config.database_url} # → References shared value
      timeout: ${ref:shared_config.timeout} # → References shared value

4. Working with Models

# Get all available models
model_names = config.list_models()

# Get specific model
model = config.get_model("gpt-4")
if model:
    print(f"Provider: {model.provider}")
    print(f"ID: {model.id}")
    print(f"Config: {model.config}")
    print(f"Parameters: {model.params}")

5. Working with Agents

# Get all available agents
agent_names = config.list_agents()

# Get specific agent
agent = config.get_agent("search-agent")
if agent:
    print(f"Name: {agent.name}")
    print(f"Description: {agent.description}")
    print(f"Model: {agent.model.name}")
    print(f"Tools: {agent.tools}")
    print(f"System Prompt: {agent.system_prompt.path}")

6. Tool Configuration

OpenAPI Tools

tools:
  openapi:
    weather_api:
      schema_path: 'tools/openapi/weather.json'
      version: '1.0'
      headers:
        Authorization: ${env:WEATHER_API_KEY}
        Content-Type: 'application/json'

Azure AI Foundry Tools

tools:
  ai_foundry:
    default_project_endpoint: ${env:AZURE_AI_FOUNDRY_ENDPOINT}
    tools:
      bing_search:
        version: '1.0'
        type: bing
        description: 'Bing search integration'
        connection_ids:
          - ${env:BING_CONNECTION_ID}
        config:
          project_endpoint: ${ref:tools.ai_foundry.default_project_endpoint}

🏗️ Programmatic Configuration

Create configurations in code for dynamic setups:

from agents_config.ai_config import AIConfig
from agents_config.model_config import ModelConfig
from agents_config.agent_config import AgentConfig

# Create model configuration
model = ModelConfig(
    provider="azure_openai",
    id="gpt-4",
    version="1.0",
    config={
        "api_key": "your-api-key",
        "endpoint": "https://your-endpoint.com",
        "deployment": "gpt-4-deployment"
    },
    params={
        "temperature": 0.7,
        "max_tokens": 4000
    }
)

# Create agent configuration
agent = AgentConfig(
    version="1.0",
    name="My Agent",
    description="A programmatically created agent",
    model={"name": "gpt-4", "temperature": 0.5},
    tools=[],
    platform="azure_openai",
    system_prompt={
        "version": "1.0",
        "path": "prompts/my-agent.md"
    }
)

# Create full configuration
config = AIConfig(
    version="1.0",
    models={"gpt-4": model},
    tools={},
    agents={"my-agent": agent}
)

🔍 Validation and Error Handling

The library provides comprehensive validation with clear error messages:

try:
    config = ConfigLoader.load_from_file("config.yaml")
except ValueError as e:
    print(f"Configuration validation failed: {e}")
    # Shows detailed validation errors:
    # - Missing required fields
    # - Invalid data types
    # - Cross-reference validation failures

Example validation error output:

Configuration validation failed: 6 validation errors for AIConfig
models.gpt-4.version
  Field required [type=missing, input_value={'provider': 'azure_openai'...}, input_type=dict]
models.gpt-4.config
  Input should be a valid dictionary [type=dict_type, input_value='not_a_dict', input_type=str]
agents.my-agent.system_prompt
  Field required [type=missing, input_value={'name': 'My Agent'...}, input_type=dict]

🌍 Environment Variables

Required Environment Variables

Set these environment variables for the example configuration:

# Azure OpenAI
export AZURE_OPENAI_KEY="your-azure-openai-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"

# Azure AI Foundry
export AZURE_AI_FOUNDRY_PROJECT_ENDPOINT="https://your-project.azure.ai/"

# Tool Connections
export BING_SEARCH_CONNECTION_ID="your-bing-connection-id"
export OPOINT_API_CONNECTION_ID="your-opoint-connection-id"
export OPENAPI_OPOINT_API_KEY="your-opoint-api-key"

Environment Variable Validation

# Check for missing environment variables before deployment
missing_vars = ConfigLoader.validate_environment_variables(config)
if missing_vars:
    raise EnvironmentError(f"Missing required environment variables: {missing_vars}")

📁 Project Structure

agents-config/ ├── app/ │ ├── agents_config/ # Main library package │ │ ├── init.py │ │ ├── ai_config.py # Main configuration class │ │ ├── agent_config.py # Agent configuration models │ │ ├── base.py # Base mixins for env/ref resolution │ │ ├── config_loader.py # Configuration loading utilities │ │ ├── config_models.py # Common configuration models │ │ ├── model_config.py # AI model configuration │ │ └── tool_config.py # Tool configuration models │ └── ai-config/ # Example configuration │ ├── ai-config.yaml # Main configuration file │ ├── prompts/ # System prompt templates │ └── tools/ # Tool schema definitions ├── main.py # Demo script ├── pyproject.toml # Project configuration └── README.md # This file

## 🛠️ Advanced Usage

### Custom Tool Integration

```python
from agents_config.tool_config import ToolsConfig

# Define custom tools
custom_tools = ToolsConfig(
    openapi={
        "my_api": {
            "schema_path": "tools/my_api.json",
            "version": "1.0",
            "headers": {
                "Authorization": "${env:MY_API_KEY}"
            }
        }
    }
)

Multi-Environment Configuration

# config/production.yaml
version: '1.0'
models:
  gpt-4:
    config:
      endpoint: ${env:PROD_OPENAI_ENDPOINT}
      api_key: ${env:PROD_OPENAI_KEY}

# config/development.yaml
version: '1.0'
models:
  gpt-4:
    config:
      endpoint: ${env:DEV_OPENAI_ENDPOINT}
      api_key: ${env:DEV_OPENAI_KEY}
import os

# Load environment-specific configuration
env = os.getenv("ENVIRONMENT", "development")
config_path = f"config/{env}.yaml"
config = ConfigLoader.load_from_file(config_path)

Configuration Composition

# Base configuration
base_config = ConfigLoader.load_from_file("base-config.yaml")

# Environment-specific overrides
env_config = ConfigLoader.load_from_file(f"config/{env}.yaml")

# Merge configurations (implement your merge logic)
final_config = merge_configurations(base_config, env_config)

🧪 Testing

import pytest
from agents_config.config_loader import ConfigLoader

def test_configuration_loading():
    """Test that configuration loads successfully."""
    config = ConfigLoader.load_from_file("test-config.yaml")
    assert config.version == "1.0"
    assert "gpt-4" in config.models
    assert len(config.agents) > 0

def test_environment_variable_substitution():
    """Test environment variable resolution."""
    import os
    os.environ["TEST_API_KEY"] = "test-key-123"

    config_dict = {
        "version": "1.0",
        "models": {
            "test-model": {
                "provider": "azure_openai",
                "config": {"api_key": "${env:TEST_API_KEY}"}
            }
        }
    }

    config = ConfigLoader.load_from_dict(config_dict)
    model = config.get_model("test-model")
    assert model.config["api_key"] == "test-key-123"

🚀 Deployment

Docker Integration

FROM python:3.12-slim

# Install dependencies
COPY pyproject.toml .
RUN pip install -e .

# Copy configuration
COPY config/ /app/config/
COPY prompts/ /app/prompts/

# Set environment variables
ENV ENVIRONMENT=production
ENV AZURE_OPENAI_ENDPOINT=https://your-endpoint.com

# Run your application
CMD ["python", "your_app.py"]

Kubernetes Configuration

apiVersion: v1
kind: ConfigMap
metadata:
  name: ai-config
data:
  ai-config.yaml: |
    version: '1.0'
    models:
      gpt-4:
        provider: azure_openai
        config:
          endpoint: ${env:AZURE_OPENAI_ENDPOINT}
          api_key: ${env:AZURE_OPENAI_KEY}
---
apiVersion: v1
kind: Secret
metadata:
  name: ai-secrets
data:
  AZURE_OPENAI_KEY: <base64-encoded-key>
  AZURE_OPENAI_ENDPOINT: <base64-encoded-endpoint>

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Run the test suite: pytest
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

  • Issues: GitHub Issues
  • Documentation: This README and inline code documentation
  • Examples: See main.py for comprehensive usage examples

🔄 Changelog

v0.1.0

  • Initial release
  • Pydantic V2 configuration models
  • Environment variable substitution
  • Internal reference resolution
  • OpenAPI and Azure AI Foundry tool support
  • Comprehensive validation and error handling

Built with ❤️ for the AI development community

Metadata

Release files for agents-config 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agents-config 0.2.0
File Size Uploaded Provenance Actions
agents_config-0.2.0.tar.gz 24.8 kB With provenance Details for agents_config-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agents-config 0.2.0
File Interpreter ABI Platform Actions
agents_config-0.2.0-py3-none-any.whl Python 3 none any Details for agents_config-0.2.0-py3-none-any.whl

Total release size: 50.5 kB

Release files / agents_config-0.2.0.tar.gz

Download URL agents_config-0.2.0.tar.gz
Size 24.8 kB
Tags Source
SHA-256 checksum
How to use checksums
50e1cd490ba552f250ed7aae28cb2758eaacf388e4af50b8cdf4249cd20cf886
BLAKE2b-256 checksum
How to use checksums
689787e6a644f8ea06bed25b3b8b1761e73b86f4af01c5a2bb68631476515940
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 26, 2025.

Transparency log

Release files / agents_config-0.2.0-py3-none-any.whl

Download URL agents_config-0.2.0-py3-none-any.whl
Size 25.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
83a3a59c75504a86b5d74bbc7c8f0569b1cc79efbf310448de7cd7ae23fb6883
BLAKE2b-256 checksum
How to use checksums
3e54fe994bba170adf5e96ded2ea4f1b24bad58a996f8e7b832c363b4c5d1309
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 26, 2025.

Transparency log

Security for agents-config 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agents_config-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 26, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page