Agency Orchestrator: YAML Workflows and a 276-Role Library for Multi-Agent Deliverables

The Problem: One Model Gives One Perspective

Ask a single chat model to plan a product and you get one voice. The README states the case plainly: a decision needs the product view, the technical view, the financial view and the marketing view, and a single conversation supplies one of them. Agency Orchestrator's answer is to split the request across several named roles that work separately and then combine their output. The README's own framing is "one person versus a team."

The target user is not a library author. It is someone who wants a finished deliverable (a feasibility study, a pricing analysis, a code review, a 90-day plan) and does not want to write Python to get it. The README's comparison table puts CrewAI and LangGraph on the "write Python" side and this project on the "one sentence or YAML" side. That is the whole positioning: the orchestration is the product, and the user is expected to supply an idea rather than a graph.

How a Sentence Becomes a DAG of Named Specialists

The documented flow is: a sentence goes in, the system decomposes it into tasks, matches roles from the library, executes the resulting graph in parallel where dependencies allow, and writes out the combined result. The README describes this as "DAG automatic detection," and the comparison table lists it as the difference from building the graph by hand.

The role library is the substance behind that matching. The repository description counts 276 Chinese roles plus 184 English roles, with additional packs for Korean, Russian, Brazilian Portuguese, Indonesian and Arabic, distributed as separate npm packages (the README gives `npm i agency-agents-ko` as the example for the ko/ru/pt-br/id/ar group). A workflow can point at a pack by name through the `agents_dir` key. The Studio's role picker groups the 276 Chinese experts by domain, with seven executive roles from a company-operations section pinned at the top, and supports favourites plus a "my roles" category for prompts saved from the prompt-generation page into `~/.ao/roles`.

So the unit of composition is not a function call. It is a role card: a name, an icon, a domain and a system prompt. The engine chooses among those cards, and the user can override the choice or write new cards. That is a different design from an agent framework where an agent is a class with tools and a state machine.

Compose, Run and the YAML That Sits Between Them

There are two entry points. `ao compose "..." --run` takes a sentence, builds the workflow and executes it. `ao run <file.yaml> --input key=value` executes a workflow you already have. The README's example output for a compose run shows five roles (trend researcher, platform analyst, financial planner, content strategist, execution planner) running in sequence with per-step timings and a token total, which tells you the engine reports per-step duration and token usage rather than only a final answer.

Inputs are passed with `-i` or `--input`, and the README shows a file-reference form: `ao run workflows/dev/pr-review.yaml --input code=@src/main.ts`. The `@` prefix reads the value from a file, which is how you feed real source into a review workflow without pasting it. The repository ships built-in workflows under `workflows/`, including `workflows/一人公司全员大会.yaml` and `workflows/story-creation.yaml`, and the README claims 60+ built-in templates with English versions.

Two flags matter for unattended use. `--provider` selects the model backend, for example `--provider claude-code`. `--notify <webhook>` pushes the finished result to DingTalk, Feishu or WeCom, with the README stating that the robot payload format is chosen automatically from the webhook domain. Combined with cron, that is the documented path to a scheduled delivery. A separate `ao report` command (the Studio button is "share page") emits a self-contained single-file HTML report with the role timeline and each step's output, intended to be forwarded to people who do not have the tool installed.

Providers: Keys, Key-Free CLI Agents, and What Each Requires

The repository description says 15 LLM providers, 11 of which need no key. The mechanism is detection: if Claude Code, Gemini CLI or Codex CLI is installed and logged in on the machine, the README states that the tool finds it and uses it with no configuration and no API key. The DeepSeek path is the documented key-based default: set `DEEPSEEK_API_KEY` and run. The README recommends DeepSeek on cost grounds and notes that API-key providers need no CLI installed at all.

The trade-off is explicit in the install section. Choosing `--provider claude-code` (or `gemini-cli`, `codex-cli`) means you must already have that CLI installed and authenticated. Choosing a key-based provider means the opposite: no CLI, but a key and a per-token bill. Neither path is free of prerequisites; they just move the prerequisite.

The Studio runs locally via `ao web`, and the README states that keys stay on your machine. In the Docker deployment the story changes: `docker run -d -p 8088:8088 -v ao-data:/data ghcr.io/jnmetacode/agency-orchestrator:latest` exposes port 8088, and the README says keys are configured in the page's provider panel and stored in the mounted volume so they survive restarts. A docker-compose.yml exists at the repository root as an alternative. Anyone running that container on a shared host should treat the volume as a secret store.

Acceptance Criteria, the Boss Gate, and the Human Checkpoint

The interesting design choice is that steps can carry acceptance criteria, written as the `acceptance` key in the workflow YAML. The README describes the "one-person company" template series (product, content, investment research, plus an all-hands meeting) as having acceptance standards on key steps, and describes the investment-research template as including a boss-signature gate. The README is also careful about what this means, describing the output as verifiable work products and stating that no miracles are promised.

That is the honest framing. An acceptance criterion here is text evaluated by a model, not an assertion evaluated by a runtime. It can catch a step that produced a plan with no numbers in it. It cannot prove the numbers are right. The signature gate is a pause for a human decision, which is a workflow feature rather than a correctness guarantee. If you need the second kind of check, you are writing tests around the output yourself.

The same caution applies to the role library. A role is a system prompt with a label. Reading the YAML is the only way to know what a given role actually instructs, and the README's own course material is described as documenting "honest usage boundaries" and "seven kinds of failure scenes," which suggests the authors do not present the role count as a quality measure either.

Where It Fits Badly

This is a prompt-orchestration layer, not a deterministic pipeline. If your requirement is that step three always produces a machine-parseable object that step four validates, the natural home for that logic is a framework where agents are code and edges are typed: LangGraph is the obvious comparison, and the README itself lists it as the thing this project replaces. The difference in approach is concrete. In LangGraph you write the nodes, the state schema and the conditional edges in Python, and you can unit-test them. Here you write YAML and prose role definitions, and the engine decides how a sentence decomposes. That buys you speed of authoring and costs you testability.

Two more limits are visible in the material. First, the strongest out-of-the-box experience is Chinese: 276 roles against 184 English ones, and the primary README is Chinese with a separate English file. English users get a complete interface per the README, but a smaller role pool. Second, the Studio is a local web app or a desktop app. It is not a hosted service, so there is no shared workspace, no team account, and no server-side run history. The share page exists precisely because the recipient cannot log in to your instance; it is a static HTML file, not a collaborative dashboard.

Finally, the project's own README spends a full section on a Claude Code provider switcher that writes a global config, backs it up before writing, and can restore official login, plus a health-check card that repairs a broken `~/.claude`. That is a useful utility, and its presence tells you the maintainers expect users to be swapping provider endpoints on a working machine. If you would rather not have a tool touch your global CLI configuration, that feature is a reason to look elsewhere, not a bonus.

Install, Packaging and the Apache-2.0 Boundary

The CLI installs with `npm install -g agency-orchestrator`. The README notes the desktop client bundles the engine and Node, so it needs no global install; the CLI is for terminal, script and CI use. Directory overrides are `AO_DATA_DIR` for artifacts and data, `AO_AGENTS_DIR` for the role library, and `AO_HOME` for a unified workspace. The desktop build defaults its data directory to the Electron userData path. Docker images are published for amd64 and arm64.

Releases follow a desktop version line: desktop-v0.4.8, desktop-v0.4.9 and desktop-v0.4.10 all landed within about a week in late August 2026, with the repository's last push dated 2026-09-10. That cadence is consistent with an actively maintained desktop client, and it also means desktop users should expect to reinstall or auto-update often. The npm package and the desktop app version independently, so a CLI-only user and a desktop user can be on different engine versions.

On licensing, the repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. The role libraries for Korean, Russian, Brazilian Portuguese, Indonesian and Arabic ship as separate npm packages, so their licence terms should be checked separately rather than assumed to match the main repository. The README also links to paid-adjacent material (courses, a Studio, a homepage at ao.aiolaola.com), and it describes the courses as free; nothing in the supplied material states terms for the hosted site. That is a question to resolve before depending on it. None of this is legal advice.

Who Should Pick It Up, and the First Thing to Verify

The fit is a solo operator or a small team that wants a repeatable multi-role deliverable and is comfortable reading YAML. If you already pay for a Claude or Gemini plan, the key-free detection path means your first run costs nothing beyond the install. If you are on DeepSeek, the README positions the per-run cost as low and the key setup as one environment variable. Either way the first hour is short: install, run one built-in template with a real input file, read the generated workflow.

The mismatch cases are equally clear. Teams that need typed state between steps, deterministic retries, or CI assertions on intermediate outputs should stay with a code-first framework. Teams that need a shared hosted workspace will find the local-only Studio and the static share page insufficient. Anyone unwilling to let a tool rewrite global CLI configuration should disable or avoid the provider-switch feature.

The specific thing to verify before wider adoption is the generated workflow itself, not the demo. Run `ao run workflows/dev/pr-review.yaml --input code=@src/main.ts` against a file you know well, then open the workflow YAML and read the `acceptance` entries on each step. If those criteria are the ones you would have written, the template is doing real work for you. If they are generic, you are looking at a well-packaged prompt chain, and you should budget time to rewrite the criteria before trusting the output.

Editorial conclusion

Adopt it if you want a multi-role pipeline you can define in YAML and run from a terminal, a browser or a container, and if you already have a Claude Code, Gemini CLI or Codex CLI login on the machine. Skip it if you need typed, testable agent graphs: role behaviour here lives in prompt text and language packs, not in code you can assert against. Before committing, run one built-in workflow such as workflows/dev/pr-review.yaml with a real input file, then open the produced YAML and check that the acceptance criteria on each step are the ones you would have written yourself.

Official sources

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