Multi-agent AI collaboration framework. Assembles a team of specialized AI agents who debate, disagree, and converge on solutions — like a real cross-functional meeting, not an assembly line.
- Debate-driven — Agents challenge each other. Disagreement is a feature, not a bug.
- Auto-assembly — Describe your objective; the orchestrator picks the right 4-6 specialists.
- 40+ personas — Distinct voices with speaking styles, loaded from markdown files.
- Tool approval system — High-risk tools (terminal, shell) require user approval. Low-risk auto-allowed.
- Live cost tracking — Per-model pricing, real-time cost display in the UI.
- Quality evaluation — Every workflow scored on diversity, novelty, convergence, constructiveness.
- A2A protocol — Google A2A-compatible for multi-agent interop.
# One-command setup (interactive)
npm run init
# Or manually:
git clone --depth 1 https://github.com/msitarzewski/agency-agents.git agents-repo
cp .env.example .env # add your API key
npm install
# Start
npm run dev # server on :3000
cd web && npm install && npm run dev # UI on :5173Type these in the chat to steer the discussion:
| Command | Effect |
|---|---|
/focus <topic> |
Redirect discussion to a specific topic |
/challenge <agent> |
Force an agent to defend their position |
/extend <N> |
Add N extra discussion rounds |
/stop |
Force immediate synthesis |
/reset |
Start the discussion fresh |
/help |
Show available commands |
| Variable | Default | Description |
|---|---|---|
DEFAULT_LLM_PROVIDER |
openai |
openai, anthropic, or copilot |
DEFAULT_MODEL_NAME |
gpt-4o |
Model name |
OPENAI_API_KEY |
— | OpenAI key |
ANTHROPIC_API_KEY |
— | Anthropic key |
CONCLAVE_API_KEY |
— | Server auth key (required in production) |
CONCLAVE_PROFILE |
— | fast, thorough, or cheap |
CONCLAVE_CUSTOM_AGENTS_DIR |
custom-agents |
Custom persona directory |
CONCLAVE_OTEL_ENDPOINT |
— | OpenTelemetry collector URL |
A2A_ALLOWED_TOOLS |
— | Comma-separated tool allowlist for A2A tasks |
WORKFLOW_TOKEN_BUDGET |
500000 |
Token limit per workflow |
See .env.example for all options.
Agent memories persist automatically via an embedded Postgres instance — no external database needed. Memories survive restarts and are searchable via hybrid keyword + vector search.
Data is stored in .workspace/knowledge-db/. Embedded Postgres starts on first use (port 5433).
Features:
- Hybrid search: keyword (tsvector) + vector (local Transformers.js embeddings) with RRF fusion
- Time-decay on unretrieved memories (old noise fades automatically)
- Per-agent + per-workflow scoping
- HNSW ANN index for fast vector similarity search
- Zero API keys — embedding model runs locally in-process
Conclave can run as a Discord bot — agents participate in Discord threads.
npm install discord.jsSet in .env:
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_GUILD_ID=your-server-id
DISCORD_CHANNEL_ID=channel-to-listen-in
DISCORD_WEBHOOK_URL=webhook-for-agent-messages
Create a bot at discord.com/developers with MESSAGE CONTENT intent enabled.
Create markdown files in custom-agents/ with YAML frontmatter:
---
name: "HIPAA Compliance Officer"
emoji: "🏥"
description: "Reviews designs for healthcare compliance"
capabilities: "validate"
---
Your system prompt here...Custom personas override built-in ones on role name conflict.
# JSON
curl http://localhost:3000/api/sessions/{id}/export
# Markdown
curl http://localhost:3000/api/sessions/{id}/export?format=markdown
# Full (includes all events)
curl http://localhost:3000/api/sessions/{id}/export?format=fullcurl http://localhost:3000/.well-known/agent.json
curl -X POST http://localhost:3000/a2a \
-H "Authorization: Bearer $CONCLAVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"1","method":"tasks/send","params":{"message":{"role":"user","parts":[{"type":"text","text":"Design a REST API"}]}}}'A2A tasks run with unattended trust — high-risk tools (terminal, shell) are automatically denied.
See docs/architecture.md for the full data flow diagram and component breakdown.
Key extractions from RoomManager:
- AgentRegistry — agent lifecycle, roles, tool equipment
- EventPublisher — event fan-out, calibration, SlidingEventWindow
- PhaseController — discussion → synthesis → closed FSM
- WorkflowStore — immutable workflow state with
update(fn)
npm run dev # hot-reload server
npm test # vitest (219 tests)
npm run lint # biome
npm run typecheck # tsc --noEmit (strict + noUncheckedIndexedAccess)See CONTRIBUTING.md for how to add tools, personas, and protocols.
Agent memories persist via embedded Postgres (Knowledge Engine) — always on, survives restarts. Event streams can optionally use Redis for durability:
- Embedded Postgres: agent memories with hybrid search (default, always enabled)
- Redis (optional): durable event streams, consumer groups, workflow recovery
- No OS-level execution sandbox — tool execution uses allowlists + approval gates, not containers. Suitable for trusted users, not arbitrary third-party agents.
- Single-process architecture — Redis event bus is multi-process-ready, but room orchestration is in-process only. No horizontal scaling yet.
- Agent-to-agent taint tracking is advisory — taint delimiters rely on LLM compliance, not enforcement. Agent messages are classified as trusted.
- Model pricing is hardcoded —
cost-estimator.tsprices will go stale. Override not yet configurable. - No artifact browser UI — backend supports artifact versioning; no frontend for browsing, diffing, or exporting artifacts.
- Vector search requires
@huggingface/transformers— falls back to keyword-only search if the optional dependency isn't installed. No UI indicator for fallback mode.
src/
agents/ Agent brain: graph-builder, base-agent, persona-loader, orchestrator
cli/ Interactive setup wizard (npx conclave init)
core/ Orchestration: room-manager, discussion-loop, synthesis, phase control
messaging/ Event bus (Redis + in-memory), thought channel, routing
models/ LLM factory, tokenizer, cost estimator, local embeddings
observability/ OpenTelemetry tracing (opt-in)
prompts/ All prompt templates (centralized)
protocols/ A2A adapter, debate state, evaluation, build protocol
server/ Connection handler, session manager, crypto utils
state/ Events schema, workflow state, checkpoints, event factory
storage/ KnowledgeEngine (embedded PG), artifact store, memory adapters
tools/ Tool registry, browser, code-runner, approval gate, taint tracking
types/ Shared TypeScript interfaces
web/ React frontend (Vite + Tailwind + @assistant-ui)
agents-repo/ 40+ agent persona definitions (markdown + YAML frontmatter)
custom-agents/ User-defined personas (same format, takes priority)
docs/ Architecture docs
In the web UI and CLI, the room is assembled after the first objective so the selected employees match the actual topic.
# First-time setup (creates ~/.conclave, clones agents-repo, writes config)
npx ts-node ./src/cli/init.ts init --quick
# Run the test suite
npm test
# KnowledgeEngine integration tests (excluded by default — requires embedded-postgres binary)
npx vitest run tests/integration/knowledge-engine-integrationSee LICENSE.