agent-orchestrator

English | 简体中文

agent-orchestrator is a TypeScript orchestration server for multi-model engineering workflows. It is designed for leader-worker execution, deterministic validation, and thin delivery layers through a CLI and MCP server.

What this is

• A TypeScript/Node.js monorepo for orchestrating leader and worker agents
• A CLI callable by humans or other coding agents through shell commands
• An MCP server exposing orchestration capabilities as structured tools
• A safe workflow engine that defaults to dry-run behavior

What this is not

• Not a Codex, OpenCode, Cursor, or Claude Code clone
• Not an interactive coding terminal or TUI
• Not a full chat interface
• Not a web UI product

Architecture diagram

Human / Coding Agent / CI / MCP Client
                |
                v
           ao CLI / MCP
                |
                v
         LangGraph Workflows
                |
      +---------+---------+
      |                   |
      v                   v
 Leader Agent      Deterministic Tools
      |
      v
 Worker Agents

Monorepo layout

packages/
  core/
  models/
  graph/
  tools/
  mcp-server/
  cli/
apps/
  playground/
examples/
  leader-worker-basic/
docs/

Setup

pnpm install
pnpm typecheck
pnpm test

CLI usage

ao plan --goal "Generate TipTap nodes from S1000D proced.xsd"
ao run leader-worker-basic --goal "Generate tests for schema parser"
ao review --diff main...HEAD
ao fix --error ./tmp/tsc-error.log --scope packages/schema-codegen
ao models list
ao mcp serve
ao mcp list-tools

Worker onboarding

Workers are not treated as automatically qualified just because a model endpoint exists.

Use onboarding evaluation before assigning real work:

ao worker interview --provider litellm --model qwen3-coder
ao worker interview --provider litellm --model qwen3-coder --save
ao worker list
ao worker profile litellm:qwen3-coder

The interview workflow evaluates:

• instruction following
• structured JSON output
• summarization
• code understanding
• simple TypeScript code generation
• confidence calibration

Interview results produce a WorkerCapabilityProfile that affects routing:

• active: worker can receive the task types it qualified for
• limited: worker is restricted to low-risk tasks and requires leader review
• blocked: worker is excluded from production workflows and emits warnings

Example warning output:

Worker litellm:qwen3-coder failed onboarding evaluation.

Status: limited

Reasons:
- structured-output: Output failed schema validation.
- codegen: Generated code uses any.
- confidence-calibration: Worker reported high confidence on an ambiguous task.

Recommended action:
- Do not assign codegen tasks.
- Limit this worker to qualified low-risk tasks.
- Require leader review for every accepted output.

If the worker is significantly worse, the profile becomes blocked and production routing should treat it as unavailable.

Persisting worker profiles

Use --save if you want to persist the interview result:

ao worker interview --provider litellm --model qwen3-coder --save

Saved profiles are written to:

.ao/worker-profiles.json

You can inspect persisted profiles with:

ao worker list
ao worker profile litellm:qwen3-coder

Current behavior is conservative: if a workflow is started without an explicit profile object, the system can re-run the interview instead of blindly trusting an old capability record.

MCP server usage

Start the stdio server:

ao mcp serve

List exposed tool names:

ao mcp list-tools

Environment variables

See .env.example.

• LEADER_MODEL_PROVIDER
• LEADER_MODEL_NAME
• LEADER_MODEL_BASE_URL
• LEADER_MODEL_API_KEY
• WORKER_MODEL_PROVIDER
• WORKER_MODEL_NAME
• WORKER_MODEL_BASE_URL
• WORKER_MODEL_API_KEY
• LITELLM_BASE_URL
• LITELLM_API_KEY
• MCP_SERVER_NAME
• MCP_SERVER_VERSION
• LOG_LEVEL
• AO_DRY_RUN
• AO_ALLOW_WRITE
• AO_ALLOWED_COMMANDS

Workflows

• planning-workflow: builds a plan, worker assignment proposal, risk list, and validation strategy
• leader-worker-workflow: coordinates leader planning, worker execution, tool validation, and final review
• review-workflow: summarizes diff impact, risks, missing tests, and follow-up items
• fix-error-workflow: analyzes error logs and proposes safe validation-oriented fix steps
• worker-interview-workflow: evaluates a worker model before production routing and generates a capability profile

How to run the basic example

pnpm example:leader-worker-basic

How to add a new worker

1. Add a worker class under packages/graph/src/workers.
2. Give it a clear WorkerCapability with Zod-backed schemas.
3. Declare the worker's supported task types so routing can enforce capability limits.
4. Route it from a workflow and keep its output reviewable.
5. Make sure onboarding interview results can constrain how it is assigned.
6. Add tests for the workflow path it affects.

How to add a new workflow

1. Create a workflow file under packages/graph/src/workflows.
2. Use LangGraph.js to model transitions explicitly.
3. Reuse core contracts and leader review patterns.
4. Expose it through the CLI or MCP only after tests exist.

How to add a new MCP tool

1. Add a tool definition in packages/mcp-server/src/tools.
2. Keep the handler thin and delegate to core workflow APIs.
3. Register it in packages/mcp-server/src/server.ts.
4. Add a registration test.

How to configure LiteLLM

Set LEADER_MODEL_PROVIDER=litellm or WORKER_MODEL_PROVIDER=litellm, then provide:

• LITELLM_BASE_URL
• LITELLM_API_KEY

If you want different endpoints for leader and worker traffic, use the model-specific base URL variables instead.

Safety model

• Default mode is dry-run.
• File writes require explicit policy allowance.
• Shell execution is allowlisted.
• Worker outputs are not final until leader review completes.
• Workers must pass onboarding evaluation before they should receive production tasks.
• Workers that fail structured output or reliability checks are limited or blocked.
• Secrets are expected from environment variables and should never be logged.

Roadmap

• Expand workflow coverage and richer deterministic validations
• Add domain-specific orchestration packages later
• Add CI automation for checks and releases
• Keep the core focused on orchestration rather than UI