Conductor – A CLI for deterministic multi‑agent AI workflows

What it is – conductor is a command‑line tool that lets you describe a pipeline of AI agents (Copilot, Claude, etc.) in a single YAML file and then run that pipeline locally or in CI. The orchestration itself is deterministic: routing decisions are expressed with Jinja2 templates, not with an LLM, so the same inputs always follow the same path.

Why you might care – If you build or experiment with multi‑step AI systems (code‑review bots, research‑then‑synthesize loops, plan‑then‑implement cycles) you often end up writing ad‑hoc scripts that are hard to version, test, or share. Conductor gives you:

• Repeatable, version‑controlled workflows (plain YAML that can be diffed in PRs)
• Provider‑agnostic agents – Copilot, Anthropic Claude, Claude‑Agent SDK, NousResearch Hermes, or Azure Container Apps sandboxed execution.
• Parallelism & sub‑workflows – fan‑out with for_each, reusable sub‑workflows, and concurrent agent groups.
• Human‑in‑the‑loop gates – pause a run for a user to answer a Markdown prompt.
• Observability – a web dashboard (real‑time DAG view, streaming agent output) and a TUI “Fleet Manager” that monitors every running workflow, shows token usage, and lets you answer gates without leaving the terminal.
• Safety limits – max‑iteration caps, timeouts, and explicit termination steps.
• OpenTelemetry – export traces to Jaeger/Tempo for deeper analysis.

How it works

1. Write a YAML that declares a workflow, a list of agents (model, prompt, output schema), and the routing (routes) between them. Jinja2 expressions can compute values, decide which step runs next, or build input mappings for sub‑workflows.
2. Run it with conductor run my-workflow.yaml --input key=value …. The CLI resolves the YAML, spins up the chosen provider’s API client, and executes each step – agents, scripts, set steps, MCP tool calls, etc.
3. Watch it – add --web for an interactive browser UI, or --web‑bg to run head‑less and later open the dashboard. Use conductor fleet (TUI) to see all active runs, answer human gates, or launch new runs from a form.
4. Observe & debug – logs, token/cost counters, and optional OpenTelemetry spans are emitted; you can also export the run’s JSON output.

Installation – The project provides a one‑liner installer that pulls the latest release via curl … | sh (or PowerShell on Windows). It uses uv under the hood to create an isolated virtual‑env, handling mirrors, proxies, and integrity checks. You can also install via uv tool install, pipx, or plain pip.

Key concepts

• Providers – Choose the AI backend (copilot, openai, claude, etc.) in workflow.runtime.provider. Each provider’s model name is set with default_model.
• Steps –
  • agent – calls an LLM with a prompt.
  • script – runs a shell command, can route on exit code or parsed JSON.
  • set – computes values with Jinja2 (no LLM, no subprocess).
  • mcp – calls a tool server directly, bypassing LLM token usage.
  • terminate – ends the workflow with a status.
• Routing – First‑matching Jinja2 condition wins; you can route on agent output, script exit, or any context variable.
• Human gates – A step can pause and render a Markdown prompt; the user answers via the dashboard, CLI, or TUI.
• Parallel groups / for_each – static groups run together; dynamic groups fan‑out over a list, each instance can invoke a sub‑workflow.

Typical use‑case

workflow:
  name: simple-qa
  entry_point: answerer
  runtime:
    provider: copilot
    default_model: gpt-5.5

agents:
  - name: answerer
    model: gpt-5.5
    prompt: |
      Answer the following question:
      {{ workflow.input.question }}
    output:
      answer:
        type: string
    routes:
      - to: $end

output:
  answer: "{{ answerer.output.answer }}"

Run with:

conductor run my-workflow.yaml --input question="What is Python?"

The CLI prints the JSON result and, if --web is added, streams the agent’s reasoning in the dashboard.

Who should use it –

• Teams building AI‑augmented developer tools, code‑review bots, or research assistants.
• Researchers prototyping multi‑agent pipelines who need reproducibility and observability.
• DevOps folks who want to run such pipelines in CI/CD (the deterministic routing means runs are predictable and cost‑trackable).

Limitations / status – The core CLI is stable, but several providers (Claude Agent SDK, Hermes, Azure Container Apps) are marked experimental. The project is actively maintained (CI badge, versioned releases) and provides upgrade tooling (conductor update).

---

All information above is taken directly from the repository’s README; no external assumptions have been added.