Skip to content
Back to search

conductor

MarketplaceWorks with Claude CodeGitHub

Conductor — multi-agent workflow orchestration via YAML

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/microsoft/conductor with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/microsoft/conductor'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/microsoft--conductor/badge.svg)](/listings/microsoft--conductor)

HTML

<a href="/listings/microsoft--conductor"><img src="/api/listings/microsoft--conductor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Quick Install (Recommended)

**macOS / Linux:**

curl -sSfL https://aka.ms/conductor/install.sh | sh

**Windows (PowerShell):**

irm https://aka.ms/conductor/install.ps1 | iex

The installer checks for [uv](https://docs.astral.sh/uv/) (installs it if missing), fetches the latest release with pinned dependencies, and verifies integrity via SHA-256 checksum.

Updating

`conductor update` checks for a newer release and tells you the one-line command to upgrade. Upgrades happen via the install script — the same script you used to install — because in-process self-upgrade is unreliable on Windows (the running Python interpreter sits inside the venv that needs replacing).

conductor update

To upgrade, run the install script in a **new shell** (not from inside a running `conductor` process):

**macOS / Linux:**

curl -sSfL https://aka.ms/conductor/install.sh | sh

**Windows (PowerShell):**

irm https://aka.ms/conductor/install.ps1 | iex

Or skip the copy-paste with `--apply`:

conductor update --apply

`--apply` launches the install script automatically — on Windows it opens in a new console window so you can watch progress; on macOS/Linux it replaces the current process. Either way, the running `conductor` exits before the installer touches the venv, so file locks release cleanly.

**Optional extras survive the upgrade.** `uv tool install --force` replaces the tool's entire requirement set, so an upgrade that named no extras used to silently uninstall `[tui]` or `[aca]`. Both install scripts now read the existing install's uv receipt and carry those extras forward, and `conductor update` tells you which ones it found. To add one during an upgrade, or to drop back to a bare install:

curl -sSfL https://aka.ms/conductor/install.sh | sh -s -- --extras tui
curl -sSfL https://aka.ms/conductor/install.sh | sh -s -- --no-preserve-extras
$env:CONDUCTOR_INSTALL_EXTRAS = 'tui'; irm https://aka.ms/conductor/install.ps1 | iex

The install script handles file-lock safety (process detection, stale-file cleanup, and on Windows a rename-fallback when the venv directory can't be removed), retries with backoff, and verifies the installed version after install. If your shell ever gets into a bad state from a failed update, re-running the install script is always the right next step.

Conductor periodically checks GitHub for newer releases (cached for 24 hours under `~/.conductor/update-check.json`) and prints a one-line hint when one is available. To silence the hint permanently — for example when you manage upgrades through a package manager or company-mirrored install — set `CONDUCTOR_NO_UPDATE_CHECK=1` in your shell environment. The check is also skipped automatically for non-TTY invocations, `--silent` mode, the `update` subcommand, and `--help` / `--version`.

Manual Install

# Install from GitHub
uv tool install git+https://github.com/microsoft/conductor.git

# Run the CLI
conductor run workflow.yaml

# Or run directly without installing
uvx --from git+https://github.com/microsoft/conductor.git conductor run workflow.yaml

# Install a specific branch, tag, or commit
uv tool install git+https://github.com/microsoft/conductor.git@branch-name
uv tool install git+https://github.com/microsoft/conductor.git@v1.0.0
uv tool install git+https://github.com/microsoft/conductor.git@abc1234

Using pipx

pipx install git+https://github.com/microsoft/conductor.git
conductor run workflow.yaml

# Install a specific branch or tag
pipx install git+https://github.com/microsoft/conductor.git@branch-name

Using pip

pip install git+https://github.com/microsoft/conductor.git
conductor run workflow.yaml

# Install a specific tag or commit
pip install git+https://github.com/microsoft/conductor.git@v1.0.0

Installing behind a proxy or private package index

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 32 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "conductor",
  4. "version": "0.1.15",
  5. "description": "Conductor — multi-agent workflow orchestration via YAML",
  6. "owner": {
  7. "name": "Microsoft",
  8. "email": "opensource@microsoft.com"
  9. },
  10. "plugins": [
  11. {
  12. "name": "conductor",
  13. "source": "./plugins/conductor",
  14. "description": "Validate, run, and execute Conductor multi-agent YAML workflows. Adds the conductor skill that knows the workflow schema, CLI commands, and execution model.",
  15. "author": { "name": "Microsoft" },
  16. "homepage": "https://github.com/microsoft/conductor",
  17. "repository": "https://github.com/microsoft/conductor",
  18. "license": "MIT",
  19. "category": "workflow",
  20. "keywords": [
  21. "workflow",
  22. "orchestration",
  23. "multi-agent",
  24. "yaml",
  25. "copilot",
  26. "claude",
  27. "agents"
  28. ],
  29. "tags": ["agents", "automation", "workflow"]
  30. }
  31. ]
  32. }
README.md · README · 702 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Conductor
  2. A CLI tool for defining and running multi-agent workflows with the GitHub Copilot SDK and Anthropic Claude.
  3. [![CI](https://github.com/microsoft/conductor/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/conductor/actions/workflows/ci.yml)
  4. [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
  5. ## Why Conductor?
  6. Conductor makes multi-agent workflows — code review pipelines, research-then-synthesize flows, plan-then-implement loops — **repeatable, deterministic, and version-controlled**. You define your agents, their prompts, and the routing between them in a single YAML file:
  7. - **Repeatable** — Same inputs follow the same path through the same agents.
  8. - **Deterministic** — Routing uses Jinja2 templates and expression evaluation. First matching condition wins. No LLM in the orchestration loop, no tokens spent deciding what runs next.
  9. - **Source-controlled** — Plain YAML files. Diff workflows in pull requests, version them with your code, run them the same way locally and in CI.
  10. ## Features
  11. - **YAML-based workflows** - Define multi-agent workflows in readable YAML
  12. - **Multiple providers** - GitHub Copilot, Anthropic Claude, Claude Agent SDK (experimental), NousResearch Hermes (experimental), or Azure Container Apps sandboxed execution (experimental) with seamless switching
  13. - **Parallel execution** - Run agents concurrently (static groups or dynamic for-each)
  14. - **Sub-workflow composition** - Reusable sub-workflows with templated `input_mapping`, usable inside `for_each` groups for dynamic fan-out
  15. - **Script steps** - Run shell commands and route on exit code or parsed JSON stdout
  16. - **Set steps** - Bind one or more Jinja2-evaluated values into the context (no LLM, no subprocess) for derived flags, computed defaults, and constants reused by many later prompts
  17. - **MCP steps** - Call MCP server tools directly without an LLM (deterministic execution, zero prompt tokens, and structured envelope routing)
  18. - **Terminate steps** - Explicit terminal step with `status` (`success`/`failed`) and structured `reason` — distinguishable from the default `$end` path in CLI exit codes, dashboard state, and event logs
  19. - **Dialog mode** - Agents can pause for multi-turn conversation when uncertain
  20. - **Reasoning effort** - Unified `reasoning.effort` (low/medium/high/xhigh/max) per agent or workflow-wide, translated to each provider's native API
  21. - **Workspace instructions** - Auto-discover and inject `AGENTS.md` / `CLAUDE.md` / `.github/copilot-instructions.md` into every agent's prompt
  22. - **Conditional routing** - Route between agents based on output conditions
  23. - **Human-in-the-loop** - Pause for human decisions with Markdown-rendered prompts and clickable file links
  24. - **Safety limits** - Max iterations and timeout enforcement
  25. - **[Web dashboard](#web-dashboard)** - Real-time workflow visualization with interactive DAG graph, breadcrumb navigation into sub-workflows, live streaming, and in-browser human gates
  26. - **[Fleet Manager](#fleet-manager-tui)** - An interactive TUI over every running `conductor` process (foreground, `--web`, or `--web-bg`): live status, tokens and cost, gate alerts you can answer, step-level drill-down, and launching new runs — plus non-interactive `conductor stop` / `conductor fleet list`
  27. - **Validation** - Catches stale template references, missing inputs, and undeclared dependencies before runtime
  28. - **OpenTelemetry tracing**: Export detailed workflow execution traces to OTLP collectors, such as Jaeger or Tempo, with native Pydantic AI and Copilot CLI span correlation.
  29. ## Installation
  30. ### Quick Install (Recommended)
  31. **macOS / Linux:**
  32. ```bash
  33. curl -sSfL https://aka.ms/conductor/install.sh | sh
  34. ```
  35. **Windows (PowerShell):**
  36. ```powershell
  37. irm https://aka.ms/conductor/install.ps1 | iex
  38. ```
  39. The installer checks for [uv](https://docs.astral.sh/uv/) (installs it if missing), fetches the latest release with pinned dependencies, and verifies integrity via SHA-256 checksum.
  40. ### Updating
  41. `conductor update` checks for a newer release and tells you the one-line command to upgrade. Upgrades happen via the install script — the same script you used to install — because in-process self-upgrade is unreliable on Windows (the running Python interpreter sits inside the venv that needs replacing).
  42. ```bash
  43. conductor update
  44. ```
  45. To upgrade, run the install script in a **new shell** (not from inside a running `conductor` process):
  46. **macOS / Linux:**
  47. ```bash
  48. curl -sSfL https://aka.ms/conductor/install.sh | sh
  49. ```
  50. **Windows (PowerShell):**
  51. ```powershell
  52. irm https://aka.ms/conductor/install.ps1 | iex
  53. ```
  54. Or skip the copy-paste with `--apply`:
  55. ```bash
  56. conductor update --apply
  57. ```
  58. `--apply` launches the install script automatically — on Windows it opens in a new console window so you can watch progress; on macOS/Linux it replaces the current process. Either way, the running `conductor` exits before the installer touches the venv, so file locks release cleanly.
  59. **Optional extras survive the upgrade.** `uv tool install --force` replaces the tool's entire requirement set, so an upgrade that named no extras used to silently uninstall `[tui]` or `[aca]`. Both install scripts now read the existing install's uv receipt and carry those extras forward, and `conductor update` tells you which ones it found. To add one during an upgrade, or to drop back to a bare install:
  60. ```bash
  61. curl -sSfL https://aka.ms/conductor/install.sh | sh -s -- --extras tui
  62. curl -sSfL https://aka.ms/conductor/install.sh | sh -s -- --no-preserve-extras
  63. ```
  64. ```powershell
  65. $env:CONDUCTOR_INSTALL_EXTRAS = 'tui'; irm https://aka.ms/conductor/install.ps1 | iex
  66. ```
  67. The install script handles file-lock safety (process detection, stale-file cleanup, and on Windows a rename-fallback when the venv directory can't be removed), retries with backoff, and verifies the installed version after install. If your shell ever gets into a bad state from a failed update, re-running the install script is always the right next step.
  68. Conductor periodically checks GitHub for newer releases (cached for 24 hours under `~/.conductor/update-check.json`) and prints a one-line hint when one is available. To silence the hint permanently — for example when you manage upgrades through a package manager or company-mirrored install — set `CONDUCTOR_NO_UPDATE_CHECK=1` in your shell environment. The check is also skipped automatically for non-TTY invocations, `--silent` mode, the `update` subcommand, and `--help` / `--version`.
  69. ### Manual Install
  70. ```bash
  71. # Install from GitHub
  72. uv tool install git+https://github.com/microsoft/conductor.git
  73. # Run the CLI
  74. conductor run workflow.yaml
  75. # Or run directly without installing
  76. uvx --from git+https://github.com/microsoft/conductor.git conductor run workflow.yaml
  77. # Install a specific branch, tag, or commit
  78. uv tool install git+https://github.com/microsoft/conductor.git@branch-name
  79. uv tool install git+https://github.com/microsoft/conductor.git@v1.0.0
  80. uv tool install git+https://github.com/microsoft/conductor.git@abc1234
  81. ```
  82. ### Using pipx
  83. ```bash
  84. pipx install git+https://github.com/microsoft/conductor.git
  85. conductor run workflow.yaml
  86. # Install a specific branch or tag
  87. pipx install git+https://github.com/microsoft/conductor.git@branch-name
  88. ```
  89. ### Using pip
  90. ```bash
  91. pip install git+https://github.com/microsoft/conductor.git
  92. conductor run workflow.yaml
  93. # Install a specific tag or commit
  94. pip install git+https://github.com/microsoft/conductor.git@v1.0.0
  95. ```
  96. ### Installing behind a proxy or private package index
  97. Conductor's dependencies are resolved from the public Python package index
  98. (`pypi.org` / `files.pythonhosted.org`). Some networks — corporate or otherwise
  99. managed devices in particular — block direct access to public package
  100. registries and require every package to come from an internal mirror or proxy.
  101. Conductor ships **no default mirror** and never redirects your packages on its
  102. own. Point your package manager at whichever index your organization provides
  103. and the normal install commands work unchanged.
  104. **uv** (used by the install scripts, `uv tool install`, and `conductor update`):
  105. ```bash
  106. # macOS / Linux
  107. export UV_DEFAULT_INDEX="internal=https://<your-index-host>/simple/"
  108. curl -sSfL https://aka.ms/conductor/install.sh | sh
  109. ```
  110. ```powershell
  111. # Windows -- for this shell only
  112. $env:UV_DEFAULT_INDEX = "internal=https://<your-index-host>/simple/"
  113. irm https://aka.ms/conductor/install.ps1 | iex
  114. # Windows -- persist for future shells (then open a new terminal)
  115. setx UV_DEFAULT_INDEX "internal=https://<your-index-host>/simple/"
  116. ```
  117. The `internal=` prefix names the index. The name is optional for a plain
  118. public mirror, but it is what credential environment variables key off — so
  119. naming it up front saves reconfiguring later.
  120. Persist the setting in your shell profile (or with `setx`) so later upgrades
  121. and `conductor update --apply` inherit it. uv also reads a config file if you
  122. prefer that to an environment variable — `~/.config/uv/uv.toml` on macOS/Linux,
  123. `%APPDATA%\uv\uv.toml` on Windows:
  124. ```toml
  125. [[index]]
  126. name = "internal"
  127. url = "https://<your-index-host>/simple/"
  128. default = true
  129. ```
  130. **pipx / pip** (only if you install via the `pipx` or `pip` sections above):
  131. ```bash
  132. pip config set global.index-url https://<your-index-host>/simple/
  133. ```
  134. > **uv does not read pip's configuration.** Setting `pip config set
  135. > global.index-url` alone has no effect on the install scripts, `uv tool
  136. > install`, or `conductor update` — those need `UV_DEFAULT_INDEX` (or
  137. > `uv.toml`). Configure both if you use both toolchains.
  138. If pip already works through the required mirror, you can bridge its configured
  139. URL into uv without copying or printing credentials:
  140. ```bash
  141. # macOS / Linux
  142. pip_index="$(pip config get global.index-url 2>/dev/null || true)"
  143. if [ -n "$pip_index" ]; then
  144. export UV_DEFAULT_INDEX="internal=${pip_index}"
  145. curl -sSfL https://aka.ms/conductor/install.sh | sh
  146. else
  147. printf '%s\n' 'No pip global.index-url; use the approved mirror URL above.'
  148. fi
  149. ```
  150. ```powershell
  151. # Windows
  152. $pipIndex = pip config get global.index-url 2>$null
  153. if ($pipIndex) {
  154. $env:UV_DEFAULT_INDEX = "internal=$pipIndex"
  155. irm https://aka.ms/conductor/install.ps1 | iex
  156. } else {
  157. Write-Host "No pip global.index-url; use the approved mirror URL above."
  158. }
  159. ```
  160. If the index requires credentials, uv accepts them inline in the URL or via
  161. `UV_INDEX_INTERNAL_USERNAME` / `UV_INDEX_INTERNAL_PASSWORD` — where `INTERNAL`
  162. is the index name from the `internal=` prefix (or the `name` key) above,
  163. upper-cased. See
  164. [uv's index documentation](https://docs.astral.sh/uv/concepts/indexes/#providing-credentials-directly).
  165. When an install fails because the index is unreachable, the install scripts say
  166. so explicitly and skip their retry backoff — retrying cannot fix a blocked
  167. index. Two related cases are reported separately rather than being blamed on
  168. the index:
  169. - **A blocked `github.com`.** The installer fetches Conductor itself from git,
  170. and uv words that failure the same way it words an index failure. No index
  171. setting fixes it, so the scripts say so and point at github.com instead.
  172. - **A transient connection blip.** These still get the full retry schedule,
  173. since unlike a policy block they can genuinely heal.
  174. If the error mentions a certificate, your network is inspecting TLS — trust
  175. your organization's root CA via `SSL_CERT_FILE`, or set `UV_SYSTEM_CERTS=1` to
  176. use the system trust store. For uv versions older than 0.11, use the legacy
  177. `UV_NATIVE_TLS=1` setting. If the error mentions a proxy (`407`), set
  178. `HTTPS_PROXY` / `NO_PROXY` as well as the index URL. Do not work around the
  179. block by disabling security tooling; ask your IT or platform team for the
  180. approved index endpoint.
  181. ### Use the Conductor skill in Claude Code or Copilot CLI
  182. This repo doubles as a single-plugin marketplace that ships the `conductor`
  183. skill from `plugins/conductor/skills/conductor/`. The skill teaches the
  184. assistant the workflow YAML schema, CLI commands, and execution model.
  185. **Claude Code:**
  186. ```text
  187. /plugin marketplace add microsoft/conductor
  188. /plugin install conductor@conductor
  189. ```
  190. **GitHub Copilot CLI** (`gh skill` requires GitHub CLI 2.91+, public preview):
  191. ```bash
  192. gh skill install microsoft/conductor conductor
  193. ```
  194. The plugin ships only markdown — no executables, hooks, or MCP servers — so
  195. trust verification is straightforward.
  196. ## Quick Start
  197. ### 1. Create a workflow file
  198. ```yaml
  199. # my-workflow.yaml
  200. workflow:
  201. name: simple-qa
  202. description: A simple question-answering workflow
  203. entry_point: answerer
  204. agents:
  205. - name: answerer
  206. model: gpt-5.5
  207. prompt: |
  208. Answer the following question:
  209. {{ workflow.input.question }}
  210. output:
  211. answer:
  212. type: string
  213. routes:
  214. - to: $end
  215. output:
  216. answer: "{{ answerer.output.answer }}"
  217. ```
  218. ### 2. Run the workflow
  219. ```bash
  220. conductor run my-workflow.yaml --input question="What is Python?"
  221. ```
  222. ### 3. View the output
  223. ```json
  224. {
  225. "answer": "Python is a high-level, interpreted programming language..."
  226. }
  227. ```
  228. ## Web Dashboard
  229. Conductor includes a built-in real-time web dashboard that lets you visualize and interact with your workflows as they run. Launch it with `--web`:
  230. ```bash
  231. conductor run workflow.yaml --web --input question="What is Python?"
  232. ```
  233. ![Web Dashboard](docs/img/web-dashboard.png)
  234. **Key features:**
  235. - **Interactive DAG graph** — Zoomable, draggable workflow graph with animated edges showing execution flow and conditional routing
  236. - **Live agent streaming** — Watch agent reasoning, tool calls, and outputs stream in real-time as each step executes
  237. - **Three-pane layout** — Resizable panels for the graph, agent detail, and a tabbed output pane (Log, Activity, Output)
  238. - **In-browser human gates** — Respond to human-in-the-loop decision points directly in the dashboard, no terminal needed
  239. - **Per-node detail** — Click any node to see its prompt, metadata (model, tokens, cost), activity stream, and output
  240. - **Mid-run guidance** — Send a correction to a running workflow — via the dashboard's **Guide** button or `conductor guide --text "..."` — without stopping it first. Works with both `--web` and `--web-bg`.
  241. - **Background mode** — Run with `--web-bg` to start the dashboard in the background, print the URL, and exit. Use `conductor stop` to shut it down later and `conductor status` to list what's running.
  242. ```bash
  243. # Run in background — prints dashboard URL and exits
  244. conductor run workflow.yaml --web-bg --input topic="AI in healthcare"
  245. # Send mid-run guidance to a running background workflow
  246. conductor guide --text "Prefer Python 3.12 examples"
  247. # Stop a background workflow
  248. conductor stop
  249. ```
  250. ## Fleet Manager (TUI)
  251. The dashboard shows you one run in depth. The **Fleet Manager** shows you *every* run at once — and it's where you go when something needs you. Launch it with `conductor fleet`:
  252. ```bash
  253. # One-time: the TUI ships as an optional extra.
  254. curl -sSfL https://aka.ms/conductor/install.sh | sh -s -- --extras tui
  255. conductor fleet
  256. ```
  257. > The install command depends on how you installed Conductor. Running `conductor fleet`
  258. > without the extra prints the one that works on your machine — pinned to the version
  259. > you are running and carrying any extras you already have, because `uv tool install
  260. > --force` replaces the tool's whole requirement set. `conductor update` carries them
  261. > forward for the same reason.
  262. ![Fleet Manager](docs/img/fleet-manager.png)
  263. > **TUI = breadth. Dashboard = depth.**
  264. >
  265. > The TUI answers *"what's happening across my fleet, and what needs me?"* The dashboard answers *"what exactly is this one run doing?"* They compose — press `w` on any run to open its dashboard in a browser.
  266. **Key features:**
  267. - **Every run is discoverable** — Foreground, `--web`, and `--web-bg` runs all appear. Previously only `--web-bg` runs were visible to `conductor stop`; a plain `conductor run` had to be hunted down and killed by hand.
  268. - **Live fleet table** — Each run's status, current step, elapsed time, tokens, cost, and a token-burn sparkline, polled continuously and sorted by recency
  269. - **Gates that find you** — A run blocked on a human gate is badged in the table and fires a terminal bell, so a waiting workflow doesn't sit unnoticed. Press `g` to answer it without leaving the TUI.
  270. - **Drill down** — `enter` opens a run's per-agent breakdown, then `enter` again on any step shows what it actually did: its input, output, and activity stream
  271. - **Launch new runs** — `n` builds a form from a workflow's declared `input:` block and starts it in the background, so the TUI both watches and starts work
  272. - **Browse and re-run** — Providers and model diagnostics (`p`), registries and their workflows (`r`), and History (`h`) for finished runs, which hands off to `conductor replay`
  273. - **Kill safely** — `k` stops the selected run, `K` the whole fleet. Both confirm first, and a foreground run is named explicitly, since stopping one discards in-flight progress unless periodic checkpoints are enabled.
  274. ```bash
  275. # Not interactive? These need no extra dependency:
  276. conductor fleet list # table of every live run
  277. conductor stop # stop the only running workflow, or list them
  278. conductor fleet prune # bound the event logs in $TMPDIR/conductor
  279. ```
  280. See [docs/fleet.md](docs/fleet.md) for every screen, key binding, the status vocabulary, and retention settings.
  281. ## Providers
  282. Conductor supports multiple AI providers. Choose based on your needs:
  283. | Feature | Copilot | OpenAI | Claude | Claude Agent SDK | Hermes | ACA |
  284. |---------|---------|--------|--------|------------------|--------|-----|
  285. | **Tier** | Stable | Stable | Stable | Experimental | Experimental | Experimental |
  286. | **Pricing** | Subscription | Pay-per-token | Pay-per-token | Subscription | Pay-per-token (via hermes) | Subscription + ACA compute |
  287. | **Context Window** | Per-model | Per-model | Per-model | Per-model | Per-model | Per-model (inner Copilot) |
  288. | **Tool Support (MCP)** | Yes | Yes (stdio) | Yes (stdio) | Yes (built-in) | No (hermes internal tools) | Yes (always forwarded, not allowlisted) |
  289. | **Streaming** | Yes | Yes | Yes | Yes | No | Yes |
  290. | **Best For** | Heavy usage, tools | OpenAI ecosystem, pay-per-use | Large context, pay-per-use | Full Claude Code toolset | Multi-provider model access | Untrusted/isolation-sensitive agents |
  291. ### Using Copilot
  292. ```yaml
  293. workflow:
  294. runtime:
  295. provider: copilot
  296. default_model: gpt-5.5
  297. ```
  298. Copilot is the default provider — `runtime.provider` can be omitted entirely. Requires an active GitHub Copilot subscription and the GitHub CLI authenticated (`gh auth login`).
  299. ### Using OpenAI
  300. ```yaml
  301. workflow:
  302. runtime:
  303. provider: openai
  304. default_model: gpt-5.6-terra
  305. ```
  306. Set your API key: `export OPENAI_API_KEY=sk-...`
  307. ### Using Claude
  308. ```yaml
  309. workflow:
  310. runtime:
  311. provider: claude
  312. default_model: claude-sonnet-5
  313. ```
  314. Set your API key: `export ANTHROPIC_API_KEY=sk-ant-...`
  315. ### Using Claude Agent SDK (Experimental)
  316. ```yaml
  317. workflow:
  318. runtime:
  319. provider: claude-agent-sdk
  320. default_model: claude-sonnet-5
  321. ```
  322. Requires the `claude` CLI to be installed and authenticated. Install the SDK: `uv add 'claude-agent-sdk>=0.2.82'`
  323. > **Note:** `runtime.mcp_servers` is supported — servers are translated into the SDK's own MCP config and attach alongside the built-in `claude_code` preset (a narrowing per-server `tools:` filter is refused, since the SDK cannot enforce one). Per-agent tool allowlists are not bridged: a workflow-level `tools:` block is rejected at `conductor validate` for any agent that omits `tools:` (it would otherwise inherit a list the CLI can't map). Omit `tools:` to grant the full `claude_code` preset; an agent's `tools: []` disables the built-in tools, though declared MCP servers still attach.
  324. ### Using Hermes (Experimental)
  325. ```yaml
  326. workflow:
  327. runtime:
  328. provider: hermes
  329. default_model: anthropic/claude-sonnet-5
  330. ```
  331. Install the library: `pip install hermes-agent`
  332. ### Using ACA (Experimental)
  333. ```yaml
  334. workflow:
  335. runtime:
  336. provider:
  337. name: aca
  338. pool_endpoint: "https://my-agent-pool.example.westus2.azurecontainerapps.io"
  339. inner_provider: copilot
  340. default_model: gpt-5.6-terra
  341. ```
  342. The `aca` provider delegates an agent's entire agentic loop, tools, and MCP calls to a remote **Azure Container Apps dynamic-sessions sandbox** instead of running it on the host — useful for untrusted or isolation-sensitive agents (e.g. running arbitrary generated code). Unlike the other providers, `aca` requires the structured `provider:` form with a `pool_endpoint` pointing at an operator-provisioned ACA session pool (`scripts/aca/provision-pool.sh`) and `azure-identity` for authentication. Resolves its inner Copilot credential automatically via `COPILOT_PROVIDER_BASE_URL` → `COPILOT_GITHUB_TOKEN`/`GH_TOKEN`/`GITHUB_TOKEN` → `gh auth token`, so a `gh`-authenticated operator needs no ACA-specific setup. See [`examples/aca-coding-agent.yaml`](examples/aca-coding-agent.yaml) for a full end-to-end example.
  343. **See also:** [OpenAI Documentation](docs/providers/openai.md) | [Claude Documentation](docs/providers/claude-provider.md) | [Hermes Documentation](docs/providers/hermes.md) | [ACA Documentation](docs/providers/aca.md) | [Provider Comparison](docs/providers/comparison.md) | [Migration Guide](docs/providers/migration.md)
  344. ### Using a Local / Custom LLM Endpoint (Ollama, vLLM, Azure OpenAI, ...)
  345. `runtime.provider` also accepts a structured object that routes the
  346. Copilot SDK at any OpenAI-compatible / Azure / Anthropic-shaped endpoint.
  347. Useful for local inference (Ollama, vLLM, LM Studio) and managed
  348. deployments (Azure OpenAI):
  349. ```yaml
  350. workflow:
  351. runtime:
  352. provider:
  353. name: copilot
  354. type: openai # openai | azure | anthropic
  355. wire_api: completions # completions | responses
  356. base_url: http://localhost:11434/v1
  357. api_key: ${OPENAI_API_KEY:-ollama}
  358. default_model: llama3.1 # match your endpoint's model name
  359. ```
  360. The structured form is opt-in: a bare `provider: copilot` keeps the
  361. default GitHub Copilot routing. See
  362. [`examples/copilot-local-llm.yaml`](examples/copilot-local-llm.yaml) for
  363. the full example (including an Azure OpenAI variant) and
  364. [Configuration Guide → Custom Provider Routing](docs/configuration.md#custom-provider-routing-ollama--vllm--azure-openai)
  365. for environment-variable fallbacks, security notes, and validator rules.
  366. ## CLI Reference
  367. ### `conductor run`
  368. Execute a workflow from a YAML file.
  369. ```bash
  370. conductor run <workflow.yaml> [OPTIONS]
  371. ```
  372. | Option | Description |
  373. |--------|-------------|
  374. | `-i, --input NAME=VALUE` | Workflow input (repeatable) |
  375. | `-m, --metadata KEY=VALUE` | Workflow metadata (repeatable; surfaced in `workflow_started`) |
  376. | `--workspace-instructions` | Auto-discover `AGENTS.md` / `CLAUDE.md` / `.github/copilot-instructions.md` and prepend to every agent prompt |
  377. | `--instructions PATH` | Explicit instructions file (repeatable) |
  378. | `-p, --provider PROVIDER` | Override provider |
  379. | `--dry-run` | Preview execution plan |
  380. | `--skip-gates` | Auto-select at human gates |
  381. | `--web` | Start real-time web dashboard |
  382. | `--web-bg` | Run in background, print dashboard URL, exit |
  383. | `--web-port PORT` | Port for web dashboard (0 = auto) |
  384. | `-l, --log-file PATH` | Write logs to file |
  385. Output verbosity is controlled by **root-level options**, which must appear
  386. *before* the subcommand:
  387. ```bash
  388. conductor --quiet run workflow.yaml # -q: minimal output (agent lifecycle and routing only)
  389. conductor --silent run workflow.yaml # -s: no progress output (JSON result only)
  390. ```
  391. ### `conductor validate`
  392. Validate a workflow file without executing.
  393. ```bash
  394. conductor validate <workflow.yaml>
  395. ```
  396. ### `conductor fleet`
  397. Discover and manage every running `conductor` process — foreground,
  398. `--web`, or `--web-bg`. See [Fleet Manager](#fleet-manager-tui) above for
  399. the interactive TUI; these need no extra dependency:
  400. ```bash
  401. conductor stop # stop the only running workflow, or list them
  402. conductor fleet list # non-interactive table of every live run
  403. conductor fleet # interactive TUI (requires the `tui` extra)
  404. ```
  405. See [docs/fleet.md](docs/fleet.md) for the TUI's screens, key bindings, and
  406. status vocabulary.
  407. **Full CLI documentation:** [docs/cli-reference.md](docs/cli-reference.md)
  408. ## Workflow Registries
  409. Conductor supports named workflow registries — GitHub repos or local directories
  410. containing shared workflows. Configure a registry once, then run workflows by
  411. short name.
  412. ### Quick start
  413. ```bash
  414. # Add a registry
  415. conductor registry add official myorg/conductor-workflows --default
  416. # List available workflows
  417. conductor registry list official
  418. # Run a workflow from the registry
  419. conductor run qa-bot # latest from default registry
  420. conductor run 'qa-bot@official#v1.2.3' # specific tag (quote the #)
  421. conductor run 'qa-bot@official#main' # branch HEAD (re-resolved on fetch)
  422. ```
  423. See [docs/design/registry.md](docs/design/registry.md) for the full design.
  424. ## Examples
  425. See the [`examples/`](./examples/) directory for complete workflows:
  426. | Example | Description |
  427. |---------|-------------|
  428. | [simple-qa.yaml](./examples/simple-qa.yaml) | Basic single-agent Q&A |
  429. | [for-each-simple.yaml](./examples/for-each-simple.yaml) | Dynamic parallel processing |
  430. | [parallel-research.yaml](./examples/parallel-research.yaml) | Static parallel execution |
  431. | [design-review.yaml](./examples/design-review.yaml) | Human gate with loop pattern |
  432. | [script-step.yaml](./examples/script-step.yaml) | Script step with exit_code routing |
  433. | [set-step.yaml](./examples/set-step.yaml) | Set step deriving named values + boolean-routed branching |
  434. | [mcp-step.yaml](./examples/mcp-step.yaml) | Direct MCP tool execution with structured routing and error handling |
  435. | [wait-step.yaml](./examples/wait-step.yaml) | Wait step + script for a polling loop-back pattern |
  436. | [wait-smoke.yaml](./examples/wait-smoke.yaml) | Minimal wait-only smoke test (no provider required) |
  437. | [terminate.yaml](./examples/terminate.yaml) | Explicit `type: terminate` with success and failure paths |
  438. **More examples and running instructions:** [examples/README.md](./examples/README.md)
  439. ## Documentation
  440. | Document | Description |
  441. |----------|-------------|
  442. | [Workflow Syntax](./docs/workflow-syntax.md) | Complete YAML schema reference |
  443. | [CLI Reference](./docs/cli-reference.md) | Full command-line documentation |
  444. | [Fleet Manager](./docs/fleet.md) | `conductor fleet` TUI: screens, key bindings, gate resolvability, retention |
  445. | [Parallel Execution](./docs/parallel-execution.md) | Static parallel groups |
  446. | [Dynamic Parallel](./docs/dynamic-parallel.md) | For-each groups and array processing |
  447. | [OpenAI Provider](./docs/providers/openai.md) | OpenAI setup and configuration |
  448. | [Claude Provider](./docs/providers/claude-provider.md) | Claude setup and configuration |
  449. | [Hermes Provider](./docs/providers/hermes.md) | Hermes setup and configuration |
  450. | [ACA Provider](./docs/providers/aca.md) | Azure Container Apps sandboxed execution setup and configuration |
  451. | [Provider Comparison](./docs/providers/comparison.md) | Copilot vs Claude vs Hermes decision guide |
  452. ## Development
  453. Contributor guides covering each subsystem's invariants, change checklists, and
  454. regression tests live in [docs/development/](docs/development/README.md).
  455. ### Prerequisites
  456. - Python 3.12+
  457. - [uv](https://github.com/astral-sh/uv) for dependency management
  458. ### Setup
  459. ```bash
  460. git clone https://github.com/microsoft/conductor.git
  461. cd conductor
  462. make dev
  463. ```
  464. ### Windows
  465. On Windows, use `uv` directly instead of `make`:
  466. ```powershell
  467. uv sync --all-extras # instead of make dev
  468. uv run pytest -n 4 --dist loadfile -m "not real_api and not install_scripts and not performance"
  469. uv run pytest -n 0 -m "not real_api and not install_scripts and not performance" # serial debugging
  470. uv run ruff check . # instead of make lint
  471. uv run ruff format . # instead of make format
  472. ```
  473. **Copilot CLI path:** Windows `subprocess` cannot resolve `.bat`/`.ps1` wrappers by name alone. If you see `[WinError 2] The system cannot find the file specified` when running workflows, set the full path to the Copilot CLI:
  474. ```powershell
  475. # Find your copilot CLI
  476. Get-Command copilot* | Format-Table Name, Source
  477. # Set the path (use the .cmd variant from npm)
  478. $env:COPILOT_CLI_PATH = "C:\Users\<you>\AppData\Roaming\npm\copilot.cmd"
  479. ```
  480. ### Common Commands
  481. ```bash
  482. make test # Run tests in parallel (4 workers by default)
  483. make test-cov # Run tests in parallel with coverage
  484. PYTEST_WORKERS=0 make test # Run tests serially for debugging
  485. make lint # Check linting
  486. make format # Auto-fix and format code
  487. make typecheck # Type check
  488. make check # Run all checks (lint + typecheck)
  489. make validate-examples # Validate all example workflows
  490. ```
  491. ### Code Style
  492. - [Ruff](https://github.com/astral-sh/ruff) for linting and formatting
  493. - [ty](https://github.com/astral-sh/ty) for type checking
  494. - Google-style docstrings
  495. ## Contributing
  496. This project welcomes contributions and suggestions. Most contributions require you to agree to a
  497. Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
  498. the rights to use your contribution. For details, visit [Contributor License Agreements](https://cla.opensource.microsoft.com).
  499. When you submit a pull request, a CLA bot will automatically determine whether you need to provide
  500. a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
  501. provided by the bot. You will only need to do this once across all repos using our CLA.
  502. This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
  503. For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
  504. contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
  505. To submit a pull request, follow these steps:
  506. 1. Fork the repository
  507. 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
  508. 3. Make your changes
  509. 4. Add a changelog fragment in `changelog.d/` if your change is user-facing (see below)
  510. 5. Run tests and checks (`make test && make check`)
  511. 6. Commit your changes (`git commit -m 'Add amazing feature'`)
  512. 7. Push to the branch (`git push origin feature/amazing-feature`)
  513. 8. Open a Pull Request
  514. <a id="changelog"></a>
  515. ### Changelog fragments
  516. Every pull request with user-facing changes must include a changelog fragment under `changelog.d/`. Never edit `CHANGELOG.md` directly in a pull request. Maintainers can apply the `changelog-not-required` label to exempt trivial, internal, or bootstrap changes from both the fragment requirement and the `CHANGELOG.md` edit prohibition (any fragments present are still validated).
  517. Name your fragment `<issue>.<category>.md` (e.g. `392.added.md`) or `+<slug>.<category>.md` (e.g. `+my-feature.added.md`), where category is one of `added`, `fixed`, `changed`, or `removed`. See [`changelog.d/README.md`](changelog.d/README.md) for the full fragment contract and examples.
  518. ## Trademarks
  519. This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
  520. trademarks or logos is subject to and must follow
  521. [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general).
  522. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
  523. Any use of third-party trademarks or logos are subject to those third-party's policies.
  524. ## License
  525. MIT License - see [LICENSE](./LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.