@backendkit-labs/orchestrator-agent

Config-driven multi-agent orchestration for enterprise workflows. Decomposes natural language tasks into sub-tasks, coordinates specialist agents via a shared knowledge vault, and enforces human approval gates — with full audit trail.

What it does

• Plans: decomposes a task into a dependency-ordered plan (static flow or LLM-generated)
• Executes: runs steps in parallel when dependencies allow, each delegated to a specialist agent
• Gates: pauses for human approval at critical steps, either by config or by active policy rules
• Persists: every run is saved to disk (or Redis) — survives restarts, resumes after gate approval
• Learns: enterprise reflection monitors gate outcomes and promotes recurring failure patterns into deterministic policy rules
• Remembers: completed runs are auto-distilled into the knowledge vault; specialist agents receive episodic context from past successful runs on similar tasks

Installation

npm install -g @backendkit-labs/orchestrator-agent
# or as a local dep in a monorepo
npm install @backendkit-labs/orchestrator-agent

Quick start (5 minutes)

1. Create orchestrator.yaml

version: 1

orchestrator:
  name: "My Orchestrator"
  provider: deepseek

providers:
  deepseek:
    api_key: ${DEEPSEEK_API_KEY}
    base_url: https://api.deepseek.com/v1
    model: deepseek-chat

agents:
  - id: analyst
    name: Data Analyst
    description: Analyzes data and produces reports
    capabilities: [analysis, reporting, metrics]
    provider: deepseek

  - id: writer
    name: Technical Writer
    description: Writes documents and summaries
    capabilities: [writing, documentation, summaries]
    provider: deepseek

2. Create .env

DEEPSEEK_API_KEY=sk-...

3. Wire into Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "orchestrator": {
      "command": "npx",
      "args": ["-y", "@backendkit-labs/orchestrator-agent"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-..."
      }
    }
  }
}

4. Run a task (in Claude Desktop):

orchestrator_run
  config_path: /path/to/orchestrator.yaml
  task: "Analyze Q1 sales data and write an executive summary"

Feature overview

| Feature | Description | |---------|-------------| | Dynamic planning | LLM decomposes any task into a dependency-ordered plan | | Static flows | Pre-defined YAML workflows triggered by regex or flow_id | | Parallel execution | Independent steps run concurrently (Promise.all) | | Human gates | Steps pause for approval — configurable per-agent or per-step | | Policy rules (Cable 2) | Active rules automatically gate matching steps — no LLM involved | | LanceDB RAG | Incremental vault indexing with ANN search, fast at scale | | Redis + BullMQ | Distributed execution across worker processes for production | | HTTP trigger | REST endpoint for n8n / external system integration | | Enterprise reflection | MAPE-K: monitors outcomes → promotes patterns → enforces rules | | Run consolidation | Completed runs auto-distilled by LLM into vault — episodic→semantic loop | | Cross-run episodic memory | Agents receive past successful outputs for similar tasks as context | | Forgetting curve | Episodic memory prunes by relevance (recency × recall frequency), not just age |

MCP Tools

| Tool | Description | |------|-------------| | orchestrator_run | Start a task — returns runId immediately | | orchestrator_status | Poll status by runId | | orchestrator_approve | Approve or reject a waiting gate | | orchestrator_list_runs | List all persisted runs | | orchestrator_list_agents | Show configured agents | | orchestrator_reflect | View pending promotions, active rules, demotion candidates | | orchestrator_reflect_promote | Approve or reject a pattern promotion to policy rule | | orchestrator_reflect_demote | Demote a policy rule with audit trail |

Documentation

• Configuration reference — full orchestrator.yaml schema
• MCP tools — parameters, examples, and responses for all 8 tools
• Static flows — YAML flow format, payload interpolation, auto-detection
• Gates and policies — human approval, Cable 2 automatic gates
• HTTP trigger — REST API for n8n and external systems
• Redis + workers — distributed execution with BullMQ
• RAG vault — LanceDB indexing, run consolidation, cross-run episodic injection
• Enterprise reflection — MAPE-K loop, promotions, demotions
• Memory system — full architecture: episodic, semantic, procedural, forgetting curve

Data directory

By default, run state and RAG index live in .orchestrator/ adjacent to your orchestrator.yaml:

.orchestrator/
  runs/           ← JSON run files (one per run)
  rag-lance/      ← LanceDB vector index

Override with ORCHESTRATOR_DATA_DIR env var or data_dir in the YAML.

License

MIT