Skip to main content

​
Overview

Components are reusable artifacts that can be versioned, shared, and referenced across your ensembles. They’re managed by edgit, Ensemble’s version control system for AI artifacts.

​
Component Types

Conductor supports six types of components:
ComponentFile TypePurposeExample Reference
Schemas.jsonJSON Schema for structured AI outputsschemas/invoice@v1
Prompts.mdAI instruction templatesprompts/summarizer@latest
Configs.json, .yamlReusable configurationconfigs/db-prod@stable
Queries.sqlDatabase query templatesqueries/analytics@v2
Scripts.js, .tsJavaScript/TypeScript functionsscripts/validators@v1
Templates.htmlHTML templates for renderingtemplates/layouts/main@v1

​
Why Use Components?

​
Version Control

# Lock to specific version
schema: schemas/invoice@v1.2.3

# Use latest stable
prompt: prompts/summarizer@production

# Follow major version
config: configs/api@v2

​
Reusability

Define once, use everywhere: 
# ensemble-1.yaml
agents:
  - name: extract
    operation: think
    config:
      schema: schemas/contact@v1
      prompt: prompts/extractor@v1

# ensemble-2.yaml
agents:
  - name: validate
    operation: think
    config:
      schema: schemas/contact@v1  # Same schema

​
Team Collaboration

  • Share components across teams
  • Review changes before deployment
  • Roll back to previous versions
  • A/B test different versions

​
Gradual Rollouts

# Start with canary
edgit tag prompts/summarizer@v2.0.0 canary

# Promote to production
edgit tag prompts/summarizer@v2.0.0 production

​
Component References

​
Versioned Reference

Reference a specific version: 
schema: schemas/invoice@v1.2.3
prompt: prompts/summarizer@v2.0.0
config: configs/database@v1.5.2
query: queries/analytics@v3.1.0
script: scripts/validator@v2.0.0
template: templates/layouts/main@v1.0.0

​
Tag Reference

Reference by tag: 
schema: schemas/invoice@production
prompt: prompts/summarizer@stable
config: configs/database@canary
template: templates/layouts/main@production

​
Major Version Reference

Auto-upgrade to latest patch/minor: 
schema: schemas/invoice@v1       # Gets latest v1.x.x
prompt: prompts/summarizer@v2    # Gets latest v2.x.x
template: templates/layouts/main@v1  # Gets latest v1.x.x

​
Latest Reference

Always use the latest version: 
schema: schemas/invoice@latest
prompt: prompts/summarizer@latest
template: templates/layouts/main@latest

​
Shorthand (defaults to @latest)

schema: schemas/invoice
prompt: prompts/summarizer
template: templates/layouts/main

​
Component Organization

Organize components in your project: 
my-project/
├── schemas/
│   ├── invoice.json
│   ├── contact.json
│   └── sentiment.json
├── prompts/
│   ├── summarizer.md
│   ├── extractor.md
│   └── classifier.md
├── configs/
│   ├── database.yaml
│   ├── api-keys.json
│   └── rate-limits.yaml
├── queries/
│   ├── analytics.sql
│   ├── reports.sql
│   └── cleanup.sql
└── scripts/
    ├── validators.ts
    ├── transformers.js
    └── formatters.ts

​
Versioning Components

​
Initialize Component

# Version a component
edgit version schemas/invoice v1.0.0

# Version with message
edgit version prompts/summarizer v1.0.0 -m "Initial release"

​
Semantic Versioning

Follow semver for clear version meanings:
  • Major (v2.0.0): Breaking changes
  • Minor (v1.1.0): New features, backwards compatible
  • Patch (v1.0.1): Bug fixes, no new features
# Bug fix
edgit version schemas/invoice v1.0.1

# New optional field
edgit version schemas/invoice v1.1.0

# Breaking change to schema structure
edgit version schemas/invoice v2.0.0

​
Tagging

Tag versions for deployment stages: 
# Tag for canary testing
edgit tag schemas/invoice@v2.0.0 canary

# Promote to staging
edgit tag schemas/invoice@v2.0.0 staging

# Promote to production
edgit tag schemas/invoice@v2.0.0 production

​
View Versions

# List all versions
edgit versions schemas/invoice

# Show version details
edgit show schemas/invoice@v1.2.3

​
A/B Testing Components

Test different component versions: 
name: ab-test-prompts

agents:
  - name: summarize-a
    operation: think
    config:
      prompt: prompts/summarizer@v1  # Control
      percentage: 50

  - name: summarize-b
    operation: think
    config:
      prompt: prompts/summarizer@v2  # Treatment
      percentage: 50
See A/B Testing for more patterns.

​
Component Types Deep Dive

​
Schemas

JSON Schema definitions for structured AI outputs.

​
Prompts

Markdown files with AI instructions and templates.

​
Configs

JSON/YAML configuration files.

​
Queries

SQL query templates.

​
Scripts

JavaScript/TypeScript functions.

​
Best Practices

​
1. Version Early and Often

# Version from the start
edgit version prompts/new-feature v0.1.0

​
2. Use Semantic Versioning

# Clear version progression
v1.0.0 → v1.0.1 (fix) → v1.1.0 (feature) → v2.0.0 (breaking)

​
3. Tag Production Versions

# Development
prompt: prompts/summarizer@latest

# Production
prompt: prompts/summarizer@production

​
4. Document Breaking Changes

edgit version schemas/invoice v2.0.0 -m "BREAKING: Renamed 'total' to 'amount'"

​
5. Test Before Promoting

# Test in canary
edgit tag schemas/contact@v2.0.0 canary

# If successful, promote
edgit tag schemas/contact@v2.0.0 production

​
6. Lock Production to Versions

# ❌ Bad: production using @latest
schema: schemas/invoice@latest

# ✅ Good: production locked to tag
schema: schemas/invoice@production

# ✅ Better: production locked to specific version
schema: schemas/invoice@v1.2.3

​
Next Steps

Schemas

JSON Schema for structured outputs

Prompts

Reusable AI instruction templates

Configs

Configuration management

Queries

SQL query templates

Scripts

Reusable JavaScript/TypeScript

Edgit

Version control system