Parliagent

Multi-agent deliberation engine. One call gets you a structured debate among expert personas — with disagreement tracking, minority reports, and budget controls.

Designed as a skill: invoke it from an agent workflow, import it as a library, or run it from the CLI.

Installation

npm install parliagent

Requires Node >= 18 and at least one LLM provider API key.

When to Use Parliagent

Use it when you need multiple perspectives before deciding — architecture choices, risk reviews, planning under uncertainty, security-sensitive designs.

Don't use it for simple factual questions, pure writing tasks, or anything where a single expert answer is sufficient. Micro mode on a writing prompt reaches consensus in one round with zero disagreements — the debate adds nothing.

Quick Start

SDK

import { debate } from "parliagent";

const response = await debate({
  prompt: "Should we use microservices or a monolith?",
  mode: "fast",
  taskType: "strategy",
});

// Use the result
console.log(response.finalAnswer);
console.log(response.decisionType);    // "consensus" | "majority" | "split" | "uncertain"
console.log(response.minorityReport);  // dissenting views, if any
console.log(response.warnings);        // safety/security concerns raised during debate

CLI

# Quick question — micro mode, 2-3 seats, 1 round
parliagent ask "What's the best approach to rate limiting?"

# Planning — fast mode, structured steps
parliagent plan "Migration plan from monolith to microservices"

# Critical review — find problems and risks
parliagent review "Our proposed auth schema" --mode balanced

# Full debate with trace
parliagent debate "Should we pivot?" --mode fast --trace full --json

# See what seats would be selected without running a debate
parliagent inspect "How to handle API key rotation?" --mode fast

Defaults and Mode Selection

These defaults are backed by benchmark data (10 prompts × 3 modes: micro/fast/balanced, Anthropic Claude, 2026-04-02). Deep mode was not benchmarked.

| Command | Default Mode | Cost | Latency | Why This Default | |---------|-------------|------|---------|------------------| | ask | micro | 1.6x baseline | 16s | Best value. 3+ disagreements on average at minimal cost overhead. | | plan | fast | 6.5x baseline | 34s | Planning needs deeper conflict surfacing. 10+ disagreements on average. | | review | fast | 6.5x baseline | 34s | Reviews benefit from more critical perspectives. | | debate | balanced | 13.3x baseline | 37s | Explicit full deliberation. 5 seats, 18+ disagreements, 70% minority reports. |

Security auto-upgrade: Prompts containing security/auth/credential keywords auto-upgrade from micro to fast. This ensures SecurityPrivacySeat is included — it can't fit in micro's 2-seat chamber.

When to override:

• Use --mode fast on ask when the question has real tradeoffs
• Use --mode micro on review when you want a quick sanity check, not a deep critique
• Avoid balanced unless you specifically want 5+ perspectives — it costs 13x baseline with diminishing returns vs fast
• deep mode is implemented but not yet benchmarked. Budget limits (60k tokens / 60s) are enforced. Use at your own cost discretion.

Provider Support

| Provider | Status | Key Variable | |----------|--------|-------------| | Anthropic | Live-validated + benchmarked | ANTHROPIC_API_KEY | | OpenAI | Live-validated | OPENAI_API_KEY | | Google/Gemini | Live-validated | GOOGLE_API_KEY or GEMINI_API_KEY | | FLOCK | Live-validated (OpenAI-compatible) | FLOCK_API_KEY + FLOCK_MODEL |

All four providers are live-validated individually and in federated combinations (multiple keys). Set at least one key.

FLOCK uses the OpenAI-compatible API format with x-litellm-api-key header auth. Model must be specified explicitly:

FLOCK_API_KEY=sk-...
FLOCK_MODEL=your-model-name               # required — no default
FLOCK_BASE_URL=https://api.flock.io/v1    # default, can be overridden

To force a specific primary provider:

PARLIAGENT_PRIMARY_PROVIDER=openai

Output Language

Internal debate is always in English for reasoning quality. Output language is configurable — the final synthesis step renders the result in the requested language.

# CLI
parliagent ask "What is the best database for this use case?" --language zh

# SDK
debate({ prompt, outputLanguage: "zh" })

Supported: any BCP-47 language code (en, zh, zh-CN, ja, es, fr, ko, etc.). English output (en) is the default — no translation step is added.

What gets translated: finalAnswer, warnings, minorityReport, openQuestions, debateSummary, transcript output.

What stays English: Internal seat statements, disagreement records, trace artifacts. These are reasoning internals, not user-facing output.

Evidence Bundle

Pass shared evidence to seats for grounded deliberation:

debate({
  prompt: "Should we migrate to PostgreSQL?",
  evidenceBundle: [
    { source: "benchmark-2024.csv", content: "PostgreSQL: 12k TPS, MySQL: 9k TPS", type: "data" },
    { source: "ops-report.md", content: "Current MySQL cluster has 3 known replication issues", type: "document" },
  ],
})

When evidence is provided, seats can classify claims as supported (backed by evidence) vs speculative. The evidence is injected as shared context — all seats see the same bundle. Evidence types: document, data, code, citation, observation.

Execution Profiles

Mode controls how many seats debate. Profile controls which models they use. These are independent knobs.

| Profile | Behavior | When to Use | |---------|----------|-------------| | federated | Each seat uses its preferred provider's best model (OpenAISeat→gpt-5.4, ClaudeSeat→claude-opus-4-6, GeminiSeat→gemini-3.1-pro-preview, others→primary) | Default. Best model per seat, maximum quality. | | available | Seats walk their fallback chain: preferred → primary → any | When you want fallback flexibility | | supreme | All seats on one operator-designated provider | When you want uniform single-provider behavior |

# CLI
parliagent ask "question" --profile supreme

# SDK
debate({ prompt, mode: "fast", executionProfile: "supreme" })

With only one API key, all three profiles produce the same assignments — every seat deterministically falls back to that provider.

Configuration

Environment Variables

ANTHROPIC_API_KEY=sk-ant-...                        # Provider keys (at least one required)
OPENAI_API_KEY=sk-...
FLOCK_API_KEY=sk-...                                 # FLOCK provider key
FLOCK_MODEL=your-model-name                          # FLOCK model (required, no default)
FLOCK_BASE_URL=https://api.flock.io/v1               # FLOCK base URL (default shown)
PARLIAGENT_PRIMARY_PROVIDER=anthropic            # Force primary provider
PARLIAGENT_SUPREME_PROVIDER=flock                # Override supreme model selection
PARLIAGENT_EXECUTION_PROFILE=federated          # Default profile
PARLIAGENT_DEFAULT_MODE=fast                     # Override default mode
PARLIAGENT_DEFAULT_TRACE=summary                 # none | summary | full
PARLIAGENT_DEFAULT_OUTPUT_LANGUAGE=en             # Output language (e.g. zh, ja, es)
PARLIAGENT_MAX_TOKENS=15000                      # Global token budget cap
PARLIAGENT_MAX_LATENCY_MS=20000                  # Global latency cap
PARLIAGENT_MAX_CONCURRENT_SEATS=6               # Global seat concurrency cap per round
PARLIAGENT_MAX_CONCURRENT_OPENAI=4              # Optional per-provider concurrency cap
PARLIAGENT_MAX_CONCURRENT_ANTHROPIC=4
PARLIAGENT_MAX_CONCURRENT_GOOGLE=4
PARLIAGENT_MAX_CONCURRENT_FLOCK=4

Config File

Optional parliagent.config.json in your working directory:

{
  "primaryProvider": "anthropic",
  "supremeProvider": "anthropic",
  "defaults": { "mode": "fast", "executionProfile": "federated", "trace": "summary", "outputLanguage": "en" },
  "budgetOverrides": { "maxTokens": 15000, "maxLatencyMs": 20000, "maxConcurrentSeats": 6 },
  "providerConcurrency": { "anthropic": 4, "openai": 4, "google": 4, "flock": 4 }
}

Environment variables take priority over file config.

Response Structure

Every call returns a ParliagentResponse:

| Field | Type | Always Present | Description | |-------|------|---------------|-------------| | finalAnswer | string | Yes | The synthesized answer | | decisionType | "consensus" | "majority" | "split" | "uncertain" | Yes | How the parliament resolved | | activatedSeats | string[] | Yes | Which seats participated | | whyTheseSeats | string | Yes | Routing rationale | | minorityReport | string | No | Dissenting views (absent on consensus) | | openQuestions | string[] | No | Unresolved disagreements | | warnings | string[] | No | Safety/security concerns raised | | debateSummary | string | When trace != "none" | Per-round summary | | traceArtifact | object | When trace == "full" | Full deliberation trace with rounds, statements, disagreements, and structured-output reliability metrics (parseRecoveryCount, degradedParseCount) |

Answer Modes

Control the synthesis format with answerMode:

| Mode | Output Shape | Best For | |------|-------------|----------| | answer | Direct response (default) | General questions | | memo | Situation / Options / Analysis / Recommendation | Decision memos | | plan | Goal / Steps / Dependencies / Risks | Implementation planning | | review | Verdict / Strengths / Issues / Risks / Recommendations | Code and design review | | transcript | Formatted debate with per-seat contributions | Understanding the deliberation |

Serverless Deployment

import { handleRequest } from "parliagent";

export default async function handler(req) {
  return handleRequest({ method: req.method, body: await req.json() });
}

POST a ParliagentRequest JSON body, get back a ParliagentResponse. Includes CORS headers, input validation, and structured error responses.

Full Parliagent (33 seats)

All 33 seats are production-grade and invokable. Default modes select a subset; full parliagent is explicit opt-in.

| Category | Seats | |----------|-------| | Procedural | Speaker | | Model Representatives | OpenAISeat, ClaudeSeat, GeminiSeat | | Computing Foundations | TuringSeat, KnuthSeat, DijkstraSeat, ShannonSeat | | Modern Computing | DistributedSystemsSeat, MLSystemsSeat, HumanComputerInteractionSeat, SecurityPrivacySeat | | Philosophy | AristotleSeat, KantSeat, NietzscheSeat | | Mathematics | EuclidSeat, GaussSeat, VonNeumannSeat | | Physics | NewtonSeat, EinsteinSeat, FeynmanSeat | | Economics & Strategy | SmithSeat, KeynesSeat, StrategySeat | | Psychology & Cognition | KahnemanSeat, JungSeat, CognitiveScienceSeat | | Product & Operations | ProductStrategySeat, OperatorSeat, DesignCommunicationSeat | | Civic & Ethics | LawGovernanceSeat, EthicsHumanImpactSeat, CitizenPragmatistSeat |

Full Parliagent Mode

Activate all 33 seats for maximum deliberation breadth:

parliagent debate "question" --full-parliagent

debate({ prompt, fullParliagent: true, trace: "full" })

| Metric | Full Parliagent (measured) | |--------|--------------------------| | Seats | 32 (+ Speaker) | | Rounds | 1 (default) | | Avg tokens | ~247,000 | | Avg latency | ~44s | | Avg disagreements | 133 | | Estimated cost | ~$1.50/run | | Budget cap | 300k tokens / 120s |

Full parliagent runs 1 round by default — 32 voices in a single round already produce 100+ disagreements. Budget limits apply between rounds; a single parallel round may use the full cap. Use PARLIAGENT_MAX_CONCURRENT_SEATS and optional per-provider concurrency caps to reduce rate-limit spikes in high-seat runs.

When to use: Consequential decisions where you want every disciplinary angle — architecture with compliance implications, strategic pivots, security-critical designs.

When not to use: Everyday questions. The cost is ~300x baseline. Default modes (micro/fast/balanced) are better for routine work.

CLI Reference

parliagent ask <prompt>       Quick deliberation (micro)
parliagent debate <prompt>    Full debate with trace (balanced)
parliagent plan <prompt>      Planning-biased (fast)
parliagent review <prompt>    Critical review (fast)
parliagent seats              List available seats
parliagent inspect <prompt>   Show routing without running debate

Options:
  --mode <mode>           micro | fast | balanced | deep
  --full-parliagent       Activate all 33 seats (high cost, explicit opt-in)
  --profile <profile>     available | federated | supreme
  --language <code>       Output language (e.g. zh, ja, es). Internal debate stays English.
  --task <type>           general | writing | planning | analysis | coding | strategy | ethics
  --answer <mode>         answer | memo | plan | review | transcript
  --trace <level>         none | summary | full
  --seat <seats...>       Include specific seats
  --exclude-seat <seats>  Exclude specific seats
  --json                  Machine-readable JSON output
  --short / --long        Control output length
  --seed <value>          Reproducibility seed
  --max-tokens <n>        Override token budget
  --max-latency-ms <n>    Override latency budget

License

MIT