@cycgraph/orchestrator

Build and compose your own agent workflows with a unified engine for running custom workflows with helpful built-in patterns like supervisor, swarm, map-reduce, and reflection.

• Quick Start - build your first workflow in 5 minutes
• Core Concepts - graphs, nodes, agents, state
• Patterns - runnable guides for each built-in pattern
• Examples - runnable examples for each built-in pattern and infrastructure setup

Install

npm install @cycgraph/orchestrator

Quick start

import { agent, node, graph, run } from '@cycgraph/orchestrator';

const research = node({
  id: 'research',
  agent: agent({
    model: 'claude-sonnet-4-6',
    instructions: 'You are a research specialist. Produce concise, factual notes.',
  }),
  writes: 'notes',
});

const write = node({
  id: 'write',
  agent: agent({
    model: 'claude-sonnet-4-6',
    instructions: 'Turn the research notes into a clear summary under 300 words.',
  }),
  reads: [research.writes],
  writes: 'draft',
});

const workflow = graph({
  name: 'research-write',
  nodes: [research, write],
  edges: [{ from: research, to: write }],
});

const { draft } = await run(workflow, { goal: 'Explain how LLMs work' });

See the Quickstart guide for the full walkthrough.

Optional packages

• @cycgraph/memory - Temporal knowledge graph + xMemory-inspired hierarchical retrieval (messages → episodes → facts → themes).
• @cycgraph/context-engine - Optional prompt compression pipeline — strips redundant facts, verbose serialisation, and stale reasoning traces from memory payloads.
• @cycgraph/orchestrator-postgres - Postgres + pgvector adapter for durable state, event log, agent registry, and memory store.
• @cycgraph/tools - MCP and tools library.
• @cycgraph/evals - Regression-test harness for agent workflows with deterministic + LLM-as-judge assertions.

Studio

The studio is a dashboard over everything the engine records. Browse runs and their live log streams, inspect a workflow's topology, fork a recorded run to let the improve loop measure a workflow against its own evals, then walk the winning change from proposal to a committed branch.

See @cycgraph/studio for setup.

Built-in Patterns

Each pattern is a node type. Declarative, composable, and traced through OpenTelemetry.

• Supervisor An LLM decides which specialist worker should run next, iteratively
• Swarm Peer agents hand off work to each other based on competence
• Map-Reduce Fan out an array of items to parallel workers, then merge
• Evolution (DGM) Generate N candidates per generation, score fitness, breed the winners
• Self-Annealing Iteratively refine a single output, dropping temperature each pass
• Reflection Distill run output into atomic facts that future runs retrieve
• Human-in-the-Loop Pause for a human reviewer; resume hours later from the exact checkpoint
• Verifier LLM-judge / filtrex expression / JSONPath assertion
• Voting consensus across N voter agents
• Subgraph Compose whole graphs as reusable blocks with isolated state
• A2A Delegate a step to a remote Agent2Agent agent through the trusted registry

Examples

• Fork a run and ask what-if
• Proof the learning loop works (with charts)
• A research agent that learns over runs
• Multi-specialist routing
• Quality loop until score ≥ N
• Parallel research workers + merge
• Verify-and-fix with deterministic gates
• Voting / consensus across N agents
• Evolutionary candidate breeding
• Pause for human review + resume
• MCP tools (web search, fetch)
• Local Ollama models
• Postgres durable execution

Contributing

Issues and PRs welcome. See CONTRIBUTING.md for development setup, coding standards, and the architecture decisions worth knowing before opening a PR. Security disclosures go through SECURITY.md.

License

Apache 2.0.