Multi-Agent Orchestrator

Fan out work across many items in parallel, run agents on each, and merge the results into a single ranked or grouped output. The orchestrator coordinates execution, aggregates scores, and deduplicates findings across batches.

What is the Orchestrator?

When you have hundreds of items to process — investors to score, leads to research, candidates to evaluate — running them one-by-one through a workflow is too slow. The orchestrator splits a list into batches, runs each batch in parallel (each batch gets its own agent or AI steps), and then combines all the results.

The combination step is not just concatenation. The orchestrator can rank by score, deduplicate across batches, group into tiers (top/mid/low), compute distributions, and hydrate final results with data from the Knowledge Graph.

How It Works

1. Fan-outThe orchestrator splits the input list into batches of configurable size. Each batch runs as a child execution with its own timeline and logs.

2. ProcessEach batch runs the same steps (AI steps, agent steps, app actions). Steps reference {{batch.items}} to access their slice of the input.

3. AggregateOnce all batches complete, the aggregation step merges results: deduplicates by identity field, ranks by score, groups into tiers, and computes summary metrics.

4. OutputThe workflow's final output is the aggregated result — a single ranked list, a tier breakdown, or a distribution report, ready for the next step or export.

Aggregation Config

Set batching.aggregationConfig on the batch step to control how results merge:

aggregationConfig: {
  enabled: true,
  itemPath: "scoring.rankedInvestors",  // dot-path to per-item results array
  deduplicationField: "investorId",      // deduplicate across batches by this field
  scoreField: "matchScore",              // numeric field to rank by
  qualifiedCutoff: "{{inputs.minScore}}", // template for dynamic threshold

  groupTiers: [
    { label: "top",  minScore: 80 },
    { label: "mid",  minScore: 60 },
    { label: "low",  minScore: 0  }
  ],

  aggregateByFields: ["geography", "sector"],  // compute distributions
  scoreHistogramBands: [
    { label: "80–100", min: 80, max: 100 },
    { label: "60–79",  min: 60, max: 79  },
    { label: "0–59",   min: 0,  max: 59  }
  ]
}

itemPath — dot-notation path inside each batch result where the array of scored items lives.

deduplicationField — if the same entity appears in multiple batches (e.g., a company in two CSV rows), this field picks the higher-scored copy.

groupTiers — instead of one ranked list, outputs separate arrays per tier (useful for routing top vs. mid to different workflows).

aggregateByFields — computes how results distribute across categorical fields (e.g., 42% US, 31% EU).

Business Metrics

After aggregation, the orchestrator computes KPIs across all batches. These are surfaced in the execution summary and stored to the Knowledge Graph:

Metric type	Example
sum / count	Total investors scored: 1,842
avg / min / max	Average match score: 67.4 \| Highest: 94
percent_above	18.3% scored above threshold
distribution	Sector breakdown: 34% fintech, 22% SaaS, 19% climate

Observability

Every batch creates its own child timeline, so you can drill into any individual batch to see exactly what each agent step did. The parent execution timeline shows the aggregate view:

•Batch status (pending / running / done / failed) per child execution
•Per-step timing and token usage rolled up across all batches
•Failed batches are flagged and can be retried individually without re-running the entire job
•Aggregate metrics and tier counts shown in the execution summary panel

Example: Investor Matching at Scale

A VC firm runs investor matching against 2,000+ investors. Here's how the orchestrator participates:

Input2,000 investor rows from the investors Knowledge List, filtered to status: active.

BatchesSplit into 20 batches of 100. Each batch runs a scoring agent that reads the ICP from Business Memory and scores each investor.

AggregateDeduplication removes 47 duplicate entries. Results ranked by score, split into top (82 investors) / mid (310) / low (1,561) tiers.

OutputTop-tier investors written back to the shortlist Knowledge List. Aggregate metrics stored to KG as an insight node.

Next Steps

Agents as Step — How individual agent steps work inside each batch
Batching — Batching configuration, concurrency, and retry policies
Scoring & Feedback — Feed aggregated outcomes back into the Knowledge Graph to improve future runs
Knowledge Lists — Load input rows and write tier results back