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 seven 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
Docs.mdMarkdown documentation with Handlebarsdocs/getting-started@v1

​
Why Use Components?

​
Version Control

# Lock to specific version
schema: schemas/[email protected]

# 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 set summarizer canary v2.0.0

# Promote to production
edgit tag set summarizer production v2.0.0

​
Component References

​
Versioned Reference

Reference a specific version: 
schema: schemas/[email protected]
prompt: prompts/[email protected]
config: configs/[email protected]
query: queries/[email protected]
script: scripts/[email protected]
template: templates/layouts/[email protected]
docs: docs/[email protected]

​
Tag Reference

Reference by tag: 
schema: schemas/invoice@production
prompt: prompts/summarizer@stable
config: configs/database@canary
template: templates/layouts/main@production
docs: docs/api-guide@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
docs: docs/getting-started@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
docs: docs/getting-started@latest

​
Shorthand (defaults to @latest)

schema: schemas/invoice
prompt: prompts/summarizer
template: templates/layouts/main
docs: docs/getting-started

​
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
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── api-guide.md

​
Versioning Components

​
Initialize Component

# Version a component
edgit tag create invoice v1.0.0

# Version with message
edgit tag create 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 tag create invoice v1.0.1

# New optional field
edgit tag create invoice v1.1.0

# Breaking change to schema structure
edgit tag create invoice v2.0.0

​
Tagging

Tag versions for deployment stages: 
# Tag for canary testing
edgit tag set invoice canary v2.0.0

# Promote to staging
edgit tag set invoice staging v2.0.0

# Promote to production
edgit tag set invoice production v2.0.0

​
View Versions

# List all versions
edgit tag list invoice

# Show version details
edgit tag show [email protected]

​
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.

​
Docs

Markdown documentation with Handlebars template support.

​
Best Practices

​
1. Version Early and Often

# Version from the start
edgit tag create 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 tag create invoice v2.0.0 -m "BREAKING: Renamed 'total' to 'amount'"

​
5. Test Before Promoting

# Test in canary
edgit tag set contact canary v2.0.0

# If successful, promote
edgit tag set contact production v2.0.0

​
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/[email protected]

​
Next Steps

Schemas

JSON Schema for structured outputs

Prompts

Reusable AI instruction templates

Configs

Configuration management

Queries

SQL query templates

Scripts

Reusable JavaScript/TypeScript

Docs

Markdown documentation components

Edgit

Version control system