Components (prompts, schemas, configs, scripts)
    ↓
Agents (workers with operations)
    ↓
Ensembles (orchestration of agents)
    ↓
Triggers (http, webhook, mcp, email, queue, cron, build, cli)

Ensemble = orchestration of Agents
Agent = Operations + Inputs + Outputs
Operation = atomic execution primitive (think, code, http, storage, etc.)

# Ensembles: Complex orchestration is OK
ensemble: order-pipeline
trigger:
  - type: http
    path: /api/orders
agents:
  - name: validate
    agent: order-validator
    inputs: { order: ${input.body} }
  - name: process
    condition: ${validate.output.valid}
    agent: order-processor
  - name: notify
    condition: ${process.success}
    agent: notification-sender
output:
  orderId: ${process.output.id}
  status: ${process.output.status}

# Agent YAML: Simple contract
agent: order-validator
description: Validates order data against business rules
version: 1.0.0

inputs:
  order:
    type: object
    required: true

actions:
  - name: validate
    operation: code
    handler: ./validator.ts

outputs:
  valid: boolean
  errors: array

// validator.ts: Complex logic lives here
import type { AgentContext } from '@ensemble-edge/conductor'
import { orderSchema } from '../schemas/order.js'

export default async function validate(ctx: AgentContext) {
  const { order } = ctx.input

  // All complex validation logic in TypeScript
  const errors: string[] = []

  if (!order.items?.length) {
    errors.push('Order must have at least one item')
  }

  if (order.total < 0) {
    errors.push('Order total cannot be negative')
  }

  // Use shared schema for structure validation
  const schemaResult = ctx.schemas.validate('order', order)
  if (!schemaResult.valid) {
    errors.push(...schemaResult.errors)
  }

  return {
    valid: errors.length === 0,
    errors
  }
}

# Agent leveraging components
agent: docs-generator
inputs:
  page:
    type: string
    required: true

actions:
  - name: generate
    operation: code
    handler: ./generator.ts
    # Reference shared components
    uses:
      - schemas/[email protected]      # Validation schema
      - prompts/docs-writer@latest    # AI prompt (if useAI enabled)
      - configs/[email protected]   # Shared configuration

// generator.ts
export default async function generate(ctx: AgentContext) {
  // Access components directly
  const schema = ctx.schemas.get('docs-page')
  const prompt = ctx.prompts.get('docs-writer')
  const config = ctx.configs.get('docs-settings')

  // Access project configuration
  const docsConfig = ctx.config.docs

  if (docsConfig?.useAI && prompt) {
    // AI-powered generation
    return ctx.think({
      prompt: prompt.render({ page: ctx.input.page }),
      schema: schema
    })
  }

  // Static generation
  return generateStatic(ctx.input.page, config)
}

// Read config
const projectName = ctx.config.name
const docsSettings = ctx.config.docs
const observability = ctx.config.observability

// Config is read-only at runtime
// To modify settings, update conductor.config.ts and rebuild

catalog/
├── agents/
│   ├── redirect/           # URL redirect agent
│   │   ├── redirect.yaml   # Simple contract
│   │   └── redirect.ts     # All redirect logic
│   └── docs/               # Documentation agent
│       ├── docs.yaml       # Simple contract
│       └── docs.ts         # All docs logic
└── ensembles/
    ├── redirects/          # Redirect orchestration
    │   └── resolve.yaml    # HTTP trigger + routing
    └── docs/               # Docs orchestration
        ├── serve.yaml      # HTTP serving
        └── generate.yaml   # Build-time generation

${input.field}                    # Ensemble/agent input
${agent-name.output}              # Agent output
${agent-name.output.nested.field} # Nested access
${state.field}                    # State variable
${env.VARIABLE}                   # Environment variable
${[email protected]}          # Component reference
${trigger.options.format}         # CLI trigger options

${agent.executed}                 # Boolean: ran
${agent.failed}                   # Boolean: errored
${agent.success}                  # Boolean: succeeded
${agent.cached}                   # Boolean: from cache
${agent.duration}                 # Number: ms

condition: ${input.value > 10}
condition: ${agent.failed}
condition: ${!agent.executed}
condition: ${input.type === 'premium'}
condition: ${input.age >= 18 && input.verified}

${Date.now()}
${JSON.stringify(obj)}
${JSON.parse(str)}
${array.length}
${array.map(x => x.id)}
${array.filter(x => x.active)}
${string.split(',')}
${string.toUpperCase()}

ensemble: string                   # Required
description: string                # Optional

trigger:                           # Optional: invocation methods
  - type: http|webhook|mcp|email|queue|cron|build|cli
    # ... trigger-specific config

state:                             # Optional
  schema:
    field: type

agents:                            # Required
  - name: string
    agent: string                  # OR operation
    operation: string              # OR agent
    inputs: { key: value }
    config: { key: value }
    condition: string
    cache: { ttl: number, key: string }
    retry: { maxAttempts: number, backoff: exponential|linear }
    timeout: number
    state: { use: [fields], set: { field: value } }

output:                            # Optional
  key: value

agent: string                      # Required
description: string                # Optional

inputs:                            # Optional
  field:
    type: string|number|boolean|array|object
    required: boolean
    default: any

operations:                        # Required
  - name: string
    operation: string
    config: { ... }
    condition: string
    cache: { ttl, key }
    retry: { maxAttempts, backoff }

outputs:                           # Optional
  field: expression

import { createEnsemble, step, parallel, branch, tryStep } from '@ensemble-edge/conductor'

const ensemble = createEnsemble('name')
  .setDescription('...')
  .setInput<InputType>()
  .setOutput<OutputType>()
  .addStep(step('name').agent('agent-name').input({ ... }))
  .addStep(step('name').operation('think').config({ ... }))
  .addStep(parallel('name').steps([...]))
  .addStep(branch('name').condition('...').then(...).else(...))
  .addStep(tryStep('name').try(...).catch(...))
  .build()

export default ensemble

step('name')
  .agent('agent-name')           // Reference agent
  .operation('think')            // OR use operation directly
  .input({ key: '${...}' })      // Inputs
  .config({ ... })               // Operation config
  .condition('${...}')           // Conditional execution
  .cache({ ttl: 3600, key: '...' })
  .retry({ maxAttempts: 3, backoff: 'exponential' })
  .timeout(30000)

import { componentRef, versionedAgent, versionedEnsemble } from '@ensemble-edge/conductor'

// Component reference
componentRef('agent', 'path/name', '1.0.0')
componentRef('agent', 'path/name', '^1.0.0', { fallback: '0.9.0' })

// Versioned agent
versionedAgent('path/name', '1.0.0')
versionedAgent('path/name', '^1.0.0', { config: { ... } })

// Versioned ensemble
versionedEnsemble('pipelines/name', '^2.0.0', { input: { ... } })

agents:
  - name: fetch
    operation: http
    config: { url: "${input.url}" }
  - name: process
    operation: code
    config: { script: scripts/process }
    input: { data: ${fetch.output} }
  - name: store
    operation: data
    config: { backend: d1, binding: DB, query: "INSERT..." }

agents:
  - name: fetch-a
    operation: http
    config: { url: "https://api-a.com" }
  - name: fetch-b
    operation: http
    config: { url: "https://api-b.com" }
  - name: merge
    operation: code
    config: { script: scripts/merge }
    input: { a: ${fetch-a.output}, b: ${fetch-b.output} }

agents:
  - name: check-cache
    operation: storage
    config: { type: kv, action: get, key: "result-${input.query}" }
  - name: generate
    condition: ${check-cache.output.value === null}
    operation: think
    config: { provider: openai, model: gpt-4o, prompt: "${input.query}" }
  - name: save-cache
    condition: ${generate.executed}
    operation: storage
    config: { type: kv, action: put, key: "result-${input.query}", value: ${generate.output} }
output:
  result: ${check-cache.output.value || generate.output}

agents:
  - name: try-primary
    operation: http
    config: { url: "https://primary-api.com" }
    retry: { maxAttempts: 2 }
  - name: try-backup
    condition: ${try-primary.failed}
    operation: http
    config: { url: "https://backup-api.com" }
  - name: use-cache
    condition: ${try-primary.failed && try-backup.failed}
    operation: storage
    config: { type: kv, action: get, key: cached-data }
output:
  data: ${try-primary.output || try-backup.output || use-cache.output}

agents:
  - name: classify
    operation: think
    config: { provider: openai, model: gpt-4o-mini, prompt: "Classify: ${input.text}. Return: urgent|normal|low" }
  - name: urgent-handler
    condition: ${classify.output === 'urgent'}
    agent: urgent-processor
  - name: normal-handler
    condition: ${classify.output === 'normal'}
    agent: normal-processor
output:
  result: ${urgent-handler.output || normal-handler.output}

agents:
  - name: embed
    operation: think
    config: { provider: openai, model: text-embedding-3-small, input: "${input.question}" }
  - name: search
    operation: data
    config: { backend: vectorize, binding: VECTORIZE, operation: query, vector: ${embed.output}, topK: 5 }
  - name: generate
    operation: think
    config:
      provider: openai
      model: gpt-4o
      prompt: |
        Context: ${search.output.results}
        Question: ${input.question}
        Answer using only the context.

agents:
  - name: generate
    operation: think
    config: { prompt: "Generate content for: ${input.topic}" }
  - name: review
    agent: hitl
    inputs: { prompt: "Review content", context: { content: ${generate.output} } }
  - name: publish
    condition: ${review.output.approved}
    operation: data
    config: { backend: d1, query: "INSERT INTO published..." }

trigger:
  - type: http
    path: /api/data/:id
    methods: [GET, POST]
    auth:
      type: bearer
      secret: ${env.API_TOKEN}
    rateLimit:
      requests: 100
      window: 60
    cors:
      origin: "https://myapp.com"

trigger:
  - type: cron
    cron: "0 8 * * *"
    timezone: "America/New_York"
    input: { report_type: "daily" }

project/
├── ensembles/          # YAML or TS ensembles
│   └── my-workflow.yaml
├── agents/             # Custom agents
│   └── my-agent/
│       └── agent.yaml
├── scripts/            # TS/JS for code operations
│   └── transform.ts
├── prompts/            # Prompt templates
│   └── analyzer.md
├── schemas/            # JSON schemas for structured output
│   └── response.json
├── configs/            # Reusable configs
│   └── settings.yaml
├── queries/            # SQL templates
│   └── analytics.sql
├── wrangler.toml       # Cloudflare config
└── .dev.vars           # Local secrets (gitignored)

// scripts/my-script.ts
import type { AgentExecutionContext } from '@ensemble-edge/conductor'

export default function myScript(context: AgentExecutionContext) {
  const { input, env, bindings } = context

  // Your logic here

  return { result: "..." }
}

# Project initialization
ensemble conductor init [name]    # Create project (use --yes for CI)

# Development (project commands)
pnpm run dev                      # Local dev server
pnpm run build                    # Build project
pnpm test                         # Run Vitest tests
npx wrangler deploy               # Deploy to CF Workers

# Validate
ensemble conductor validate [path]           # Validate YAML/TS files
ensemble conductor validate --fix            # Auto-fix issues
ensemble conductor validate -r               # Recursive directory scan
ensemble conductor validate --strict         # Strict mode
ensemble conductor validate --format json    # JSON output

# Execute
ensemble conductor ensemble:run <name> <input>
ensemble conductor agent:run <name> <input>

# Secrets
wrangler secret put <NAME>        # Production secrets

import { describe, it, expect } from 'vitest'
import { Executor, MemberLoader } from '@ensemble-edge/conductor'

describe('My Ensemble', () => {
  it('executes successfully', async () => {
    const executor = new Executor({ env, ctx })
    const result = await executor.executeFromYAML(yaml, { input: 'test' })
    expect(result.success).toBe(true)
  })
})

# Validate all files in current directory
ensemble conductor validate

# Validate specific file
ensemble conductor validate ensembles/my-workflow.yaml
ensemble conductor validate ensembles/my-workflow.ts

# Recursive with auto-fix
ensemble conductor validate . -r --fix

# Strict mode with JSON output (for CI)
ensemble conductor validate --strict --format json

agents:
  - name: greet
    operation: think
    config:
      provider: workers-ai
      model: "@cf/meta/llama-3.1-8b-instruct"
      temperature: 0.7
    schema:
      output:
        greeting: string    # AI response maps to this field
    prompt: "Generate a friendly greeting for ${input.name}"

output:
  message: ${greet.output.greeting}  # Access via schema field name
  model: ${greet.output._meta.model} # Metadata available via _meta

account_id = "your-account-id"  # Required for remote binding

[ai]
binding = "AI"
remote = true  # Required for local dev