Mixture of Agents

Mixture of Agents lets you combine several models into a single virtual model that is selectable anywhere a normal model is (chat model picker, specialized agents, channels, scheduled jobs). It is part of the ClapilotAICore native runtime.

Instead of asking one model, a MoA preset asks several reference models in parallel and then has one aggregator model synthesize the final answer and drive the normal agent loop (tool calls, follow-ups, retries).

Concepts

• Aggregator model — the acting model. It runs the normal Clapilot agent loop with full tool access. It sees the reference outputs as private context and produces the user-facing answer.
• Reference models — run first, in parallel, with no tools and a trimmed conversation (system prompts and tool transcripts stripped, only the last few user/assistant turns). Their answers are injected as advisory context for the aggregator.
• Virtual model ref — each preset is addressable as moa/<slug> and appears in the model catalog (listModels) like any other model.

A preset combining Opus 4.6 via the Claude CLI provider with GPT‑5.5 via the Codex bridge is a typical setup: Opus aggregates, while both Opus and GPT‑5.5 contribute reference perspectives.

How a turn runs

1. The session model resolves to moa/<slug>. resolveProviderSelection maps it to the preset's aggregator model and attaches the preset.
2. Reference models run in parallel (runConversation for HTTP/Claude‑CLI providers; a single-shot codex exec --ephemeral for Codex providers). Claude‑CLI reference calls run as stateless text-only completions with CLI tools disabled. Failures are non-fatal — a failed reference is simply omitted.
3. The reference outputs are formatted into one volatile system block appended after the cached stable prefix, so the aggregator's prompt cache is never broken.
4. The aggregator runs the normal agent loop with that block in context. Retries reuse the same reference context (references are not re-run).

Creating a preset

Settings → ClapilotAICore → Mixture of Agents:

• Name and identifier (slug) — the preset is selectable as moa/<slug>.
• Aggregator model — any non-MoA model from the catalog.
• Reference models — one or more non-MoA models.
• Advanced: max tokens per reference, history turns used for references, reference timeout (ms), an optional synthesis instruction appended to the aggregator context, and whether to expose reference outputs.

Once enabled, the preset appears in the chat model picker and specialized-agent model selectors as a normal model.

Constraints and notes

• No recursion: an aggregator or reference may not itself be a MoA preset (enforced on save and defensively at load).
• Cost / latency: every turn calls N+1 models. References run in parallel, so added latency is roughly the slowest reference; cost is the sum.
• Public/external contexts: subscription-bridge references (Claude CLI, Codex) are skipped where subscription bridges are disallowed.

Data model

Presets are stored in agent_moa_presets (migration 176_agent_moa_presets.sql):

No credentials are stored here — refs point at existing agent_provider_configs models.

Endpoints

• Web (admin): GET/POST /api/agent-runtime/moa-presets, DELETE /api/agent-runtime/moa-presets?slug=<slug>.
• Native runtime: GET/POST/DELETE /internal/moa-presets.

See API Reference for request/response shapes.