car-multi

Multi-agent coordination patterns for the Common Agent Runtime.

What it does

Provides coordination patterns for running multiple agents together: Swarm (parallel/sequential/debate), Pipeline (linear chain), Supervisor (review loop), Delegator (spawn specialists mid-run), SpawnSubtask (ephemeral tool-subset sub-agents), MapReduce (fan-out + reduce), Vote (majority wins), Fleet (independent missions), AdversarialReview (fresh-context verification), Tournament (pairwise ranking), and Advisor (bounded stronger-model guidance while the executor stays in control). Agents communicate via shared state, task enrichment, and async mailboxes.

All coordinations share a runtime-enforced CoordinationBudget (token/cost/agent caps; see budget.rs) and can run agents under per-agent state isolation (task_context) and filesystem workspace isolation (Swarm::with_workspaces, workspace.rs — an isolated directory or git worktree per parallel agent).

topology.rs bridges finished runs into car-topology execution records: execution_record folds a run's outputs into one record (returning None rather than a zero-cost record when the runner reported no token accounting), scorer_advice answers — off the AgentSpecs themselves, no encoder needed — whether the team is homogeneous enough that a profile-node message-passing scorer would score every candidate topology identically, and select_shape turns a fitted selector's answer back into a pattern this crate can execute. record_run is the one-call write path — fold a finished run and append it to a RecordJournal in a single call — and it reports false rather than writing when the runner metered nothing. record_run_from_outcomes derives BOTH measured numbers from the run itself — tokens from TokenAccounting, utility from the agents' AgentOutcomes — and writes nothing when either is missing, so the convenient path cannot fabricate a training label. UtilityEvidence::Grounded additionally refuses a success backed only by the agent's own say-so, mirroring the receipts rule the flagship assistant applies. Note that outcome is filled by the caller's AgentRunner: the aggregate outputs these patterns build themselves carry none, by construction.

Usage

use car_multi::{Swarm, SwarmMode, AgentSpec, AgentRunner, SharedInfra};

let agents = vec![
    AgentSpec::new("researcher", "You find information."),
    AgentSpec::new("writer", "You write summaries."),
];
let swarm = Swarm::new(agents, SwarmMode::Sequential);
let result = swarm.run("Summarize recent news", &runner, &infra).await?;

Part of CAR -- see the main repo for full documentation.