jnMetaCode/agency-orchestrator

Agency Orchestrator – What It Is

Agency Orchestrator (AO) is a Node‑JS‑based tool that lets you run multiple AI “experts” together to solve a task. You either write a tiny YAML workflow that describes which roles should act, what they should do, and how the steps depend on each other, or you let AO generate that workflow for you from a single natural‑language prompt. The engine then calls the selected large‑language‑model (LLM) providers, runs the steps in parallel where possible, and stitches the outputs together into a final deliverable.

Core ideas

Concept	How AO implements it
Multi‑agent collaboration	AO ships with a library of 267 Chinese‑language roles (and optional multilingual packs). Each role is just a system‑prompt that tells an LLM to act as a specific expert (e.g., “Product Manager”, “Financial Planner”).
Zero‑code orchestration	You can run ao compose "<task description>" --run and AO will pick the right experts, design a DAG (directed‑acyclic‑graph) of steps, and execute it. No YAML, no code required.
YAML workflow files	For repeatable pipelines you write a short YAML file that lists steps, the role for each step, the task prompt, optional acceptance criteria, and depends_on relationships. AO parses the file, builds the DAG, and runs it.
Graphical Studio	A local web UI (ao web) lets you drag‑and‑drop nodes, select roles, edit prompts, and watch live progress. The UI mirrors the CLI – the same role library and workflow files are shared.
Provider flexibility	AO can use 11 LLM providers (Claude, DeepSeek, OpenAI, Gemini, etc.). Seven of them work without an API key by leveraging locally installed CLIs (Claude‑code, Copilot‑cli, etc.).
Safety‑first service switching	AO can replace the underlying Claude service with a custom endpoint and automatically backs up the original config, allowing a one‑click revert if something goes wrong.
Result sharing	After a run you can generate a self‑contained HTML report (ao report) or push the output to DingTalk, Feishu, or WeChat groups via a webhook (--notify).

Who Might Use It?

• Solo entrepreneurs who want an “AI‑powered team” to draft business plans, market analyses, content calendars, etc.
• Product managers needing rapid feasibility studies, PRD reviews, or multi‑disciplinary design reviews.
• Developers who want AI‑generated code reviews, architecture assessments, or scaffolding that can then be handed off to a coding agent.
• Content creators looking for AI‑driven brainstorming, script writing, and video‑generation pipelines.
• Teams that want a repeatable, auditable workflow (acceptance criteria, versioned outputs, resumable runs).

Getting Started (3‑step quick start)

1. Install – npm install -g agency-orchestrator (or download the Electron desktop client for a zero‑install experience).
2. Run a one‑liner – ao compose "帮我分析做一个AI记账工具的可行性" --run. AO picks the right experts, builds the DAG, and prints a concise summary.
3. Explore templates – ao run workflows/一人公司全员大会.yaml -i idea="..." runs a pre‑built “one‑person company” workflow that includes planning, marketing, finance, etc.

Key Commands (CLI cheat‑sheet)

Command	What it does
ao demo	Quick demo of multi‑agent collaboration.
ao compose "<sentence>"	Generate a workflow from natural language.
ao compose "..." --run	Generate and execute it immediately.
ao run <workflow.yaml>	Execute a saved YAML workflow.
ao team save <workflow.yaml> --name <team>	Save the role lineup as a reusable “team”.
ao run --team <team> "<new task>"	Re‑use a saved team on a fresh prompt.
ao prompt optimize "<prompt>" --save <name>	Let AO improve a prompt and store it.
ao report	Produce a shareable HTML report of the last run.
ao serve	Start an MCP server so tools like Claude Code or Cursor can invoke AO programmatically.

Architecture Highlights

• Role library lives under ~/.ao/roles (or a custom AO_AGENTS_DIR). Each role is a markdown file containing a system prompt.
• Workflow engine reads the YAML, builds a DAG, resolves {{variables}} between steps, and runs each step via the selected LLM provider.
• Parallelism – AO automatically detects independent branches and runs them concurrently (configurable via concurrency).
• Acceptance & assertions – Steps can declare acceptance criteria or assert rules (file count, token size, regex matches). Failed assertions trigger a retry or a directed re‑work.
• Resumability – --resume and --from let you restart from a specific step using previously saved outputs, enabling cheap iteration.
• Extensible “skills” – Small reusable method‑ologies (e.g., test‑driven development, structured code review) can be attached to steps via the skill field.

Ecosystem & Extensions

• Multilingual role packs (agency-agents-ko, pt-br, ar, etc.) can be installed via npm and selected in Studio.
• Creative assets – AO bundles 1500+ image prompts and 76 video templates, usable directly from the UI.
• Docker / NAS deployment – Official image ghcr.io/jnmetacode/agency-orchestrator with a simple docker run command; volume‑mounted ao-data persists keys and outputs.
• Integrations – Built‑in MCP adapters for 14 AI coding assistants (Claude Code, Cursor, Copilot, etc.) so those tools can call AO workflows without writing glue code.

When It Makes Sense vs. Simpler Alternatives

Situation	Use AO	Use a single‑chat LLM
Need multiple expert viewpoints (product, tech, finance, marketing)	✅ AO builds a team and merges results	❌ You’d have to ask repeatedly and stitch manually
Want a repeatable, auditable pipeline with acceptance checks	✅ YAML + assert/acceptance	❌ No built‑in validation
Prefer a graphical drag‑and‑drop view	✅ Studio UI	❌ No GUI
Want to run locally without paying for API calls	✅ Use CLIs (Claude‑code, Copilot‑cli, Ollama) or free key‑less providers	❌ Most single‑chat services need a key

---

Bottom line: Agency Orchestrator is a genuine, production‑ready framework for orchestrating many AI agents to solve complex, multi‑disciplinary tasks, offering both a low‑code CLI and a full‑featured web studio. It is squarely in the AI‑agent / multi‑LLM orchestration space.