Multiagentz (MAZ)
ZlaylowZ/multiagentz
Orquestre equipes de agentes IA via YAML, sem código Python
Ver no GitHubFramework de orquestração multi-agente declarativo baseado em YAML para compor equipes de agentes especializados em código sem necessidade de programação Python. Integra múltiplos provedores de IA (Anthropic, OpenAI, xAI, Google) com roteamento inteligente, execução paralela e síntese de respostas, incluindo modos de operação avançados como análise de perspectivas cruzadas e A/B testing com agentes gêmeos.
Instalação
npx convez-ai ZlaylowZ/multiagentz1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Estruturar equipes de agentes especializados em domínios diferentes (backend, frontend, infra)
- Análise multi-perspectiva de bases de código com roteamento automático de consultas
- Otimizar custos usando modelos diferentes por agente conforme complexidade
- Implementar workflows de consensus, cross-pollination e builder mode entre agentes
Veredito

Ferramenta sólida para orquestração declarativa de agentes IA, reduzindo drasticamente o overhead de code-first. Ideal para times que querem composição ágil de agentes especializados sem mergulhar em Python puro, embora dependa de setup inicial via CLI e conhecimento de YAML estruturado.
README
A tradução para o português deste README ainda está na fila.
multiagentz (maz)
Multi-agent orchestration framework. Define domain-expert AI agent teams in YAML and run them from your terminal.

What It Does
You describe your agent hierarchy in a YAML file — which code repositories each agent knows about, what models they use, how they're grouped — and multiagentz builds the full system: intelligent routing, parallel queries, response synthesis, caching, and a terminal interface.
One YAML file is the entire interface. Practically no Python coding required.
Quick Start
# 1. Clone the repo via
# brew install gh (and install homebrew if necesary)
gh repo clone ZlaylowZ/multiagentz
# 2. Go into the repo directory
cd multiagentz
# 3. Install Python (preferably via homebrew) [ask agent for assistance if unsure)
# Create a virtual environment and activate it
python3 -m venv .venv
source .venv/bin/activate
# 4. Install
pip install -e ".[all]"
# 5. Add your API key(s) — the setup wizard walks you through it
maz setup
# 6. Run
# First, use preferred LLM to construct YAML stack, then save the .yaml to multiagentz/stacks/example.yaml and then run
maz --config stacks/example.yaml
New to this? See SETUP.md for a complete beginner walkthrough with Claude Code. Want the full picture? See GUIDE.md for the user guide covering all complexity levels and the maz → Claude Code workflow.
Features
- Declarative YAML — Define agent teams without writing code
- Multi-provider support — Anthropic, OpenAI, xAI (Grok), Google (Gemini)
- Per-agent models — Use different AI models for different agents
- Cost optimization — Expensive models for complex routing, cheap models for simple lookups
- Orchestration modes — Standard, consensus, perspective-based analysis, and builder mode
- Cross-pollination — A/B twin agents using different models for cognitive diversity
- Auto provider detection — Model name determines provider automatically
How It Works
1. Define a Stack (YAML)
name: my-project
lead:
keywords:
backend: [api, endpoint, database, server]
frontend: [react, component, hook, ui]
agents:
backend:
repo_path: /path/to/backend
description: Backend API and database layer
model: claude-sonnet-4-20250514
key_files: [src/, README.md]
frontend:
repo_path: /path/to/frontend
description: React frontend application
model: gemini-2.0-flash # Cheaper model for frontend
key_files: [src/, package.json]
2. Run It
maz --config stacks/my-stack.yaml
3. Ask Questions
The lead agent automatically routes to the right sub-agent(s), queries them in parallel, and synthesizes responses.
Architecture
LeadAgent (classify -> route -> query -> synthesize -> cache)
+-- SubAgent "backend" (loads /path/to/backend)
+-- SubAgent "frontend" (loads /path/to/frontend)
+-- CoordinatorAgent "infra" (nested sub-coordinator)
| +-- SubAgent "devops"
| +-- SubAgent "database"
+-- FileHandlerAgent (watches arbitrary files)
Core Components
| Component | Purpose |
|---|---|
| SubAgent | Domain expert backed by a local file tree. Loads key files into LLM context. |
| CoordinatorAgent | Routes to child agents, queries in parallel, synthesizes. Nestable. |
| LeadAgent | Top-level orchestrator: keyword hints + LLM routing + parallel query + synthesis + cache. |
| FileHandlerAgent | Watches arbitrary files/directories. Persistent watch list. |
| ArchitectAgent | Decomposes tasks into dependency-ordered DAG plans. Validates structure, detects cycles, replans on failure. |
| BuilderAgent | Executes scoped coding tasks. Write-validate-fix loop with structured JSON output. Composes SubAgent for file context. |
| TaskDAG | Walks dependency graph, spawns BuilderAgents in parallel, handles failure with Architect-mediated replanning. |
| LLMClient | Unified multi-provider client (Anthropic, OpenAI, xAI, Google). |
Supported LLM Providers
| Provider | Models | Setup |
|---|---|---|
| Anthropic | Claude Opus 4, Sonnet 4, Haiku 3.5 | console.anthropic.com |
| OpenAI | GPT-4o, o4-mini, o3 | platform.openai.com |
| xAI | Grok-4, Grok-4.1 | console.x.ai |
| Gemini 2.0 Flash, Gemini 2.5 Pro | aistudio.google.com |
Provider is automatically detected from model name (claude-* -> Anthropic, grok-* -> xAI, etc.).
Configuration
API Keys (.env)
Create a .env file in the project root with your API keys:
# You only need ONE provider to get started
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# XAI_API_KEY=xai-...
# GOOGLE_API_KEY=...
# MISTRAL_API_KEY=...
# Optional: override the default model for a provider
# ANTHROPIC_MODEL=claude-opus-4-6
# XAI_MODEL=grok-4-fast-reasoning
# Optional: global model override (any provider)
# MAZ_LLM_MODEL=claude-sonnet-4-20250514
You only need one provider to get started. For cross-pollination (twin agents), use the same model (e.g., TwinA_claude-opus, TwinB_claude-opus) or use different providers and models.
YAML Stack Reference
name: stack-name
orchestration:
mode: standard # standard | consensus | perspective | builder
max_iterations: 3 # Refinement cycles
cross_pollination: false # A/B twin agent loops
lead:
model: claude-sonnet-4-20250514 # Model for routing
routing_prompt_extra: |
Domain-specific routing instructions...
keywords:
agent_name: [keyword1, keyword2]
agents:
my_agent:
repo_path: /absolute/path
description: What this agent knows
model: claude-sonnet-4-20250514 # Per-agent model
system_prompt: |
You are an expert on ...
key_files:
- src/
- README.md
my_group:
type: coordinator
description: Groups related agents
agents:
child1:
repo_path: /path
key_files: [src/]
child2:
repo_path: /path
key_files: [lib/]
Orchestration Modes
Standard (Default)
Basic routing and synthesis.
Consensus
Detects conflicts between agents, iteratively refines until agreement.
Perspective
Multi-perspective analysis: independent solutions, LEAD review, iterative refinement, consensus synthesis.
Cross-Pollination
A/B twin agents (different models) exchange outputs and refine. Produces cognitively diverse results.
Builder
Plan-act-validate loop. Shifts from read-only analysis to code generation.
The ArchitectAgent decomposes a task into a dependency-ordered DAG. BuilderAgents execute each subtask — writing files, running shell commands, and validating results. Independent tasks run in parallel. Failures trigger automatic replanning via the Architect.
How it works:
- Architect plans — decomposes your task into dependency-ordered subtasks with validation commands
- You approve — plan displayed in terminal, confirm with
y, edit withe(opens$EDITOR), or cancel withN - Builders execute — parallel execution with write-validate-fix loops, automatic retry on failure
Stack configuration:
name: my-project-builder
orchestration:
mode: builder
max_iterations: 3
architect:
model: claude-opus-4-6 # Quality planning
builder_defaults:
model: claude-sonnet-4-20250514 # Fast implementation
max_retries: 3
max_tokens: 16384
validation_commands:
- "python -m py_compile {file}"
- "ruff check {file} --select E,F"
workspace: /path/to/your/project
Usage:
maz --config stacks/my-builder.yaml
> /build Add user authentication with JWT tokens
Performance Tuning
Routing Optimizations
maz uses two fast-path optimizations to eliminate unnecessary LLM routing calls:
Keyword fast-routing (LeadAgent) — When keywords in your YAML match the query and resolve to a single agent, the lead skips the LLM routing call entirely and routes directly. This saves one full LLM round-trip per query. To take advantage of this, define thorough keyword lists for your agents:
lead:
keywords:
backend: [api, endpoint, database, server, query, migration, schema]
frontend: [react, component, hook, ui, css, layout, render]
Twin fast-routing (CoordinatorAgent) — When all sub-agents in a coordinator are configured as cross-pollination twins, the coordinator skips its routing LLM call since cross-pollination always runs both agents regardless of the routing decision. No configuration needed — this activates automatically when twin: is set on all agents in a coordinator group.
Bootstrap Q&A Parallelization
During the Bootstrap Q&A phase of perspective mode, the LEAD agent answers perspective questions in parallel rather than sequentially. Each question can trigger a full routing → sub-agent → synthesis chain, so parallelizing them is the single largest performance improvement for perspective mode stacks.
No configuration needed — this is automatic.
Tunable Parameters
These parameters control the speed/depth/cost tradeoff. All are set in your YAML stack file.
| Parameter | Location | Default | Effect |
|---|---|---|---|
max_iterations | orchestration: | 3 | Number of LEAD review + refinement cycles in perspective mode. Each iteration adds a full round of LLM calls per perspective. |
key_files | per agent | — | Files loaded into each agent's system prompt. More files = richer context but higher token usage per call. |
max_context_chars | per agent | 600,000 | Character cap for file loading (~170K tokens). Reduce to lower per-agent token usage. |
max_tokens | per agent | 32,768 | Max generation tokens per LLM call. Lower values produce shorter responses but reduce cost and latency. |
model | per agent | global default | Model used for each agent. Cheaper/faster models for simple agents dramatically reduce cost. |
| Bootstrap Q&A turns | hardcoded | 3 | Max Q&A turns per perspective before proceeding. |
| Questions per turn | hardcoded | 5 | Max questions extracted per Q&A turn. |
Recommended Configurations
Fast/cheap (quick analysis, 5-15 min):
orchestration:
mode: perspective
max_iterations: 1 # Single review pass, no refinement loop
cross_pollination: false # Skip the twin swap-refine cycle
lead:
model: claude-sonnet-4-20250514 # Sonnet for routing (cheaper than Opus)
agents:
my_agent:
model: claude-sonnet-4-20250514
key_files: [src/main.py, README.md] # Minimal files
Balanced (thorough analysis, 20-40 min):
orchestration:
mode: perspective
max_iterations: 2 # One review + one refinement
cross_pollination: true
lead:
model: claude-sonnet-4-20250514
agents:
planner:
type: coordinator
agents:
A:
model: claude-opus-4-6 # Opus for depth
key_files: [src/, docs/]
twin: B
B:
model: claude-opus-4-6
key_files: [src/, docs/]
twin: A
Maximum depth (exhaustive reconciliation, 45-90 min):
orchestration:
mode: perspective
max_iterations: 3 # Full three-pass refinement
cross_pollination: true
lead:
model: claude-opus-4-6 # Opus everywhere
agents:
planner:
type: coordinator
agents:
A:
model: claude-opus-4-6
key_files: [src/, lib/, docs/, tests/] # Full repo
twin: B
B:
model: claude-opus-4-6
key_files: [src/, lib/, docs/, tests/]
twin: A
Token Limits and Prompt Budgeting
LLM APIs enforce hard input token limits (e.g. Anthropic: 200K tokens). In complex orchestration modes, prompts can grow very large as Q&A context, solution text, and file contents accumulate across phases.
multiagentz handles this automatically at two layers:
-
Orchestration-level guards — Smart truncation at each accumulation point: Q&A bootstrap history (300K chars), solution generation context (300K chars), LEAD review payloads (550K chars spread across perspectives), refinement prompts (300K chars), synthesis inputs (550K chars spread), and cross-pollination swap rounds (300K chars per side). Each section is budgeted independently so no single section starves the others.
-
LLMClientsafety net — Every API call runs a pre-flight token estimate. If the prompt + system prompt would exceed 195K tokens, the prompt is automatically truncated with a warning log. This is the last-resort catch-all that prevents400 prompt is too longerrors.
These character budgets are defined as constants in orchestration.py and llm_client.py:
# orchestration.py
_MAX_SECTION_CHARS = 300_000 # ~85K tokens — max for one text section
_MAX_COMBINED_CHARS = 550_000 # ~157K tokens — max for multi-section prompts
# llm_client.py
MAX_INPUT_TOKENS = 195_000 # Pre-flight token limit (below 200K API max)
To adjust these limits, edit the constants directly. Raising them increases context fidelity but risks hitting the API limit; lowering them reduces cost and increases headroom.
Timeout Resilience
If an API call times out during refinement, reconciliation, or synthesis, the framework gracefully degrades instead of crashing:
- Refinement timeout → carries forward the previous solution
- Reconciliation timeout → falls back to the longer agent output
- Synthesis timeout → concatenates all perspective outputs with section headers
The underlying HTTP timeout is configured in llm_client.py (default: 600s with 3 retries). These resilience behaviors are automatic and require no configuration.
REPL Commands
| Command | Description |
|---|---|
/help | List commands |
/clear | Clear conversation memory |
/cache | Cache stats |
/file <path> | Load file as question |
/paste | Multi-line input mode |
/watch <path> | Watch a file/directory |
/scan <path> | Watch + auto-summarize |
/brief | Toggle brief responses |
/export [html|md|txt] | Export last response |
/perspective "<q>" | Multi-perspective analysis |
/consensus <q> | Force consensus mode |
/build <task> | Execute a coding task via Architect → Builder pipeline |
/promote <agent> | Promote to LEAD_SUB |
/status | Show orchestration status |
Example Stacks
| File | Description |
|---|---|
stacks/example.yaml | Simple two-agent stack |
stacks/advanced_example.yaml | Multi-provider with cross-pollination |
stacks/template.yaml | Full reference with all options |
stacks/minimal.yaml | Bare minimum starter |
stacks/builder_test.yaml | Builder mode with validation |
Features
Built for Claude Code — Run deep multi-agent analysis, get an auto-exported HTML artifact, and hand it directly to Claude Code for implementation. The hard thinking happens here; the building happens
License
MIT