examples

Conductor Examples

This directory contains example workflow files demonstrating various features of Conductor.

Quick Start Examples

simple-qa.yaml

A minimal workflow with a single agent that answers questions. Demonstrates:

• Basic workflow structure
• Input parameters
• Output schema validation
• Simple routing to $end

conductor run examples/simple-qa.yaml --input question="What is Python?"

Parallel Execution Examples

for-each-simple.yaml

Dynamic parallel processing with for-each groups. Demonstrates:

• For-each group definition
• Processing variable-length arrays
• Loop variable access ({{ item }}, {{ _index }})
• Aggregating parallel outputs

conductor run examples/for-each-simple.yaml --input items='["apple", "banana", "cherry"]'

parallel-research.yaml

Parallel research from multiple sources. Demonstrates:

• Static parallel groups
• Multiple specialized research agents
• Result aggregation from parallel outputs

conductor run examples/parallel-research.yaml --input topic="Renewable energy"

parallel-validation.yaml

Parallel code validation checks. Demonstrates:

• Static parallel groups for concurrent validation
• Multiple validation agents (security, performance, style)
• Failure mode configuration

conductor run examples/parallel-validation.yaml --input code="def hello(): print('world')"

Set Step Examples

set-step.yaml

Derive named values from Jinja2 expressions without spending an LLM call. Demonstrates:

• Single value: binding (scalar output accessible as step.output)
• Multi values: binding (dict output accessible as step.output.<key>)
• Conditional routing on a derived boolean (when: "{{ output.is_breaking }}")
• Combining derived values with downstream script-step consumers

# Breaking-change branch
conductor run examples/set-step.yaml \
  --input org=microsoft --input repo=conductor --input severity=high

# Safe-change branch with a custom model
conductor run examples/set-step.yaml \
  --input org=acme --input repo=widget --input severity=low \
  --input model=claude-haiku-4.5

Human-in-the-Loop Examples

design-review.yaml

An iterative design workflow with human approval. Demonstrates:

• Multiple agents with conditional routing
• Loop-back patterns for refinement
• Human gates for approval decisions
• Context accumulation between iterations
• Safety limits (max_iterations, timeout)

# Interactive mode
conductor run examples/design-review.yaml --input requirement="Build a REST API"

# Automation mode (auto-approves)
conductor run examples/design-review.yaml --input requirement="Build a REST API" --skip-gates

Explicit Termination

terminate.yaml

A workflow with multiple legitimate end states beyond "the last agent finished," using type: terminate steps to surface each outcome distinctly. Demonstrates:

• status: success — early-exit when there's nothing to do (CLI exit 0, dashboard ✅)
• status: failed — refuse-to-run on unsafe input (CLI exit 1, dashboard ❌, emits workflow_failed with is_explicit: true and error_type: WorkflowTerminated)
• Pass-through normal pipeline for the "do the work" path
• Optional output_template: that replaces the workflow-level output: for a termination path

# Success path — soft no-op, exit 0
conductor run examples/terminate.yaml --input document_state=current

# Failure path — hard refusal, exit 1 with structured reason
conductor run examples/terminate.yaml --input document_state=unsafe

# Normal pipeline (no terminate hit)
conductor run examples/terminate.yaml --input document_state=stale

CI / dashboard / notification tooling can read is_explicit: true from the JSONL event log to distinguish an intentional termination from a generic crash.

Reasoning Effort

reasoning-effort.yaml

A two-stage workflow that demonstrates configuring model reasoning / extended-thinking effort. Demonstrates:

• Workflow-wide default via runtime.default_reasoning_effort
• Per-agent override via reasoning.effort (wins over the default)
• Conditional routing on a structured boolean output
• The unified field translates to each provider's native API: reasoning_effort on the Copilot session, or extended thinking budget on Claude

conductor run examples/reasoning-effort.yaml \
  --input topic="how the Raft consensus algorithm handles leader election"

See Reasoning Effort for the per-provider translation, supported models, and validation rules.

Context Tier

context-tier.yaml

A two-stage workflow that demonstrates selecting a model's long-context (e.g. 1M-token) window. Demonstrates:

• Workflow-wide default via runtime.default_context_tier
• Per-agent override via context_tier (wins over the default)
• Composition with reasoning.effort — the two map to separate create_session kwargs
• Conditional routing on a structured boolean output

conductor run examples/context-tier.yaml \
  --input topic="root-causing a multi-service latency regression"

See Context Tier for details. This is a Copilot-only capability.

Output Validation

validator.yaml

A code-review workflow that demonstrates the validator: block — a second LLM call that grades an agent's output against a rubric and re-runs the agent once with feedback when it fails. Demonstrates:

• A validator.criteria rubric checking for a real bug, actionable suggestions, and no fabricated names
• Optional validator.model (defaults to the primary agent's model)
• max_retries: 1 (hard cap; 0 validates-and-reports without re-running)
• Validator cost appears as a separate code_reviewer (validator) usage row

conductor run examples/validator.yaml
conductor run examples/validator.yaml --input diff="$(git diff HEAD~1)"

See Validator for the full field reference and behavior notes.

Multi-Agent Workflows

research-assistant.yaml

A multi-agent research workflow with tools. Demonstrates:

• Multiple specialized agents
• Tool configuration at workflow and agent levels
• Explicit context mode
• Conditional routing based on coverage
• Complex output schemas

conductor run examples/research-assistant.yaml --input topic="AI in healthcare"

# With custom depth
conductor run examples/research-assistant.yaml --input topic="Quantum computing" --input depth="comprehensive"

research-assistant-claude.yaml

The research assistant configured for Claude provider. Demonstrates:

• Claude provider with multi-agent workflow
• Model selection per agent

export ANTHROPIC_API_KEY=sk-ant-...
conductor run examples/research-assistant-claude.yaml --input topic="Machine learning"

multi-provider-research.yaml

Research workflow demonstrating multi-provider patterns. Demonstrates:

• Provider configuration options
• Cross-provider workflow patterns

conductor run examples/multi-provider-research.yaml --input topic="Cloud computing"

copilot-local-llm.yaml

Routes the Copilot SDK at a local / custom OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, Azure OpenAI, etc.) via structured runtime.provider configuration. Demonstrates:

• Object form of runtime.provider (the bare-string provider: copilot shorthand still works)
• type / wire_api / base_url / api_key forwarded to the Copilot SDK's create_session(provider=…) parameter
• Secret hygiene via ${OPENAI_API_KEY:-ollama} interpolation
• Azure OpenAI variant in a commented block

# Requires Ollama running on http://localhost:11434
conductor run examples/copilot-local-llm.yaml --input question="What is Python?"

See Configuration → Custom Provider Routing for env-var fallbacks, validator rules, and the security rationale.

Step Types

script-step.yaml

Script step with shell command, JSON output parsing, and exit_code-based routing. Demonstrates:

• type: script agents (cross-platform shell command execution)
• Capturing stdout/stderr/exit_code
• Routing on exit_code (when: "exit_code == 0")
• Passing script output to downstream LLM agents

conductor run examples/script-step.yaml

script-stdin.yaml

Hand a structured payload to a script step via stdin instead of command-line args — the cross-platform-safe way to pass large or structured data (no Windows ~32 KB command-line limit, no temp files). Demonstrates:

• stdin: as a Jinja2 string template piped to the child as UTF-8
• JSON handoff via the built-in tojson filter ({{ x | tojson }})
• A script consuming an upstream agent's structured output (json.load(sys.stdin))

conductor run examples/script-stdin.yaml --input topic="error handling"

wait-step.yaml

Polling pattern with a wait step and a routing loop-back. Demonstrates:

• type: wait agents (pure asyncio.sleep, cross-platform — no shell sleep dependency)
• Templated duration ("{{ workflow.input.poll_interval_seconds }}s")
• Loop-back from wait → script for polling
• reason field surfaced in the dashboard

conductor run examples/wait-step.yaml \
  --input poll_interval_seconds=2 --input max_attempts=3

wait-smoke.yaml

Minimal wait-only workflow — no LLM, no scripts, no provider required. Useful as a smoke test for installation, dashboard rendering, and interrupt/timeout behavior. Three sequential wait steps demonstrate the three duration syntaxes (suffixed string, templated, plain numeric).

conductor run examples/wait-smoke.yaml

# Watch wait nodes animate in the dashboard:
conductor run examples/wait-smoke.yaml --web

# Trigger the workflow timeout cancelling an in-flight wait:
conductor run examples/wait-smoke.yaml --input middle_duration_ms=10000

Planning and Implementation

plan.yaml

A comprehensive design and implementation planning workflow. Demonstrates:

• Architect agent for creating solution designs with implementation plans
• Reviewer agent for quality assessment of design and actionability
• Loop-back pattern until quality threshold is met (score >= 85)
• Structured output following design document and implementation plan templates
• MCP server integration (web-search, context7) for research
• Traceability between requirements and implementation tasks

conductor run examples/plan.yaml --input purpose="Build a user authentication system with OAuth2"

# Resume from existing plan
conductor run examples/plan.yaml --input purpose="..." --input existing_plan="path/to/plan.md"

# With verbose output
conductor -V run examples/plan.yaml --input purpose="..."

implement.yaml

An epic-based implementation workflow with multi-tier review. Demonstrates:

• Coder agent (Opus 4.5) for deep research, analysis, and implementation
• Epic reviewer agent (Opus 4.5) for per-epic quality assessment
• Committer agent (Sonnet) for git commits and plan updates
• Plan reviewer agent (Opus 4.5) for holistic review of all changes
• Fixer agent (Opus 4.5) for addressing plan-level issues
• Iterative epic-by-epic implementation with automatic plan tracking
• Two-tier review: epic-level (fast) and plan-level (thorough)

conductor run examples/implement.yaml --input plan="path/to/implementation.plan.md"

# With specific epic
conductor run examples/implement.yaml --input plan="..." --input epic="EPIC-001"

# With verbose output
conductor -V run examples/implement.yaml --input plan="..."

Running Examples

Prerequisites

1. Install Conductor:

   uvx conductor

2. Ensure you have valid credentials for your provider:

   • Copilot: GitHub authentication via gh auth login
   • Claude: Set ANTHROPIC_API_KEY environment variable

Validate Before Running

You can validate a workflow without executing it:

conductor validate examples/simple-qa.yaml

Dry Run

Preview the execution plan without actually running the workflow:

conductor run examples/simple-qa.yaml --dry-run

Verbose Mode

See detailed execution progress:

conductor -V run examples/simple-qa.yaml --input question="Hello"

Web Dashboard

web-dashboard-test.yaml

A multi-pattern workflow for testing the web dashboard. Demonstrates:

• Real-time DAG visualization with live node state updates
• Agent detail panel with streaming reasoning and tool calls
• Sequential, parallel, and script step patterns in a single workflow

# Foreground dashboard (keeps running after workflow completes)
conductor run examples/web-dashboard-test.yaml --web --input topic="Python async programming"

# Background mode (prints URL and exits immediately)
conductor run examples/web-dashboard-test.yaml --web-bg --input topic="Rust vs Go"

Creating Your Own Workflows

Use the init command to create a new workflow from a template:

# List available templates
conductor templates

# Create from a template
conductor init my-workflow --template loop

Tips

1. Start simple: Begin with a linear workflow and add complexity incrementally.

2. Validate often: Use conductor validate to catch configuration errors early.

3. Use dry-run: Preview execution with --dry-run before running expensive workflows.

4. Explicit context: Use context.mode: explicit for complex workflows to control exactly what context each agent sees.

5. Safety limits: Always set appropriate max_iterations and timeout_seconds for workflows with loops.

6. Optional dependencies: Use ? suffix for optional input references to avoid errors when agents haven't run yet.

See Also

• Workflow Syntax Reference - Complete YAML schema
• CLI Reference - Full command documentation
• Parallel Execution - Static parallel groups
• Dynamic Parallel - For-each groups