ORCHESTRATOR.md - Meta-Controlador de Agentes¶
Sistema de orquestração inteligente para composição dinâmica de squads.
Visão Geral¶
O Orchestrator é o "cérebro" do Sistema APEX.
Ele recebe input do usuário, classifica a intenção,
seleciona o squad ideal de agentes, coordena a execução
e sintetiza a resposta final.
FLUXO:
Input → Classification → Squad Selection → Execution → Synthesis → Output
Arquitetura do Orchestrator¶
┌─────────────────────────────────┐
│ USER INPUT │
└───────────────┬─────────────────┘
│
▼
┌─────────────────────────────────┐
│ INTENT CLASSIFIER │
│ (O que o usuário quer?) │
└───────────────┬─────────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ CONTEXT ANALYZER│ │ SQUAD SELECTOR │ │EMERGENCY DETECTOR│
│ (Qual o contexto)│ │(Quais agentes?) │ │ (Há urgência?) │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
└─────────────────────┼─────────────────────┘
│
▼
┌─────────────────────────────────┐
│ EXECUTION ENGINE │
│ (Coordena agentes em paralelo)│
└───────────────┬─────────────────┘
│
▼
┌─────────────────────────────────┐
│ SYNTHESIS ENGINE │
│ (Integra perspectivas, resolve │
│ conflitos, gera recomendação) │
└───────────────┬─────────────────┘
│
▼
┌─────────────────────────────────┐
│ FINAL OUTPUT │
└─────────────────────────────────┘
1. Intent Classifier¶
Categorias de Intenção¶
DECISION:
Description: Usuário precisa tomar uma decisão
Keywords:
- "devo", "deveria", "melhor", "escolher"
- "X ou Y", "qual opção", "decidir"
- "vale a pena", "faz sentido"
Default Squad: CEO Zero + Pre-Mortem + área específica
Priority: HIGH
PLANNING:
Description: Usuário quer planejar algo
Keywords:
- "como fazer", "planejar", "roadmap"
- "estratégia", "próximos passos", "timeline"
- "implementar", "executar", "desenvolver"
Default Squad: Focus Guardian + CPO + área específica
Priority: MEDIUM
ANALYSIS:
Description: Usuário quer analisar/entender algo
Keywords:
- "analisar", "entender", "por que"
- "avaliar", "comparar", "benchmark"
- "métricas", "dados", "resultados"
Default Squad: Head of Data + área específica
Priority: MEDIUM
VALIDATION:
Description: Usuário quer validar ideia/hipótese
Keywords:
- "validar", "testar", "verificar"
- "faz sentido", "está certo", "funciona"
- "feedback", "opinião", "review"
Default Squad: Contrarian + Pre-Mortem + área específica
Priority: MEDIUM
CREATION:
Description: Usuário quer criar algo
Keywords:
- "criar", "escrever", "desenvolver"
- "PRD", "pitch", "campanha", "conteúdo"
- "design", "arquitetura", "feature"
Default Squad: área específica + peers
Priority: MEDIUM
TROUBLESHOOTING:
Description: Usuário tem um problema
Keywords:
- "problema", "erro", "bug", "issue"
- "não funciona", "caiu", "falhou"
- "resolver", "consertar", "debugging"
Default Squad: CTO + AI Scientist + área específica
Priority: HIGH
EMERGENCY:
Description: Crise detectada
Keywords:
- "urgente", "crise", "emergência"
- "burnout", "exausto", "desistir"
- "falir", "acabou", "processo"
Default Squad: Founder Coach + CEO Zero + Pre-Mortem
Priority: CRITICAL
Algoritmo de Classificação¶
def classify_intent(user_input):
"""
Classifica a intenção do usuário.
Returns:
intent_type: str
confidence: float (0-1)
keywords_matched: list
"""
# 1. Check for emergency first (highest priority)
emergency_signals = detect_emergency_signals(user_input)
if emergency_signals:
return Intent(
type="EMERGENCY",
confidence=1.0,
keywords=emergency_signals,
priority="CRITICAL"
)
# 2. Score each intent category
scores = {}
for intent_type, config in INTENT_CONFIGS.items():
matched_keywords = find_keywords(user_input, config.keywords)
scores[intent_type] = len(matched_keywords) / len(config.keywords)
# 3. Get top intent
top_intent = max(scores, key=scores.get)
# 4. If tie or low confidence, use DECISION as default
if scores[top_intent] < 0.2:
top_intent = "DECISION"
return Intent(
type=top_intent,
confidence=scores[top_intent],
keywords=matched_keywords,
priority=INTENT_CONFIGS[top_intent].priority
)
2. Context Analyzer¶
Dimensões de Contexto¶
TEMPORAL:
Description: Quando isso é relevante?
Factors:
- Urgência (agora, esta semana, este quarter)
- Timeline afetada (curto/médio/longo prazo)
- Deadlines conhecidos (milestones, lançamentos)
Output: urgency_level (1-5)
SCOPE:
Description: Qual a abrangência?
Factors:
- Afeta quantas áreas? (1-7 tiers)
- Afeta quantos stakeholders?
- Impacto em métricas-chave
Output: scope_level (narrow/medium/broad)
REVERSIBILITY:
Description: Quão reversível é?
Factors:
- Pode desfazer? (sim/parcial/não)
- Custo de reverter (baixo/médio/alto)
- Tempo para reverter (horas/dias/meses)
Output: decision_type (Type 1 = irreversível, Type 2 = reversível)
RISK:
Description: Qual o nível de risco?
Factors:
- Impacto se der errado (baixo/médio/alto/fatal)
- Probabilidade de falha
- Existem mitigações?
Output: risk_level (1-5)
DEPENDENCIES:
Description: Do que isso depende?
Factors:
- Decisões anteriores relacionadas
- Recursos necessários (pessoas, dinheiro, tempo)
- Bloqueadores potenciais
Output: dependencies_list
Context Assessment Template¶
CONTEXT_ASSESSMENT:
Query: "[input do usuário]"
Temporal:
Urgency: [1-5]
Horizon: [short/medium/long]
Deadlines: [list ou "none"]
Scope:
Level: [narrow/medium/broad]
Tiers Affected: [list de tiers]
Metrics Impacted: [list de métricas]
Reversibility:
Type: [1 ou 2]
Revert Cost: [low/medium/high]
Revert Time: [hours/days/months]
Risk:
Level: [1-5]
Impact if Fail: [low/medium/high/fatal]
Mitigations: [exist/partial/none]
Dependencies:
Prior Decisions: [list]
Resources Needed: [list]
Blockers: [list ou "none"]
3. Squad Selector¶
Algoritmo de Seleção¶
def select_squad(intent, context, activation_matrix):
"""
Seleciona o squad ideal de agentes.
Rules:
- Mínimo 2 agentes
- Máximo 5 agentes (evitar overload)
- Sempre incluir pelo menos 1 de Protection tier
- Para decisões Type 1, mínimo 3 agentes
Returns:
squad: list[Agent]
roles: dict (agent -> role in squad)
"""
squad = []
# 1. Start with intent default squad
default_squad = intent.default_squad
squad.extend(default_squad)
# 2. Add area-specific agents based on keywords
area_agents = activation_matrix.get_agents(intent.keywords)
for agent in area_agents:
if agent not in squad and len(squad) < 5:
squad.append(agent)
# 3. Ensure Protection tier is represented
if not has_protection_tier(squad):
squad.append(PRE_MORTEM) # Default protection
# 4. For Type 1 decisions, add CEO Zero if not present
if context.reversibility.type == 1:
if CEO_ZERO not in squad:
squad.insert(0, CEO_ZERO)
# 5. For high risk, add Focus Guardian
if context.risk.level >= 4:
if FOCUS_GUARDIAN not in squad and len(squad) < 5:
squad.append(FOCUS_GUARDIAN)
# 6. Check for emergency override
if intent.type == "EMERGENCY":
squad = [FOUNDER_COACH, CEO_ZERO, PRE_MORTEM]
# 7. Assign roles
roles = assign_roles(squad, intent, context)
return squad, roles
Roles no Squad¶
LEAD:
Description: Agente principal que conduz a análise
Responsibilities:
- Estrutura a resposta
- Integra inputs dos outros
- Faz recomendação final
Selection: Agente mais relevante para o intent
VALIDATOR:
Description: Agente que questiona e valida
Responsibilities:
- Identifica riscos
- Questiona assumptions
- Sugere alternativas
Selection: Pre-Mortem ou Contrarian
SPECIALIST:
Description: Agente com expertise específica
Responsibilities:
- Provê conhecimento técnico
- Detalha implementação
- Identifica edge cases
Selection: Baseado em área do problema
ADVISOR:
Description: Agente que traz perspectiva adicional
Responsibilities:
- Contexto histórico
- Lessons learned
- Best practices
Selection: Baseado em dependencies
Squad Compositions Típicas¶
PRICING_DECISION:
Lead: CRO
Validator: Pre-Mortem
Specialist: CFO
Advisor: Focus Guardian
Total: 4 agents
FEATURE_PLANNING:
Lead: CPO
Validator: Focus Guardian
Specialist: CDO + CTO
Total: 4 agents
MARKET_EXPANSION:
Lead: Expansion Strategist
Validator: Pre-Mortem
Specialist: Marketplace Expert
Advisor: CFO
Total: 4 agents
BURNOUT_CRISIS:
Lead: Founder Coach (absoluto)
Support: CEO Zero
Validator: Focus Guardian
Total: 3 agents (menos é mais aqui)
COMPETITIVE_THREAT:
Lead: Competitive Intel
Validator: Pre-Mortem
Specialist: CMO + Growth
Advisor: CEO Zero
Total: 5 agents
4. Execution Engine¶
Modelo de Execução¶
PARALLEL_EXECUTION:
Description: Agentes trabalham simultaneamente
Use When:
- Inputs são independentes
- Não há dependência entre agentes
- Urgência alta
How:
- Cada agente recebe o contexto
- Produz output independente
- Outputs coletados para síntese
SEQUENTIAL_EXECUTION:
Description: Agentes trabalham em ordem
Use When:
- Output de um é input de outro
- Dependências claras entre agentes
- Decisão Type 1 (precisa mais cuidado)
How:
- Primeiro agente analisa
- Próximo recebe análise + adiciona
- Chain até o último
HYBRID_EXECUTION:
Description: Combinação de paralelo e sequencial
Use When:
- Alguns agentes são independentes
- Outros dependem dos primeiros
- Caso mais comum
How:
- Fase 1: Paralelo (independentes)
- Fase 2: Sequencial (dependentes)
- Fase 3: Síntese
Execution Flow¶
┌─────────────────────────────────────────────────────────────────┐
│ EXECUTION ENGINE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ FASE 1: PARALLEL GATHER │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ Agent 4 │ │
│ │ (Lead) │ │(Validtr)│ │(Specist)│ │(Advisor)│ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ OUTPUT BUFFER │ │
│ │ [output_1, output_2, output_3, output_4] │ │
│ └────────────────────────┬────────────────────────┘ │
│ │ │
│ FASE 2: CONFLICT DETECTION │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ CONFLICT DETECTOR │ │
│ │ - Identifica contradições │ │
│ │ - Mapeia divergências │ │
│ │ - Lista consensos │ │
│ └────────────────────────┬────────────────────────┘ │
│ │ │
│ FASE 3: RESOLUTION (se houver conflitos) │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ CONFLICT RESOLVER │ │
│ │ - Aplica hierarquia de prioridade │ │
│ │ - Busca síntese quando possível │ │
│ │ - Escala para CEO Zero se necessário │ │
│ └────────────────────────┬────────────────────────┘ │
│ │ │
│ FASE 4: SYNTHESIS │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ SYNTHESIS ENGINE │ │
│ │ - Integra perspectivas │ │
│ │ - Formata resposta │ │
│ │ - Gera recomendação │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
5. Synthesis Engine¶
Estrutura de Síntese¶
SYNTHESIS_COMPONENTS:
1. CONSENSUS_EXTRACTION:
- Identificar pontos onde todos concordam
- Marcar como "alta confiança"
- Usar como base da recomendação
2. DIVERGENCE_MAPPING:
- Listar onde agentes discordam
- Explicar razão da divergência
- Apresentar ambos os lados
3. RISK_AGGREGATION:
- Coletar todos os riscos identificados
- Remover duplicatas
- Ordenar por impacto × probabilidade
4. RECOMMENDATION_FORMULATION:
- Baseada em consensos
- Acknowledge divergências
- Incluir mitigações para riscos
5. NEXT_STEPS_GENERATION:
- Ações concretas
- Responsáveis quando aplicável
- Checkpoints de validação
Output Template¶
## Análise: [Tema da Query]
### 🎯 Squad Consultado
| Agente | Role | Perspectiva Principal |
|--------|------|----------------------|
| [Agent 1] | Lead | [1 frase] |
| [Agent 2] | Validator | [1 frase] |
| [Agent 3] | Specialist | [1 frase] |
| [Agent 4] | Advisor | [1 frase] |
### ✅ Consensos (Alta Confiança)
1. [Ponto de consenso 1]
2. [Ponto de consenso 2]
3. [Ponto de consenso 3]
### ⚖️ Divergências
| Posição A | Posição B | Recomendação |
|-----------|-----------|--------------|
| [Agent X]: [posição] | [Agent Y]: [posição] | [Como resolver] |
### ⚠️ Riscos Identificados
| Risco | Impacto | Probabilidade | Mitigação |
|-------|---------|---------------|-----------|
| [Risco 1] | [H/M/L] | [H/M/L] | [Ação] |
| [Risco 2] | [H/M/L] | [H/M/L] | [Ação] |
### 💡 Recomendação
[Recomendação clara e acionável, baseada na síntese]
**Tipo de Decisão:** [Type 1 (Irreversível) / Type 2 (Reversível)]
**Confiança:** [Alta / Média / Baixa]
**Justificativa:** [Por que esta recomendação]
### 📋 Próximos Passos
1. [ ] [Ação 1] - [Responsável]
2. [ ] [Ação 2] - [Responsável]
3. [ ] [Ação 3] - [Responsável]
### 🔄 Checkpoint
- Revisar em: [Quando]
- Validar: [O que]
- Métricas: [Como medir sucesso]
6. Emergency Handler¶
Detecção de Emergência¶
BURNOUT_SIGNALS:
Keywords:
- "exausto", "cansado demais", "burnout"
- "não aguento mais", "quero desistir"
- "trabalhando demais", "sem dormir"
- "ansioso", "deprimido", "perdido"
Action: IMMEDIATE_PAUSE
Handler: Founder Coach (EXCLUSIVO)
Protocol:
1. PARAR qualquer análise em andamento
2. Ativar Founder Coach
3. Check-in compassivo
4. Só continuar após OK do Coach
EXISTENTIAL_RISK:
Keywords:
- "falir", "acabou o dinheiro", "runway zero"
- "processo judicial", "multa", "compliance"
- "concorrente matou", "mercado fechou"
Action: CRISIS_MODE
Handler: CEO Zero + Pre-Mortem + Legal
Protocol:
1. Avaliar gravidade real
2. Opções imediatas
3. Plano de contingência
4. Escalar se necessário
FOCUS_DRIFT:
Signals:
- Pedido de feature fora do roadmap
- "O concorrente tem..."
- "Seria legal se..."
- Pivot sem validar PMF
Action: GENTLE_REDIRECT
Handler: Focus Guardian
Protocol:
1. Reconhecer a ideia
2. Perguntar: "Isso é prioridade Q1?"
3. Sugerir parking lot
4. Retornar ao foco
Emergency Override Matrix¶
┌─────────────────────────────────────────────────────────────────┐
│ EMERGENCY PRIORITY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ NÍVEL 0: SAÚDE DO FOUNDER │
│ ├─ Override: ABSOLUTO │
│ ├─ Handler: Founder Coach │
│ └─ Regra: Nada é mais importante │
│ │
│ NÍVEL 1: RISCO EXISTENCIAL │
│ ├─ Override: Todas outras tarefas │
│ ├─ Handler: CEO Zero + Pre-Mortem │
│ └─ Regra: Sobrevivência primeiro │
│ │
│ NÍVEL 2: COMPLIANCE/LEGAL │
│ ├─ Override: Decisões de negócio │
│ ├─ Handler: Legal & AI Ethics │
│ └─ Regra: Lei > Growth │
│ │
│ NÍVEL 3: FOCO │
│ ├─ Override: Novas iniciativas │
│ ├─ Handler: Focus Guardian │
│ └─ Regra: Prioridades > Oportunidades │
│ │
└─────────────────────────────────────────────────────────────────┘
7. Configuration¶
Orchestrator Settings¶
ORCHESTRATOR_CONFIG:
# Squad Configuration
squad:
min_agents: 2
max_agents: 5
always_include_protection: true
type1_min_agents: 3
# Execution Configuration
execution:
default_mode: "hybrid"
timeout_per_agent: 30s
max_total_time: 180s
parallel_limit: 4
# Synthesis Configuration
synthesis:
consensus_threshold: 0.7 # 70% agreement = consensus
divergence_threshold: 0.3 # <30% agreement = divergence
risk_sort_by: "impact * probability"
# Emergency Configuration
emergency:
burnout_priority: 0
existential_priority: 1
legal_priority: 2
focus_priority: 3
# Output Configuration
output:
format: "markdown"
include_reasoning: true
include_confidence: true
include_next_steps: true
Tuning Parameters¶
TUNING:
# Quando adicionar mais agentes
expand_squad_when:
- scope.level == "broad"
- risk.level >= 4
- context.reversibility.type == 1
- intent.type == "DECISION" and confidence < 0.5
# Quando reduzir agentes
reduce_squad_when:
- scope.level == "narrow"
- urgency > 4 (precisa de velocidade)
- intent.type == "TROUBLESHOOTING" (foco técnico)
# Quando escalar para humano
escalate_when:
- conflito_nao_resolvido entre agentes
- confiança da recomendação < 0.4
- tipo de decisão == Type 1 and risk >= 4
- emergency detectada
8. Logging e Observabilidade¶
Log Structure¶
ORCHESTRATION_LOG:
timestamp: "2025-12-28T14:30:00Z"
session_id: "sess_abc123"
input:
raw_query: "[query do usuário]"
intent_classified: "DECISION"
intent_confidence: 0.85
keywords_matched: ["pricing", "decidir"]
context:
urgency: 3
scope: "medium"
reversibility: "Type 2"
risk: 2
squad:
selected: ["CRO", "CFO", "Pre-Mortem", "Focus Guardian"]
roles:
CRO: "Lead"
Pre-Mortem: "Validator"
CFO: "Specialist"
Focus Guardian: "Advisor"
execution:
mode: "hybrid"
duration_ms: 2340
agents_completed: 4
conflicts_detected: 1
conflicts_resolved: 1
output:
recommendation_given: true
confidence: "High"
next_steps: 3
risks_identified: 2
feedback:
user_accepted: null # Preenchido depois
outcome: null # Preenchido depois
Métricas do Orchestrator¶
ORCHESTRATOR_METRICS:
# Performance
avg_response_time_ms: [track]
squad_size_distribution: [histogram]
execution_mode_usage: [parallel/sequential/hybrid %]
# Quality
conflict_rate: [% de respostas com conflitos]
resolution_rate: [% de conflitos resolvidos]
escalation_rate: [% escalado para humano]
# Accuracy (feedback-based)
recommendation_acceptance_rate: [% aceitas pelo usuário]
outcome_success_rate: [% que deram certo]
# Coverage
tier_usage_distribution: [% de uso por tier]
agent_usage_distribution: [% de uso por agente]
intent_distribution: [% por tipo de intent]
9. Integração com Sistema APEX¶
APEX_INTEGRATION:
WORKFLOWS.md:
- Orchestrator usa workflows para execuções complexas
- Cada workflow tem squad pré-definido
- Pode override baseado em contexto
DEPENDENCY-MAP.md:
- Orchestrator consulta para ordenação
- Evita chamar agente sem upstream pronto
- Usa para identificar bottlenecks
AGENT-INTERFACES.md:
- Orchestrator valida inputs antes de chamar
- Garante que outputs atendem spec
- Usa para routing entre agentes
MEMORY-SYSTEM.md:
- Orchestrator registra cada execução
- Consulta histórico para context
- Aprende de feedback
LEARNING-SYSTEM.md:
- Orchestrator alimenta feedback loops
- Ajusta weights baseado em outcomes
- Melhora squad selection over time
REASONING-FRAMEWORK.md:
- Orchestrator mostra reasoning visível
- Explica por que squad foi escolhido
- Transparência na síntese
10. Comandos do Orchestrator¶
# Ver status do orchestrator
/orchestrator status
# Ver último squad usado
/orchestrator last-squad
# Forçar modo de execução
/orchestrator mode parallel
/orchestrator mode sequential
/orchestrator mode hybrid
# Ver métricas
/orchestrator metrics
# Debug mode (mostra reasoning completo)
/orchestrator debug on
/orchestrator debug off
# Ver log de sessão
/orchestrator log [session_id]
11. Integração MCP (ADR-014)¶
O Orchestrator é implementado via ferramenta MCP orchestrateAgents:
Tool: orchestrateAgents¶
orchestrateAgents({
query: string, // Pergunta do usuário
maxAgents?: number, // 1-7, default: 3
forcedAgents?: string[], // Forçar inclusão
excludeAgents?: string[] // Excluir específicos
})
Retorno¶
{
"query": "...",
"selectedCount": 3,
"reasoning": "Explicação da seleção",
"agents": [
{ "id": "cfo", "name": "...", "role": "...", "model": "sonnet" },
...
],
"instruction": "Como usar os agentes selecionados"
}
Workflow Automatizado¶
1. Usuário faz pergunta complexa
2. Claude detecta necessidade de múltiplas perspectivas
3. Executa: orchestrateAgents({ query, maxAgents: 3 })
4. Sistema seleciona squad baseado em:
- ACTIVATION-MATRIX.md (keywords)
- Context (urgência, scope)
- Regras de conflito
5. Claude consulta cada agente
6. Sintetiza em resposta multi-perspectiva
Tools Relacionados¶
| Tool | Uso |
|---|---|
detectAgentTrigger |
Pré-análise - quais agentes são relevantes |
orchestrateAgents |
Seleção e preparação do squad |
agentConsensus |
Síntese pós-consulta |
agentDebate |
Resolução de conflitos |
Changelog¶
| Data | Mudança |
|---|---|
| 2025-12-28 | Criação inicial como parte do Sistema APEX Fase 3 |
| 2025-12-29 | Harmonização com REASONING-FRAMEWORK.md (mapeamento de steps) |
| 2026-01-17 | Integração com MCP tools (ADR-014) |