AI Agents Configuration Library
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.
Hire Me
Please send email if you consider hiring me.
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
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Run the test suite:
pytest - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - 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.pyfor 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.