---
name: moa
description: Mixture of Agents workflow for pi. Use /moa <prompt> to run 1–3 high-intelligence reference models in parallel (single-turn context, no tools) and synthesize their labeled output through the main model with full conversation history. Use when the user wants multiple expert perspectives, a second opinion on a hard problem, debate-style coverage, or higher-quality answers on ambiguous/controversial questions.
---

# MOA (Mixture of Agents)

MOA improves answer quality by consulting multiple high-intelligence
**reference models** in parallel, then letting the **main model** (aggregator)
synthesize their labeled opinions while keeping full conversation context and
normal tool access.

## How it works

1. `/moa <prompt>` fans out to the configured reference models (1–3; the wizard
   defaults to 2).
2. Each reference model sees **only a single-turn context** — no system prompt,
   no tools. In a multi-turn session, that context is the user's current prompt
   plus a short (100–200 word) summary of the conversation that the main model
   generates first, instead of raw history.
3. Reference outputs are injected into the main model's input under labeled
   headings (`## 参考模型 N：provider/model`).
4. The main model answers with full history + reference opinions, and can call
   tools normally. By default this is the **current UI-selected model**.
5. Only when a fixed `aggregator` is configured does MOA switch models; in that
   case the previously-selected model is restored once the turn settles.

## Commands

| Command | Purpose |
|---|---|
| `/moa <prompt>` | Run MOA once with the default preset |
| `/moa` | Usage + config summary (runs first-run wizard if unconfigured) |
| `/moa list` | List all presets |
| `/moa configure [name]` | Interactive create/edit of a preset |
| `/moa delete <name>` | Delete a preset (with confirmation) |
| `/moa status` | Show current config and model |
| `/moa set-main <provider>/<model>` | Pin a fixed main model (default: follow the UI model) |
| `/moa-auto` | Toggle auto mode (every message runs MOA; status shown in the bar) |

## When to use /moa

- The user asks for multiple perspectives, pros/cons, a debate, or "what would
  different experts say".
- A hard or ambiguous problem where a second opinion materially helps.
- High-stakes decisions, design trade-offs, or contentious questions.
- As a quality boost on a single important prompt (one-shot; costs 2 reference
  calls).

Do **not** use `/moa` for trivial questions or repeated back-and-forth: reference
models run on every `/moa` invocation, so it costs extra tokens and latency each
time.

## Configuration

- Config lives at `~/.pi/agent/moa.json` (global). It stores only
  `provider/model` identifiers — **never** API keys.
- First use: run `/moa` (interactive TUI) to pick reference models from models
  that already have configured auth. The main model follows your current UI
  model by default; you can optionally pin a fixed `aggregator`.
- Reference models (and any fixed aggregator) must already have auth configured
  in pi (`/login <provider>` or env var). Run `/moa status` to inspect.

Example config schema:

```json
{
  "default_preset": "default",
  "presets": {
    "default": {
      "reference_models": [
        { "provider": "anthropic", "model": "claude-sonnet-4-5" },
        { "provider": "openrouter", "model": "deepseek/deepseek-v3.1" }
      ],
      "aggregator": { "provider": "anthropic", "model": "claude-opus-4-5" },
      "reference_max_tokens": 4000
    }
  }
}
```

The `aggregator` field is optional — omit it to use the current UI model as the
main output model.

## Notes / limitations

- `/moa-auto` turns on persistent auto mode: every interactive message runs the
  MOA pipeline. It intercepts input via pi's `input` event and does not affect
  slash commands or `/moa`'s internal sends.
- The main model is the current UI model by default; a fixed `aggregator` is
  optional.
- Reference models do not see raw history or tools. In multi-turn sessions they
  receive a main-model-generated summary of the conversation plus the current
  prompt.
- If all reference models fail, `/moa` aborts before running the main model.
- A single reference failure is reported inline and the flow continues.
- Headless/print mode cannot run the wizard; configure interactively first.