Config Components - Ensemble Edge

Define and version reusable configuration objects as components for consistent settings across ensembles.

Overview

Config components enable you to:

Centralize settings used across multiple agents and ensembles
Version configurations for reproducibility and rollback
Manage secrets securely in KV storage
Test different configurations with version tags
A/B test different settings

Quick Start

1. Create a Config Component

Create a JSON configuration file:

// configs/anthropic-settings.json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4",
  "temperature": 0.2,
  "max_tokens": 2048,
  "top_p": 0.95,
  "timeout": 30
}

2. Add to Edgit

edgit components add anthropic-settings configs/anthropic-settings.json config
edgit tag create anthropic-settings v1.0.0
edgit tag set anthropic-settings production v1.0.0
edgit push --tags --force

3. Reference in Your Ensemble

ensemble: text-processor

agents:
  - name: process
    operation: think
    # Reference the config component
    config: "config://[email protected]"
    prompt: |
      Process the following text: ${input.text}

inputs:
  text:
    type: string

outputs:
  result: ${process.output}

URI Format and Versioning

All config components use the standardized URI format:

config://{path}[@{version}]

Format breakdown:

config:// - Protocol identifier for config components
{path} - Logical path to the config (e.g., anthropic-settings, providers/openai)
[@{version}] - Optional version identifier (defaults to @latest)

Version format:

@latest - Always uses the most recent version
@v1 - Uses latest patch of major version (v1.x.x)
@v1.0.0 - Specific semantic version (immutable)
@prod - Custom tag for production versions
@staging - Custom tag for staging versions

Example URIs

# Always latest version
config: "config://anthropic-settings"
config: "config://anthropic-settings@latest"

# Specific semantic version
config: "config://[email protected]"
config: "config://[email protected]"

# Custom tags
config: "config://anthropic-settings@prod"
config: "config://anthropic-settings@staging"

# Nested paths
config: "config://providers/anthropic@v1"
config: "config://model-settings/gpt4@v1"

How to Reference in Ensembles

There are three ways to reference configs in your ensembles:

1. URI Format (Recommended)

Use the config:// URI format to reference versioned config components:

ensemble: blog-analyzer

agents:
  - name: analyze
    operation: think
    config: "config://[email protected]"
    prompt: "Analyze this blog post: ${input.post}"

inputs:
  post:
    type: string

outputs:
  analysis: ${analyze.output}

2. Template Expression Format

Use ${components.config_name@version} to embed config references in YAML:

ensemble: dynamic-config

agents:
  - name: process
    operation: think
    config:
      # Spread config component
      provider: ${[email protected]}
      model: ${[email protected]}
      temperature: ${[email protected]}
      # Override specific fields
      max_tokens: 1024
      timeout: 30
    prompt: "Process: ${input.data}"

inputs:
  data:
    type: string

outputs:
  result: ${process.output}

3. Inline Config

For simple operations or during development, use inline config objects directly:

ensemble: simple-analyzer

agents:
  - name: analyze
    operation: think
    config:
      provider: anthropic
      model: claude-sonnet-4
      temperature: 0.3
      max_tokens: 2048
    prompt: "Analyze this: ${input.text}"

inputs:
  text:
    type: string

outputs:
  analysis: ${analyze.output}

Using Config Components

Multiple Agents with Different Configs

ensemble: multi-model-analysis

agents:
  - name: analyze-text
    operation: think
    config: "config://anthropic-settings@v1"
    prompt: "Analyze text: ${input.text}"

  - name: analyze-with-gpt
    operation: think
    config: "config://openai-settings@v1"
    prompt: "Analyze text: ${input.text}"

  - name: analyze-with-llama
    operation: think
    config: "config://llama-settings@v1"
    prompt: "Analyze text: ${input.text}"

inputs:
  text:
    type: string

outputs:
  anthropic_result: ${analyze-text.output}
  openai_result: ${analyze-with-gpt.output}
  llama_result: ${analyze-with-llama.output}

Config Types and Examples

AI Provider Settings

// configs/anthropic-settings.json
{
  "provider": "anthropic",
  "model": "claude-opus-4",
  "temperature": 0.3,
  "max_tokens": 4096,
  "top_p": 0.98,
  "timeout": 60,
  "system_prompt_prefix": "You are an expert analyst."
}

API Configuration

// configs/data-api.json
{
  "base_url": "https://api.data-provider.com",
  "timeout": 30,
  "retry_attempts": 3,
  "retry_delay_ms": 1000,
  "headers": {
    "Accept": "application/json",
    "User-Agent": "Conductor/1.0"
  }
}

Database Connection Settings

// configs/postgres-prod.json
{
  "engine": "postgres",
  "host": "db.example.com",
  "port": 5432,
  "database": "production",
  "pool_size": 10,
  "max_lifetime": 3600,
  "timeout": 30
}

Processing Parameters

// configs/document-processing.json
{
  "chunk_size": 2048,
  "overlap": 256,
  "use_streaming": true,
  "cache_embeddings": true,
  "batch_size": 100,
  "max_parallel": 5
}

Feature Flags

// configs/feature-flags.json
{
  "enable_advanced_analytics": true,
  "enable_caching": true,
  "enable_logging": true,
  "debug_mode": false,
  "use_legacy_api": false,
  "enable_telemetry": true
}

Caching and Performance

Config components are automatically cached for 1 hour (3600 seconds) after first load.

Default Caching

agents:
  - name: analyze
    operation: think
    config: "config://anthropic-settings@v1"
    # Cached for 1 hour automatically

Custom Cache TTL

agents:
  - name: analyze
    operation: think
    config: "config://anthropic-settings@v1"
    cache:
      ttl: 86400  # 24 hours in seconds

Bypass Cache

agents:
  - name: analyze
    operation: think
    config: "config://anthropic-settings@v1"
    cache:
      bypass: true  # Fresh load every time

Best Practices

1. Version All Configurations

Use semantic versioning:

edgit tag create anthropic-settings v1.0.0
edgit tag create anthropic-settings v1.1.0
edgit tag create anthropic-settings v2.0.0

2. Use Semantic Versioning

PATCH (v1.0.1): Bug fixes, non-breaking adjustments
MINOR (v1.1.0): New optional features, compatible changes
MAJOR (v2.0.0): Breaking changes, incompatible updates

// v1.0.0 - Initial release
{"temperature": 0.2, "max_tokens": 2048}

// v1.1.0 - Add new field (compatible)
{"temperature": 0.2, "max_tokens": 2048, "top_p": 0.95}

// v2.0.0 - Remove field (breaking)
{"temperature": 0.3, "max_tokens": 4096}

3. Separate By Concern

Organize configs by their purpose:

configs/
├── providers/
│   ├── anthropic-prod.json
│   ├── anthropic-staging.json
│   ├── openai-prod.json
│   └── openai-staging.json
├── databases/
│   ├── postgres-prod.json
│   ├── postgres-staging.json
│   ├── redis-prod.json
│   └── redis-staging.json
└── features/
    ├── feature-flags.json
    └── processing-params.json

3. Create Environment-Specific Versions

// configs/anthropic-prod.json
{
  "provider": "anthropic",
  "model": "claude-opus-4",
  "temperature": 0.2,
  "max_tokens": 4096,
  "timeout": 60
}

// configs/anthropic-dev.json
{
  "provider": "anthropic",
  "model": "claude-haiku-4",
  "temperature": 0.5,
  "max_tokens": 1024,
  "timeout": 30
}

4. Document Configuration Fields

// configs/api-settings.json
{
  "base_url": "https://api.example.com",                    // API endpoint URL
  "timeout": 30,                                            // Request timeout in seconds
  "retry_attempts": 3,                                      // Number of retries on failure
  "retry_delay_ms": 1000,                                   // Delay between retries
  "cache_responses": true,                                  // Cache successful responses
  "max_payload_size": 10485760                              // Max payload size (10MB)
}

5. Use Descriptive Names

# Good: Clear what the config is for
edgit components add anthropic-prod configs/anthropic-prod.json config
edgit components add postgres-staging configs/postgres-staging.json config

# Bad: Unclear purpose
edgit components add settings1 configs/settings1.json config
edgit components add config2 configs/config2.json config

6. Handle Sensitive Values

For secrets, store in KV with appropriate access controls:

# Don't include secrets in JSON
# Instead, reference them at runtime or use secure KV storage
edgit secrets set DB_PASSWORD "your-password"

// configs/secure-api.json
{
  "api_endpoint": "https://api.example.com",
  "timeout": 30,
  "use_auth": true,
  "auth_type": "bearer_token"
  // Password/tokens stored separately in KV
}

Versioning Strategy

Development Workflow

# 1. Create base version
edgit tag create anthropic-settings v1.0.0

# 2. Test and iterate
edgit tag create anthropic-settings v1.1.0
edgit tag create anthropic-settings v1.2.0

# 3. Promote to production
edgit tag set anthropic-settings production v1.2.0

Staged Rollout

ensemble: api-processor-v1

agents:
  - name: process
    operation: think
    config: "config://anthropic-settings@staging"
    # Test new config in staging ensemble

ensemble: api-processor-prod

agents:
  - name: process
    operation: think
    config: "config://anthropic-settings@production"
    # Use stable config in production

A/B Testing Configs

ensemble: config-comparison

agents:
  - name: process-v1
    operation: think
    config: "config://[email protected]"
    prompt: "Process: ${input.text}"

  - name: process-v2
    operation: think
    config: "config://[email protected]"
    prompt: "Process: ${input.text}"

outputs:
  version_1: ${process-v1.output}
  version_2: ${process-v2.output}

Using ctx API in Agents

When building custom agents with TypeScript handlers, you can access configs through the ctx API:

ctx.configs.get(name)

Get a configuration object by name:

// agents/processor/index.ts
import type { AgentExecutionContext } from '@ensemble-edge/conductor'

export default async function process(ctx: AgentExecutionContext) {
  // Get config by name
  const aiConfig = await ctx.configs.get('anthropic-settings')

  return {
    provider: aiConfig.provider,
    model: aiConfig.model,
    temperature: aiConfig.temperature
  }
}

Using Config for API Calls

// agents/ai-caller/index.ts
import type { AgentExecutionContext } from '@ensemble-edge/conductor'
import Anthropic from '@anthropic-ai/sdk'

interface ProcessInput {
  text: string
}

export default async function callAI(ctx: AgentExecutionContext) {
  const { text } = ctx.input as ProcessInput

  // Get AI config
  const config = await ctx.configs.get('anthropic-settings')

  // Use config for API call
  const client = new Anthropic({
    apiKey: ctx.env.ANTHROPIC_API_KEY
  })

  const response = await client.messages.create({
    model: config.model,
    max_tokens: config.max_tokens,
    temperature: config.temperature,
    messages: [{ role: 'user', content: text }]
  })

  return {
    result: response.content[0].type === 'text' ? response.content[0].text : '',
    config_used: {
      model: config.model,
      temperature: config.temperature
    }
  }
}

Dynamic Config Selection

// agents/multi-provider/index.ts
import type { AgentExecutionContext } from '@ensemble-edge/conductor'

export default async function processWithProvider(ctx: AgentExecutionContext) {
  const { provider, text } = ctx.input as {
    provider: 'anthropic' | 'openai' | 'cloudflare'
    text: string
  }

  // Load config based on provider
  const configName = `${provider}-settings`
  const config = await ctx.configs.get(configName)

  return {
    provider,
    config,
    ready: true
  }
}

Environment-Based Config

// agents/env-aware/index.ts
import type { AgentExecutionContext } from '@ensemble-edge/conductor'

export default async function process(ctx: AgentExecutionContext) {
  // Load different config based on environment
  const env = ctx.env.ENVIRONMENT || 'production'
  const configName = `api-settings-${env}`

  const config = await ctx.configs.get(configName)

  return {
    environment: env,
    config,
    baseUrl: config.base_url,
    timeout: config.timeout
  }
}

Merging Configs

// agents/config-merger/index.ts
import type { AgentExecutionContext } from '@ensemble-edge/conductor'

export default async function mergeConfigs(ctx: AgentExecutionContext) {
  // Get multiple configs and merge
  const baseConfig = await ctx.configs.get('base-ai-config')
  const overrideConfig = await ctx.configs.get('production-overrides')

  const merged = {
    ...baseConfig,
    ...overrideConfig
  }

  return {
    config: merged,
    base: baseConfig,
    overrides: overrideConfig
  }
}

Troubleshooting

Config Not Found

Error: Component not found: config://[email protected] Solution:

Check config exists: edgit list configs
Check version: edgit tag list anthropic-settings
Verify deployment: edgit tag show [email protected]

Invalid Configuration

Error: JSON parse error when loading config Solution:

Validate JSON: jsonlint configs/anthropic-settings.json
Check for required fields
Verify format matches expected schema

Configuration Mismatch

Issue: Agent doesn’t recognize config fields Solution:

Check agent documentation for supported fields
Verify config format matches agent requirements
Test with inline config first

Next Steps

Prompt Components

Reusable AI instructions

Query Components

SQL queries as components

Think Operation

AI reasoning operations

Edgit Versioning

Version control for components

Conductor

Getting Started

Core Concepts

Building

Components

Operations Reference

Plugins

Starter Kit

Playbooks

Reference

​Overview

​Quick Start

​1. Create a Config Component

​2. Add to Edgit

​3. Reference in Your Ensemble

​URI Format and Versioning

​Example URIs

​How to Reference in Ensembles

​1. URI Format (Recommended)

​2. Template Expression Format

​3. Inline Config

​Using Config Components

​Multiple Agents with Different Configs

​Config Types and Examples

​AI Provider Settings

​API Configuration

​Database Connection Settings

​Processing Parameters

​Feature Flags

​Caching and Performance

​Default Caching

​Custom Cache TTL

​Bypass Cache

​Best Practices

​1. Version All Configurations

​2. Use Semantic Versioning

​3. Separate By Concern

​3. Create Environment-Specific Versions

​4. Document Configuration Fields

​5. Use Descriptive Names

​6. Handle Sensitive Values

​Versioning Strategy

​Development Workflow

​Staged Rollout

​A/B Testing Configs

​Using ctx API in Agents

​ctx.configs.get(name)

​Using Config for API Calls

​Dynamic Config Selection

​Environment-Based Config

​Merging Configs

​Troubleshooting

​Config Not Found

​Invalid Configuration

​Configuration Mismatch

​Next Steps