Agency Orchestrator: a YAML workflow engine that turns one sentence into a team of AI roles

The problem: one chat model gives you one perspective

The README frames the gap in a single line: talking to one AI gives you one viewpoint, while a decision needs the product view, the technical view, the financial view and the marketing view. Agency Orchestrator answers that by running several roles over the same brief and merging their output. The README's own comparison table puts a single general role against its 276 professional roles, and puts conversation against a one-sentence prompt or a YAML file.

The target user is not a framework author. It is someone who wants a feasibility analysis, a technical selection report, a long article or a pricing proposal, and who does not want to build the orchestration layer. The README lists exactly those cases as example commands, from a startup feasibility study to a PR code review covering security and performance.

How the engine turns a sentence into a DAG

The pipeline described in the README has four stages. A sentence goes in. The engine decomposes it into tasks. It matches those tasks against the role library, which the README gives as 276 Chinese roles plus 184 English roles plus five more language libraries (ko, ru, pt-BR, id, ar). Then it executes the resulting graph, running independent steps in parallel.

The demo output in the README shows what that looks like in practice for a five-step plan: a trend researcher, a platform analyst, a financial planner, a content strategist and an execution planner, each finishing separately with its own elapsed time, followed by a total of 5/5 steps, 182.1s and 6,493 tokens. The parallelism is not hand-wired. The README states the DAG is detected automatically, which is the main mechanical difference from graph frameworks where you declare the edges yourself.

The unit of configuration is YAML. A workflow declares steps, roles and, in the one-person-company templates, acceptance criteria under an acceptance key. The README also describes an image and video pipeline with type: image, type: video, type: concat and a style library, where concat uses local ffmpeg to join shots. That is a wider scope than most orchestration engines, and it is the part of the README that reads most like a product roadmap rather than a specification.

Installing Agency Orchestrator and running a first workflow

The CLI is published on npm. The README gives a single global install command, which puts the ao binary on your path alongside agency-orchestrator.

npm install -g agency-orchestrator

The README draws a distinction worth reading before you install anything. The desktop client ships with its own engine and Node, so it needs no global npm install. You only need the CLI if you want ao in a terminal, or if you want to call it from scripts and CI.

The fastest first run uses a provider you already have. If Claude Code is installed and logged in on the machine, the README says AO detects it and uses it without an API key. The same command works with a key-based provider if you set the environment variable first.

ao compose "我是一个程序员，想用AI做自媒体副业，目标月入2万，帮我做完整规划" --run --provider claude-code

export DEEPSEEK_API_KEY="你的key"
ao compose "帮我分析做一个AI记账工具的可行性" --run

What you should see is the workflow header with a step count and the detected model, then one line per role as it finishes, then a completion summary with the step total and token count. The README's own example shows 5 roles, 5/5 steps, 182.1s and 6,493 tokens for a side-business planning brief.

If you prefer a browser, the README gives ao web for a local Studio where you pick roles, run workflows and inspect artifacts. For a NAS or home server, the repository ships a compose file that publishes port 8088 and keeps keys and artifacts in a named volume.

docker run -d -p 8088:8088 -v ao-data:/data ghcr.io/jnmetacode/agency-orchestrator:latest

The Dockerfile sets HOST=0.0.0.0, PORT=8088 and AO_DATA_DIR=/data, and its health check calls /api/health on that port. Two directories matter if you self-host: AO_AGENTS_DIR for the role library and AO_HOME for a shared workspace.

Where the design shows its seams

The dependency on external provider CLIs is the sharpest constraint. Using --provider claude-code, gemini-cli or codex-cli requires that CLI to be installed and logged in on the same machine. The README is explicit about this, and it is the reason the zero-configuration first run is conditional rather than universal. On a fresh server with no CLI and no key, nothing runs.

Automatic role matching is the second soft spot. The README sells it as the reason you do not have to choose roles, and for broad briefs that is a real convenience. But matching is a heuristic over a 276-role library, and the README does not publish the matching rules or a way to inspect why a particular role was selected. If your brief is narrow or uses vocabulary the roles do not cover, you have no documented lever except writing the workflow by hand.

The README is also candid about scope in one place: the one-person-company templates deliver an inspectable work product with acceptance criteria, and the README states the project does not promise miracles. That sentence is doing more work than it looks like. Treat the output as a draft that a human signs off, which is literally what the research template's approval gate models.

Finally, the role count is not the same across languages. The package description lists 267 Chinese roles while the README headline says 276, and the English library is 184. If your work is in English, you are choosing from a smaller set than the headline number suggests.

Agency Orchestrator against CrewAI and LangGraph

The README positions the project against CrewAI and LangGraph directly, and the repository topics include crewai-alternative and langgraph-alternative. The difference in approach is where the workflow lives. In CrewAI and LangGraph, the workflow is Python code: you define agents, tasks and edges, and you control the graph explicitly. In Agency Orchestrator, the workflow is a YAML document, and the graph is inferred. The README's comparison table reduces this to two rows: write Python versus one sentence or YAML, and manual graph construction versus automatic DAG detection.

That trade is real in both directions. Code-defined graphs give you conditionals, loops and exact control over what runs when, and they are testable the way any other code is. YAML plus inference gives you a working multi-role run in one command, at the cost of visibility into why the graph came out the way it did. If your orchestration needs to be audited line by line, the code-first tools are the better fit. If you want a five-role analysis before lunch, the YAML route is shorter.

The second axis is provider access. CrewAI and LangGraph assume an API key. Agency Orchestrator's README claims 15 providers with 11 that need no key, using locally installed CLIs as the transport. That is the most distinctive part of the design, and also the part most exposed to changes in those CLIs.

Licence, maintenance and what an upgrade costs you

The project is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. As with any Apache-2.0 dependency, if you redistribute a modified version you carry the notice and attribution obligations, and if you ship it as part of a larger product you should read the NOTICE and patent-termination clauses rather than assume they do not apply. That is a description of the licence, not legal advice.

The last push to the default branch was on 2026-09-10, and the desktop line saw releases on 2026-08-21 and 2026-08-28, so the repository is not archived and is being worked on. The npm package is at 0.19.2. Upgrades are cheap if you use the npm channel: the Dockerfile installs agency-orchestrator@latest by default and accepts an AO_VERSION build argument, so pinning is a one-line change. Self-hosted deployments keep state in the /data volume, which the Dockerfile documents as holding web-keys.json, ao-output and ao-workflows. Any migration that changes those paths is the thing to watch on upgrade, because that is where your keys and artifacts live.

Editorial conclusion

Adopt Agency Orchestrator if you want multi-role output from one sentence and would rather edit YAML than write an agent graph in Python. Skip it if you need deterministic, code-defined control flow, or if you cannot install or log in to one of the supported CLIs or supply a provider key. Before committing, verify three things on your own machine: that ao compose picks the provider you expect, that the role library you need is present in the language you want, and that the acceptance criteria in the template you plan to run match what you actually have to deliver.

Frequently asked questions

Official sources

1. jnMetaCode/agency-orchestrator on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases