Multi Agent Topologies

Multi-Agent Topologies

CW v0.1.19 adds official topology recipes on top of the Multi-Agent Runtime Core and Coordinator / Blackboard. v0.1.53 opens the topology system: custom topologies can be registered at runtime via registerTopology().

Topologies are userland recipes, not hidden automation. Applying a topology materializes ordinary CW records:

• MultiAgentRun
• agent roles
• groups
• fanouts
• optional fanins
• blackboard topics
• blackboard messages
• coordinator decisions
• trust audit events
• graph nodes
• deterministic next actions

Durable topology run records live in:

.cw/runs/<run-id>/topologies/index.json
.cw/runs/<run-id>/topologies/runs/<topology-run-id>.json

Official Topologies

map-reduce

Fans out mapper roles, indexes mapper evidence on the blackboard, then reduces only after required fanin evidence is present.

Use for:

• independent shard work
• parallel repo analysis
• evidence collection before synthesis

debate

Records opposing claims, rebuttal rounds, conflict context, coordinator decisions, and final synthesis.

Use for:

• adversarial review
• disputed architectural decisions
• comparing plausible options with evidence

judge-panel

Collects independent judge outputs, aggregates score evidence, and records a panel decision with provenance.

Use for:

• candidate selection
• multi-reviewer scoring
• panel-style acceptance decisions

Custom Topologies (v0.1.53)

Any module can register a custom topology at runtime. Topology ids are now open strings — no longer a closed union type.

import { registerTopology } from "./topology";

registerTopology({
  schemaVersion: 1,
  id: "swarm",
  title: "Swarm",
  summary: "Parallel swarm agents with consensus voting.",
  roles: [
    { id: "swarm-agent", title: "Swarm Agent",
      responsibilities: ["Produce shard result with evidence."],
      requiredEvidence: ["swarm output artifact"],
      expectedArtifacts: ["swarm result"],
      faninObligations: ["indexed swarm artifact"],
      count: 5 }
  ],
  groups: [{ id: "swarm", title: "Swarm Group", roleIds: ["swarm-agent"] }],
  blackboardTopics: [
    { id: "swarm-outputs", title: "Swarm Outputs", description: "Agent results." }
  ],
  phases: [
    { id: "execute", title: "Execute", roleIds: ["swarm-agent"],
      fanout: true, fanin: false,
      requiredEvidence: ["swarm output artifact"],
      coordinatorDecisionKinds: ["artifact-index"] },
    { id: "consensus", title: "Consensus", roleIds: ["synthesizer"],
      fanout: false, fanin: true,
      requiredEvidence: ["all swarm evidence"],
      coordinatorDecisionKinds: ["candidate-synthesis"] }
  ],
  fanoutStrategy: "one membership per swarm agent role",
  faninStrategy: "consensus requires all swarm agent evidence",
  requiredEvidence: ["swarm output artifact", "consensus synthesis"],
  coordinatorDecisions: ["artifact-index", "candidate-synthesis"],
  candidateExpectations: ["Synthesis cites swarm agent provenance."],
  verifierGates: ["Swarm fanin must be ready before commit."]
});

Custom topologies auto-appear in topology list, topology validate, and topology apply. Role expansion is data-driven: role.count controls how many instances are materialized. Backward compat with the official topologies is preserved — mapperCount and judgeCount input overrides still work.

When a topology needs repeated rounds (like debate rebuttals), you can drive it with a bounded dynamic loop phase: loop(name, tasks, {maxRounds, until}) re-runs a per-round task template and a named pure predicate decides each round. Rounds are hard-capped by maxRounds (fail closed) and each round writes a deterministic loop-control node.

CLI

node scripts/cw.js topology list
node scripts/cw.js topology show map-reduce
node scripts/cw.js topology show debate
node scripts/cw.js topology show judge-panel
node scripts/cw.js topology validate map-reduce
node scripts/cw.js topology apply <run-id> map-reduce --task <task-id> --mappers 2
node scripts/cw.js topology apply <run-id> debate --id debate-round --rounds 2
node scripts/cw.js topology apply <run-id> judge-panel --judges 3
node scripts/cw.js topology apply <run-id> swarm --task <task-id>   # custom topology
node scripts/cw.js topology summary <run-id>
node scripts/cw.js topology graph <run-id>

MCP

MCP parity tools:

• cw_topology_list
• cw_topology_show
• cw_topology_validate
• cw_topology_apply
• cw_topology_summary
• cw_topology_graph

Fail Closed

Topology fanin uses the existing AgentFanin checks. Missing memberships, missing result evidence, and missing indexed blackboard evidence remain blocked. A topology may recommend the next command, but it does not mark missing evidence as complete.

Operator UX

status, graph, and report --show include topology progress:

• topology id and topology run id
• generated multi-agent run and blackboard id
• roles, topics, fanouts, and fanins
• readiness and missing evidence
• conflicts
• deterministic next action

Trust audit summaries include topology event counts.

See Also

• Capability and Topology Registry
• Home
• Runtime Contract
• Repo doc: docs/multi-agent-topologies.7.md
• Repo doc: docs/capability-topology-registry.7.md