Tutorial: Your First Orchestration

Learn to create and execute your first Orchex orchestration. By the end of this tutorial, you'll understand streams, waves, and how AI agents execute tasks in parallel.

Time: 10-15 minutes Prerequisites: Orchex installed, ANTHROPIC_API_KEY set

Introduction

What Is an Orchestration?

An orchestration is a set of related tasks (called streams) that work together to accomplish a goal. Instead of one AI agent doing everything sequentially, Orchex breaks work into smaller pieces and runs them in parallel where possible.

Example: Building a feature might involve:

Creating types (independent)
Writing implementation (depends on types)
Writing tests (depends on implementation)

Orchex figures out the optimal order automatically.

What You'll Build

In this tutorial, you'll create an orchestration that:

Creates a greeting file
Creates a configuration file (in parallel with step 1)
Combines both into a final output

This demonstrates:

Defining streams with dependencies
Parallel execution (Wave 1)
Sequential execution (Wave 2)

Step 1: Create Your Project

Create a new directory for your orchestration:

mkdir my-first-orchestration
cd my-first-orchestration

Step 2: Write the Manifest

Create a file called manifest.yaml:

# manifest.yaml
# My first Orchex orchestration

streams:
  - id: create-greeting
    prompt: |
      Create a file called `greeting.txt` with a warm, friendly welcome message
      for a new user. Include their name placeholder [USER_NAME] that can be
      replaced later.
    dependencies: []

  - id: create-config
    prompt: |
      Create a file called `config.json` with the following structure:
      {
        "appName": "My App",
        "version": "1.0.0",
        "features": ["greeting", "personalization"]
      }
    dependencies: []

  - id: combine-output
    prompt: |
      Read `greeting.txt` and `config.json` (created by previous streams).
      Create a new file called `output.md` that:
      1. Shows the greeting text
      2. Lists the app configuration
      3. Combines them into a nice markdown document
    dependencies: [create-greeting, create-config]

Understanding the Manifest

Streams: Each - id: block defines a stream — a unit of work for an AI agent.

Dependencies:

create-greeting and create-config have no dependencies ([]) — they can run in parallel
combine-output depends on both — it waits for them to complete

Automatic Wave Calculation:

Wave 1: create-greeting, create-config  (parallel)
Wave 2: combine-output                   (waits for Wave 1)

Step 3: Initialize the Orchestration

If you're using Orchex via MCP (Claude Desktop, Cursor, Windsurf), ask your AI assistant:

Initialize an orchestration with the manifest in manifest.yaml

Or if using the Orchex MCP tools directly:

Use orchex.init to create an orchestration from this manifest:
[paste manifest content]

The orchestrator will:

Parse the manifest
Calculate wave order
Create .orchex/active/manifest.yaml

Step 4: Execute the Orchestration

Ask your AI assistant to execute:

Execute the orchestration we just initialized

Or use the execute command:

Use orchex.execute to run the next wave

What Happens During Execution

Wave 1 Execution:

⚡ Wave 1/2 (2 streams)
├─ create-greeting ... ✓ complete
└─ create-config   ... ✓ complete

Both streams run in parallel. The wall-clock time is roughly the time of the slowest stream, not the sum.

Wave 2 Execution:

⚡ Wave 2/2 (1 stream)
└─ combine-output ... ✓ complete

This stream runs after Wave 1 completes because it depends on both outputs.

Step 5: Examine the Results

After execution, check your files:

ls -la
# greeting.txt
# config.json
# output.md

Read the combined output:

cat output.md

You should see a markdown document that incorporates both the greeting and configuration.

Understanding Waves

Waves are how Orchex parallelizes work:

┌─────────────────────────────────────────────┐
│                   Wave 1                    │
│  ┌──────────────┐    ┌──────────────┐       │
│  │create-greeting│   │create-config │       │
│  └──────────────┘    └──────────────┘       │
│         │                   │               │
│         └─────────┬─────────┘               │
│                   │                         │
└───────────────────│─────────────────────────┘
                    │
┌───────────────────│─────────────────────────┐
│                   │                         │
│                   ▼                         │
│            ┌──────────────┐                 │
│            │combine-output│                 │
│            └──────────────┘                 │
│                   Wave 2                    │
└─────────────────────────────────────────────┘

Wave Rules:

Streams with no dependencies run in Wave 1
Each subsequent wave runs streams whose dependencies are all complete
Streams in the same wave run in parallel

Try It Yourself: Expanding the Orchestration

Now modify your manifest to add more streams:

streams:
  - id: create-greeting
    prompt: |
      Create `greeting.txt` with a friendly welcome message.
    dependencies: []

  - id: create-config
    prompt: |
      Create `config.json` with app configuration.
    dependencies: []

  - id: create-styles
    prompt: |
      Create `styles.css` with basic CSS styling:
      - Dark mode colors
      - Typography
      - Layout helpers
    dependencies: []

  - id: combine-output
    prompt: |
      Combine greeting.txt, config.json, and styles.css into
      a comprehensive `README.md` that documents all files.
    dependencies: [create-greeting, create-config, create-styles]

New Wave Structure:

Wave 1: create-greeting, create-config, create-styles (3 parallel)
Wave 2: combine-output (waits for all 3)

Common Patterns

Sequential Pipeline

streams:
  - id: step-1
    prompt: Create data.json with sample data
    dependencies: []

  - id: step-2
    prompt: Transform data.json into processed.json
    dependencies: [step-1]

  - id: step-3
    prompt: Generate report.md from processed.json
    dependencies: [step-2]

Waves: 1 → 2 → 3 (purely sequential)

Fan-Out/Fan-In

streams:
  - id: init
    prompt: Create source data
    dependencies: []

  - id: process-a
    prompt: Process source for output A
    dependencies: [init]

  - id: process-b
    prompt: Process source for output B
    dependencies: [init]

  - id: process-c
    prompt: Process source for output C
    dependencies: [init]

  - id: merge
    prompt: Combine A, B, C into final output
    dependencies: [process-a, process-b, process-c]

Waves:

Wave 1: init
Wave 2: process-a, process-b, process-c (parallel)
Wave 3: merge

Troubleshooting

"Circular dependency detected"

Problem: Stream A depends on B, and B depends on A.

Fix: Review your dependency declarations. Draw a diagram to visualize the flow.

"Stream failed"

Problem: The AI couldn't complete the task.

Fix:

Make the prompt more specific
Check that dependencies completed successfully
Look at the error message for hints

"File not found"

Problem: A stream expected a file that doesn't exist.

Fix:

Ensure the file is created by a dependency
Check that the dependency stream completed
Verify file paths match exactly

What You've Learned

✅ How to define streams in a manifest

✅ How dependencies determine wave order

✅ How parallel execution saves time

✅ Common orchestration patterns

Next Steps

Multi-Wave Feature Tutorial — Build a real feature with complex dependencies
Self-Healing Tutorial — Learn how Orchex automatically fixes failures
Context Optimization Tutorial — Optimize for faster, cheaper execution

Congratulations on completing your first orchestration!