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

# Conductor

> Edge-native orchestration for AI workflows. Under 50ms cold starts at 200+ global locations. No servers to manage.

Define workflows in YAML. Deploy to Cloudflare Workers. State management, caching, parallelization built-in.

## What Conductor Does

Conductor is a production-ready orchestration framework for building AI workflows that execute at the edge. You define **ensembles** (workflows) in YAML that coordinate **agents** (workers) using **operations** (execution primitives) to accomplish complex tasks.

**No DAG builders. No UI-driven workflows. No central orchestrator bottleneck.**

Just YAML files in Git that deploy to Cloudflare Workers.

## Why Edge-Native Matters

**Traditional Orchestrators** (Airflow, Temporal, Prefect):

* Centralized servers (single region)
* Slow cold starts (2-5 seconds)
* Infrastructure management required
* Geographic latency

**Conductor (Edge-Native)**:

* Distributed compute (200+ regions)
* Fast cold starts (\<50ms)
* Zero infrastructure management
* Near-zero latency globally

## Quick Example

Create `ensembles/company-intel.yaml`:

```yaml theme={null}
name: company-intel
description: Fetch and analyze company data

flow:
  # Fetch company data
  - name: fetch
    operation: http
    config:
      url: https://api.company-data.com/lookup?domain=${input.domain}
      cache_ttl: 3600  # Cache for 1 hour

  # Analyze with AI
  - name: analyze
    operation: think
    component: analysis-prompt@v2.1.0  # Versioned prompt via Edgit
    config:
      model: claude-3-5-sonnet-20241022
    input:
      company_data: ${fetch.output}

  # Validate quality
  - name: score
    agent: validator  # Pre-built agent
    input:
      content: ${analyze.output}

output:
  domain: ${input.domain}
  analysis: ${analyze.output}
  quality_score: ${score.output.score}
  cached: ${fetch.cached}
```

Deploy it:

```bash theme={null}
ensemble conductor deploy
```

Test it via the API:

```bash theme={null}
# Execute via API (requires authentication)
curl https://your-worker.workers.dev/api/v1/execute/ensemble/company-intel \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": {"domain": "stripe.com"}}'

# Or define an HTTP trigger for public access
# See triggers documentation for auth options
```

**You're running AI workflows at the edge in \<5 minutes.**

## Core Components

### 1. Operations (Execution Primitives)

Operations define **HOW** agents execute. They're the "verbs" of what agents do:

<CardGroup cols="2">
  <Card title="think" icon="brain" href="/conductor/operations/think">
    AI reasoning with LLMs
  </Card>

  <Card title="code" icon="code" href="/conductor/operations/code">
    JavaScript and TypeScript execution
  </Card>

  <Card title="storage" icon="database" href="/conductor/operations/storage">
    Database and storage operations
  </Card>

  <Card title="http" icon="globe" href="/conductor/operations/http">
    HTTP requests to APIs
  </Card>

  <Card title="tools" icon="wrench" href="/conductor/operations/tools">
    MCP tools and skills integration
  </Card>

  <Card title="email" icon="envelope" href="/conductor/operations/email">
    Email sending operations
  </Card>
</CardGroup>

[View all operations ](/conductor/operations/overview)

### 2. Agents (Workers)

Agents are executable units that use operations to perform tasks:

**Custom Agents** (you define):

```yaml theme={null}
flow:
  - name: analyzer
    operation: think
    component: prompt@v2.1.0
    config:
      model: claude-3-5-sonnet-20241022
```

**Starter Kit** (ship with Conductor):

```yaml theme={null}
flow:
  - name: scraper
    agent: scraper  # Use pre-built
    config:
      url: https://example.com
```

Available pre-built agents:

* `scraper` - Web scraping with 3-tier fallback
* `validator` - Quality scoring with multiple evaluators
* `rag` - RAG pipeline with R2 storage
* `hitl` - Human-in-the-loop approval workflows
* `fetcher` - HTTP with retry logic
* `transformer` - Data transformation utilities
* `scheduler` - Delayed/scheduled execution

[View all agents ](/conductor/starter-kit/overview)

### 3. Ensembles (Orchestration)

Ensembles are YAML files that coordinate agents into workflows:

```yaml theme={null}
name: my-workflow

flow:
  # Sequential by default
  - name: fetch
    operation: http

  - name: analyze
    operation: think

  # Parallel execution
  - parallel:
      - name: financial-analysis
        operation: think
      - name: legal-analysis
        operation: think

  # Conditional execution
  - name: manual-review
    agent: hitl
    condition: ${analyze.score < 0.8}

output:
  result: ${analyze.output}
  required_review: ${manual-review.completed}
```

[Learn more about ensembles ](/conductor/core-concepts/ensembles)

## Key Features

### State Management

Share data across agents with immutable state:

```yaml theme={null}
state:
  schema:
    company_data: object
    analyses: array

flow:
  - 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
```

### Caching

Three cache layers for optimal performance:

```yaml theme={null}
flow:
  - name: fetch
    operation: http
    config:
      cache_ttl: 3600  # KV cache for 1 hour

  - name: analyze
    operation: think
    config:
      model: claude-3-5-sonnet-20241022
      # AI Gateway caches automatically
```

First request: \~200ms
Cached request: \<10ms

### Flow Control

**Sequential** (default), **parallel**, **conditional**, **loops**, **retry**:

```yaml theme={null}
flow:
  # Sequential
  - name: step1
    operation: http

  - name: step2
    operation: think

  # Parallel
  - parallel:
      - name: task-a
        operation: think
      - name: task-b
        operation: think

  # Conditional
  - name: fallback
    operation: think
    condition: ${step2.failed}

  # Loop
  - name: process-batch
    operation: code
    loop:
      items: ${input.items}

  # Retry
  - name: api-call
    operation: http
    retry:
      max_attempts: 3
      backoff: exponential
```

[Learn about flow control ](/conductor/core-concepts/flow-control)

### A/B Testing

Test multiple variants simultaneously:

```yaml theme={null}
name: ab-test

flow:
  # Variant A: GPT-4 with conservative prompt
  - name: variant-a
    operation: think
    component: conservative-prompt@v1.0.0
    config:
      model: gpt-4

  # Variant B: Claude with aggressive prompt
  - name: variant-b
    operation: think
    component: aggressive-prompt@v2.0.0
    config:
      model: claude-3-5-sonnet-20241022

output:
  variant_a_result: ${variant-a.output}
  variant_b_result: ${variant-b.output}
  # Compare and pick winner
```

[Learn about A/B testing ](/conductor/core-concepts/ab-testing)

## Beyond Workflows: Build Web Applications

Conductor isn't just for backend workflows. Using ensembles with HTTP triggers, you can build server-rendered web applications:

**Features:**

* **HTTP triggers** - Define routes with path parameters and rate limiting
* **Template rendering** - Handlebars, Liquid, or raw HTML templates
* **Dynamic routes** - URL parameters like `/blog/:slug`
* **Content negotiation** - HTML or JSON based on Accept header
* **Full flow control** - Use any agent operation to fetch data before rendering

**Example:**

```yaml theme={null}
# ensembles/blog-post.yaml
name: blog-post
description: Render a blog post page

trigger:
  - type: http
    path: /blog/:slug
    methods: [GET]
    public: true
    rateLimit:
      requests: 100
      window: 60

flow:
  # Fetch post data
  - name: fetch-post
    operation: http
    config:
      url: https://api.cms.com/posts/${params.slug}

  # Render the page
  - name: render
    operation: html
    config:
      templateEngine: handlebars
      template: |
        <h1>{{fetch-post.output.title}}</h1>
        <div class="content">
          {{fetch-post.output.content}}
        </div>

output:
  _raw: ${render.output}
```

[Learn more about Ensembles](/conductor/core-concepts/ensembles)

## Versioning (Optional)

Conductor supports component versioning through **Edgit** integration:

**Basic approach**: Version control with git (standard)

**Advanced approach**: Edgit integration for component-level versioning

> **Note**: Edgit is optional. You can use Conductor with standard git workflows.

**If using Edgit**, you get:

* Versioned components (prompts, configs, queries, scripts)
* Versioned agent implementations
* Mix optimal versions from different points in history
* Rollback one component without touching anything else

**Example with Edgit:**

```yaml theme={null}
name: versioned-workflow

flow:
  - name: scraper
    agent: scraper@v1.5.0          # Versioned agent via Edgit

  - name: analyzer
    operation: think
    component: analysis-prompt@v2.1.0  # Versioned component via Edgit
    config:
      model: claude-3-5-sonnet-20241022
```

[Learn more about Edgit ](/edgit/overview)

## Platform Integration

### Cloudflare Workers

Conductor runs on Cloudflare Workers with access to the full platform:

* **KV** - Key-value storage for caching
* **D1** - SQL database for structured data
* **R2** - Object storage for documents
* **Vectorize** - Vector database for embeddings
* **Durable Objects** - Strongly consistent state for HITL
* **AI Gateway** - Caching and observability for AI providers
* **Workers AI** - On-platform AI models

### Configuration

Simple `wrangler.toml` configuration:

```toml theme={null}
name = "my-ai-workflow"
main = "src/index.ts"
compatibility_date = "2024-11-01"

# KV for caching
[[kv_namespaces]]
binding = "CACHE"
id = "your_kv_namespace_id"

# D1 for structured data
[[d1_databases]]
binding = "DB"
database_name = "analytics"
database_id = "your_d1_database_id"

# AI Gateway
[ai]
binding = "AI_GATEWAY"
gateway_id = "your_gateway_id"
```

## Production-Ready

<CardGroup cols="2">
  <Card title="812 Tests Passing" icon="check-circle">
    Comprehensive test coverage with Vitest
  </Card>

  <Card title="v1.8.0 Released" icon="rocket">
    Production-ready and published to npm
  </Card>

  <Card title="Type-Safe" icon="shield">
    Full TypeScript support with strict types
  </Card>

  <Card title="Observable" icon="chart-line">
    Structured logs and metrics for every execution
  </Card>
</CardGroup>

## Testing Your Workflows

Conductor includes Vitest for testing. The template includes working examples:

```typescript theme={null}
import { describe, it, expect } from 'vitest';
import { Executor, MemberLoader } from '@ensemble-edge/conductor';
import { stringify } from 'yaml';

describe('My Ensemble', () => {
  it('should execute successfully', async () => {
    // Setup with proper ExecutionContext mock
    const env = {} as Env;
    const ctx = {
      waitUntil: (promise: Promise<any>) => promise,
      passThroughOnException: () => {}
    } as ExecutionContext;

    const executor = new Executor({ env, ctx });
    const loader = new MemberLoader({ env, ctx });

    // Register your agents
    const agent = loader.registerAgent(agentConfig, agentFunction);
    executor.registerAgent(agent);

    // Execute ensemble
    const result = await executor.executeFromYAML(
      stringify(myEnsemble),
      { input: 'test data' }
    );

    // Assert
    expect(result.success).toBe(true);
    expect(result.value.output).toBeDefined();
  });
});
```

Run tests: `pnpm test`

> **Note**: Proper ExecutionContext mocking is required. See template examples in `tests/basic.test.ts`.

## Limitations & Considerations

**Platform Constraints**:

* **Execution time**: 30s limit for free tier, 15min for paid (CPU time limit)
* **Max payload**: 100MB for requests/responses
* **Cold starts**: \~50ms (negligible for most use cases)

**Development Notes**:

* **Rebuilding required** after adding new agents/pages (discovered at build time)
* **Network binding** needed for local dev: use `--local-protocol http` flag
* **Some operations require API keys** (OpenAI, Anthropic, etc.)

**What Works**:

* ✅ Dynamic route parameters (e.g., `/blog/:slug`) - Fixed in v1.8.0!
* ✅ Static and dynamic pages
* ✅ All 12 operations
* ✅ Auto-discovery of pages, agents, ensembles
* ✅ State management and caching

[See troubleshooting guide ](/conductor/getting-started/your-first-project#troubleshooting)

## Use Cases

<AccordionGroup>
  <Accordion icon="building" title="Company Intelligence">
    Scrape company data and analyze with AI to generate reports and store results.

    Operations: http + think + storage
  </Accordion>

  <Accordion icon="file-invoice" title="Document Processing">
    Extract data from PDFs and validate quality with human approval for low scores.

    Starter Kit: validator + hitl
  </Accordion>

  <Accordion icon="magnifying-glass" title="RAG System">
    Index documents from R2 and perform semantic search to generate contextualized answers.

    Starter Kit: rag
  </Accordion>

  <Accordion icon="envelope" title="Email Workflows">
    Parse emails and classify intent to route to handlers and send automated responses.

    Operations: email + think + http
  </Accordion>

  <Accordion icon="chart-line" title="A/B Testing">
    Test multiple prompt versions and agent implementations with model configs in parallel.

    Feature: Version multiverse with Edgit integration
  </Accordion>
</AccordionGroup>

## Quick Start (60 Seconds)

Get a working Conductor project instantly:

<Tabs>
  <Tab title="Unified CLI (Recommended)">
    The interactive wizard handles everything:

    ```bash theme={null}
    # Launch the wizard (no installation needed)
    npx @ensemble-edge/ensemble
    ```

    Select **Conductor**, enter your project name, and the wizard will create your project and install dependencies automatically.

    Then start the dev server:

    ```bash theme={null}
    cd my-conductor-app
    ensemble conductor start
    ```

    Open [http://localhost:8787](http://localhost:8787) 🎉
  </Tab>

  <Tab title="Direct Command">
    ```bash theme={null}
    # Create project with examples (no installation needed)
    npx @ensemble-edge/ensemble conductor init my-conductor-app
    cd my-conductor-app

    # Install and run
    pnpm install
    ensemble conductor start
    ```

    Open [http://localhost:8787](http://localhost:8787) 🎉
  </Tab>
</Tabs>

Your project includes:

* ✅ **10 example pages** - Static, dynamic, forms, and SSR patterns
* ✅ **Working workflows** - hello-world ensemble ready to run
* ✅ **Custom agents** - hello agent showing code operations
* ✅ **Tests** - Vitest setup with passing examples

## Ready to Get Started?

<CardGroup cols={3}>
  <Card title="Your First Project" icon="rocket" href="/conductor/getting-started/your-first-project">
    Start here! Initialize in 60 seconds
  </Card>

  <Card title="Understanding Agents" icon="robot" href="/conductor/getting-started/your-first-agent">
    Learn the building blocks
  </Card>

  <Card title="Creating Workflows" icon="diagram-project" href="/conductor/getting-started/your-first-ensemble">
    Build your own ensembles
  </Card>
</CardGroup>

## Architecture Principles

<AccordionGroup>
  <Accordion icon="globe" title="Edge-First">
    Cloudflare Workers + KV + D1 + R2 are the primitives. No centralized compute.
  </Accordion>

  <Accordion icon="bolt" title="Cache-Central">
    Multi-layer caching with TTL control reduces costs and latency by 10x.
  </Accordion>

  <Accordion icon="check-square" title="Structured Outputs">
    AI operations produce machine-readable and type-safe output validated via JSON schema.
  </Accordion>

  <Accordion icon="chart-line" title="Observable by Default">
    Every execution emits structured logs and metrics for effortless debugging.
  </Accordion>

  <Accordion icon="code" title="Result-Based Error Handling">
    No throwing exceptions in core runtime with explicit Result types for predictable error flow.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols="2">
  <Card title="Your First Project" icon="rocket" href="/conductor/getting-started/your-first-project">
    Create your first Conductor project
  </Card>

  <Card title="Core Concepts" icon="book" href="/conductor/core-concepts/operations">
    Learn about operations and agents and ensembles
  </Card>

  <Card title="Operations Reference" icon="gear" href="/conductor/operations/overview">
    All available operations
  </Card>

  <Card title="Starter Kit" icon="cube" href="/conductor/starter-kit/overview">
    Ready-to-use production agents
  </Card>

  <Card title="Playbooks" icon="lightbulb" href="/conductor/playbooks/rag-pipeline">
    Real-world patterns and recipes
  </Card>

  <Card title="Testing & Observability" icon="chart-line" href="/conductor/building/testing-observability">
    Debug and monitor your workflows
  </Card>

  <Card title="Security & Auth" icon="shield" href="/conductor/building/security-authentication">
    API keys, permissions, and authentication
  </Card>
</CardGroup>

<Note>
  Conductor is open source. Workflows run on your Cloudflare account. We don't see your data.

  You own everything.
</Note>