Documentation Index Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt
Use this file to discover all available pages before exploring further.
The Hierarchy Components (What You Version) | Agents (What Executes) | Ensembles (What Orchestrates)
Each layer has a specific job. No overlap, no confusion.
Components: Versioned Artifacts Components are files that agents use during execution. Think of them as the “ingredients” that agents consume:
Prompts (.md) - AI instructions and templatesConfigs (.json, .yaml) - Settings and parametersQueries (.sql) - Database queriesScripts (.js, .ts) - Reusable functionsSchemas (.json) - Data validation rulesTemplates (.html, .md) - Output templates
Why Components Are Special Each component gets its own version history. # Version independently edgit tag create extraction-prompt v1.0.0 edgit tag create analysis-config v2.1.0 edgit tag create validation-query v0.5.0 # Mix and match optimal versions extraction-prompt@v1.0.0 + analysis-config@v2.1.0 + validation-query@v0.5.0
You’re not stuck with “the current version.” You can cherry-pick the best version of each component from any point in history.Example: Prompt Component <!-- components/prompts/company-analysis.md --> # Company Analysis Prompt Analyze the following company data and provide: 1. Industry classification 2. Key products/services 3. Market position (scale 1-5) 4. Growth indicators Company data: {{company_data}} Respond in valid JSON format with these exact fields: - industry (string) - products (array of strings) - market_position (number 1-5) - growth (string)
Version it:
edgit tag create company-analysis v1.0.0 edgit tag set company-analysis prod v1.0.0 edgit push --tags --force
Now agents can reference it:
agents : - name : analyzer operation : think component : company-analysis@v1.0.0 # Locked to specific version
Agents: Workers That Execute Agents are executable units that perform tasks. They use operations (execution primitives) and components (versioned artifacts) to get work done.
Agent Anatomy agents : - name : analyzer # Unique name operation : think # What primitive to use component : prompt@v2.1.0 # What component to reference config : # Operation-specific config model : claude-3-5-sonnet-20241022 temperature : 0.7 cache_ttl : 3600 input : # Where to get input data data : ${fetch.output} condition : ${fetch.success} # When to run (optional) retry : # Retry config (optional) max_attempts : 3 backoff : exponential
Operations: How Agents Execute Operations are the execution primitives. Think of them as the “verb” of what an agent does:
think AI reasoning - LLMs, embeddings, classification
code JavaScript/TypeScript - Business logic, transformations
storage Storage operations - KV and R2
data Database operations - D1, Vectorize, Hyperdrive
http HTTP requests - External APIs, webhooks
tools MCP/skills access - External capabilities via protocols
email Email operations - Sending, templates
sms SMS operations - Twilio, etc.
html HTML rendering - Dynamic pages
pdf PDF generation - Reports, invoices
page Full-stack pages - Complete web pages with forms
Custom vs Starter Kit Agents Custom Agents - You define them using operations:agents : - name : my-analyzer operation : think component : my-prompt@v1.0.0 config : model : gpt-4
Starter Kit Agents - Ships with Conductor, ready to use:agents : - name : scraper agent : scraper # Use starter kit agent config : url : https://example.com extract : title : "h1"
Starter Kit agents available:
scraper - Web scraping with fallback strategiesvalidator - Quality scoring and validationrag - RAG pipeline with R2 storagehitl - Human-in-the-loop approvalfetcher - HTTP with retry logictransformer - Data transformationscheduler - Delayed/scheduled execution
Ensembles: Orchestration Workflows Ensembles are YAML files that coordinate agents into workflows. They define what runs , in what order , and how data flows .
Ensemble Anatomy ensemble : company-intelligence description : Fetch, analyze, and store company data # Input schema (optional but recommended) input : domain : type : string required : true # Agents to execute agents : # Sequential by default - name : fetch operation : http config : url : https://api.example.com/companies/${input.domain} - name : analyze operation : think component : analysis-prompt@v2.1.0 input : company_data : ${fetch.output} - name : score agent : validator input : content : ${analyze.output} condition : ${analyze.success} - name : store operation : data config : backend : d1 binding : DB operation : execute sql : "INSERT INTO analyses (domain, result) VALUES (?, ?)" params : - ${input.domain} - ${analyze.output} condition : ${score.passed} # Output mapping output : domain : ${input.domain} analysis : ${analyze.output} score : ${score.output.score} stored : ${store.success}
Flow Control Sequential (default):agents : - name : step1 operation : http - name : step2 operation : think # Waits for step1 to complete
Parallel :agents : - parallel : - name : analyze-financial operation : think - name : analyze-legal operation : think - name : analyze-technical operation : think # All three run simultaneously
Conditional :agents : - name : validate agent : validator - name : manual-review agent : hitl condition : ${validate.score < 0.8} # Only runs if validation score is low
Loops :agents : - name : process-batch operation : code loop : items : ${input.companies} max_iterations : 100 # Runs once per item
State Management Share data across agents using state:
state : schema : company_data : object analyses : array final_report : object agents : - name : fetch operation : http state : set : [ company_data ] # Write to state - name : analyze operation : think state : use : [ company_data ] # Read from state set : [ analyses ] # Append to array - name : report operation : think state : use : [ company_data , analyses ] # Read multiple set : [ final_report ]
State is immutable - each update creates a new version.
The Versioning Multiverse Here’s where it gets powerful: components AND agents can both be versioned independently.
Mix Versions Freely ensemble : analysis-pipeline agents : # Stable agent + proven prompt - name : prod-analyzer agent : analyzer@v1.0.0 component : analysis-prompt@v1.0.0 # New agent + new prompt - name : experimental-analyzer agent : analyzer@v2.0.0-beta component : analysis-prompt@v2.1.0 # Stable agent + experimental prompt - name : hybrid-analyzer agent : analyzer@v1.0.0 component : analysis-prompt@v2.1.0
Run all three in parallel and compare results. Welcome to the multiverse.
A/B Testing Made Trivial Test 2 agent versions x 3 prompt versions x 2 configs = 12 variants:
agents : - name : test-variant-1 agent : analyzer@v1.0.0 component : prompt@v1.0.0 config : config@v1.0.0 - name : test-variant-2 agent : analyzer@v2.0.0 component : prompt@v1.0.0 config : config@v1.0.0 # ... 10 more combinations
Each variant runs with its specific combination of versions.
Time Travel Reproduce bugs from last week by deploying the exact versions that were running:
# Check what's deployed edgit tag list analyzer edgit tag list analysis-prompt # Recreate exact environment with specific versions edgit tag set analyzer debug v1.9.2 edgit tag set analysis-prompt debug v3.1.0 edgit tag set config debug v2.0.1 edgit push --tags --force
Perfect reproducibility. Every time.
Edge Architecture Your ensembles run on Cloudflare Workers at 200+ global locations.
Why Edge Matters Traditional Orchestrators:
Centralized compute (single region)
Slow cold starts (2-5 seconds)
Scale requires infrastructure management
Geographic latency
Conductor (Edge-Native):
Distributed compute (200+ regions)
Fast cold starts (<50ms)
Infinite scale (automatic)
Near-zero latency globally
Built-in Caching Three cache layers:
KV Cache - HTTP responses, agent outputsAI Gateway Cache - LLM responses (persistent across deployments)Durable Objects - Strongly consistent state for HITL and async workflows
agents : - name : fetch operation : http config : cache_ttl : 3600 # Cache in KV for 1 hour - name : analyze operation : think config : model : claude-3-5-sonnet-20241022 # AI Gateway caches automatically
First request: ~200ms
Cached request: <10ms
What You Can’t Do (By Design) Ensembles can’t use operations directly: # ❌ Wrong - ensembles don't execute operations ensemble : my-workflow operation : think # ERROR # ✅ Right - ensembles orchestrate agents ensemble : my-workflow agents : - name : analyzer operation : think
Ensembles aren’t versioned: # ❌ No such thing as ensemble@v1.0.0 # Ensembles are deployment configurations # ✅ Components and agents are versioned agents : - name : analyzer agent : analyzer@v1.0.0 component : prompt@v2.1.0
Ensembles are like Kubernetes manifests - you don’t version the manifest, you update it to point to different versions of containers (agents) and configs (components).
Mental Model Think of it like a restaurant:
Components = Recipes (versioned, can be updated independently)Agents = Chefs (execute using recipes and tools)Ensembles = Menu/Order (orchestrate which chefs make which dishes)Operations = Cooking techniques (grill, bake, saute)Conductor = Kitchen manager (coordinates everything)
You version the recipes and train chefs. The menu composition changes based on what’s optimal.
Next Steps
Nomenclature & Glossary Complete terminology reference
Edgit Documentation Component versioning system
Conductor Documentation Edge orchestration framework
Operations Reference All available operations
