| name | multi-agent-orchestration-supervision |
| description | Especialista em Orquestração, Supervisão e Governança de Sistemas Multi-Agente. Focado em ancoragem de objetivos iniciais, detecção contínua de desvio de escopo (Agent Drift e Role Drift), intervenção proativa (Self-Correction), contenção gradual e aplicação de kill-switch/terminação segura de agentes não-conformes. |
Multi-Agent Orchestration, Supervision & Drift Governance
Esta skill estabelece a metodologia de supervisão, coordenação e controle de qualidade operacional sobre frotas de agentes autônomos em sistemas multi-agente hierárquicos e distribuídos.
🎯 1. Princípios Fundamentais do Supervisor
- Ancoragem de Intenção (Intent Grounding):
- Todo fluxo de trabalho começa com a extração e fixação do problema original do usuário em um contrato de intenção explícito.
- O contrato deve conter: Objetivo Primário, Restrições Inegociáveis, Entregáveis Esperados e Critérios de Parada.
- Vigilância Ativa de Execução (Observation Loop):
- O supervisor não executa o trabalho braçal de domínio, mas acompanha as chamadas de ferramentas, mensagens emitidas e arquivos modificados pelos subagentes.
- Princípio da Intervenção Mínima Eficiente:
- Ajustar primeiro com orientação contextual (re-prompting).
- Conter em seguida (limitar permissões ou pausar execução).
- Terminar (kill) apenas quando houver persistência de desvio, loop infinito ou risco operacional.
🔍 2. Taxonomia de Desvios (Agent Drift)
O supervisor deve monitorar continuamente os seguintes modos de falha:
| Categoria de Desvio | Sintoma Observável | Causa Raiz Típica | Ação Recomendada |
|---|
| Role Drift | Subagente de pesquisa tentando editar arquivos de produção; agente de frontend refatorando migrações de banco. | Alucinação de fronteira ou instrução de sistema permissiva. | Bloqueio imediato da ação e reiteração do escopo restrito do papel. |
| Scope Drift | Subagente expandindo a tarefa para refatorar módulos não solicitados ou criar funcionalidades não pedidas. | Otimização prematura ou perda da ancoragem de intenção. | Reprompt para abortar tarefas laterais e focar estritamente na meta. |
| Loop / Deadlock Drift | Subagente repetindo a mesma chamada de ferramenta com parâmetros idênticos ou alternando em ciclo sem progresso. | Falha em interpretar erros da ferramenta ou contexto poluído. | Cancelamento da operação, limpeza de contexto e fornecimento de estratégia alternativa. |
| Hallucinated Progress | Subagente emitindo status de conclusão sem que os arquivos físicos ou asserções tenham sido validados. | Resposta bajuladora (sycophancy) ou ausência de oráculo de validação. | Rejeição do status, exigência de evidência concreta de teste/execução. |
🛑 3. Protocolo de Contenção Gradual e Kill-Switch
Quando um agente demonstrar desvio, o supervisor aplica uma escala de resposta de 3 níveis:
Nível 1: Intervenção Orientativa (Nudge & Realignment)
Nível 2: Contenção de Estado e Rollback (Quarantine & Rollback)
- Reverter arquivos ou modificações incorretas geradas pelo subagente desviante.
- Limpar a memória recente contaminada ou reenviar uma síntese enxuta da tarefa.
Nível 3: Terminação Forçada (Kill-Switch)
- Se o agente insistir no comportamento errôneo após intervenção de Nível 1:
- Executar a chamada de encerramento imediato (
manage_subagents: kill ou cancelamento de tarefa).
- Registrar o log do desvio para auditoria pós-morte.
- Reatribuir a demanda a uma nova instância zerada ou assumir a condução.
📡 4. Protocolo de Comunicação TOON com Heartbeat
Na comunicação com subagentes delegados, o supervisor exige o envio de telemetria estruturada via protocolo TOON:
@FROM: <subagente>
@TO: orchestrator
@STATUS: <OK | BLOCKED | DRIFT_DETECTED | DONE>
@CTX: <id-tarefa-ancorada>
@PROGRESS: <resumo-do-avanço-realizado>
@NEXT_ACTION: <próxima-chamada-pretendida>
Se um subagente não responder ao supervisor em tempo hábil ou emitir ações discrepantes do @CTX, o processo de terminação é acionado preventivamente.
⛓️ 5. Governança de Concorrência e Prevenção de Rate-Limit
O supervisor é responsável por proteger a sessão contra estouro de quota dos provedores (429 Too Many Requests, RPM/TPM exceeded, tokens per minute). Para isso, mantém a concorrência sob controle:
5.1 Ledger de Subagentes
Mantenha um registro vivo com o estado de cada subagente:
| Estado | Significado |
|---|
ACTIVE | Em execução em paralelo neste momento. |
QUEUED | Delegado, mas aguardando um slot de concorrência abrir. |
DONE | Concluiu com sucesso. |
FAILED | Falhou sem sintoma de rate-limit (lógica, loop, drift). |
PAUSED | Falhou por rate-limit; aguarda relançamento quando houver folga. |
5.2 Teto de Paralelismo (Concurrency Cap)
- Regra central: nunca deixe mais de 5 agentes ativos simultaneamente contando com o próprio supervisor (ou seja, supervisor + no máximo 4 subagentes em
ACTIVE).
- Para delegar, calcule
ativos = 1 (você) + nº de subagentes ACTIVE. Enquanto ativos >= 5, não dispare novos subagentes: mova a tarefa para QUEUED e aguarde um sinal de DONE/FAILED/PAUSED para liberar o próximo da fila (FIFO).
5.3 Falha por Rate-Limit → Kill, Espera e Relaçamento
Sintomas de rate-limit: 429, HTTP 429, Too Many Requests, Rate limit, Quota exceeded, RPM exceeded, TPM exceeded, tokens per minute exceeded (em mensagens de erro, cabeçalhos de resposta ou status de ferramenta).
Ao detectar um desses sintomas num subagente ativo:
- Kill a instância imediatamente (kill-switch) e marque-a como
PAUSED, preservando a descrição da subtarefa e seu @CTX para retry.
- Espere enquanto o total ativo (você + demais ACTIVE) permanecer em 5; não relance ainda.
- Quando o total ativo cair abaixo de 5, relance a tarefa pausada (nova instância zerada) aplicando backoff exponencial entre tentativas: ≈2s na 1ª, 4s, 8s, 16s, 32s, até um teto de 60s. Zerar o estado da tarefa para
ACTIVE ao relançar.
- Esgotado um limite razoável de tentativas consecutivas (ex.: 5), reportar o
FAILED definitivo ao usuário e continuar o restante da fila.
5.4 Escopo do Retry
- Somente falhas com sintoma de rate-limit entram no fluxo de
PAUSED/retry.
- Qualquer outra falha (drift, loop, erro de lógica) segue o protocolo padrão de Nível 1/2/3 da seção 3, sendo tratada como
FAILED sem relaçamento automático.
5.5 Mecanismo Executável (não apenas instrucional)
O limite de paralelismo acima é aplicado em runtime por um governor de slots, não só descrito em prosa:
- Governor (
scripts/orchestrator-governor.sh): ledger com flock() atômico. acquire bloqueia (enfileira) quando o cap está saturado; fail marca PAUSED para retry. O cap = ORCH_MAX_CONCURRENT (default 5, contando com o orquestrador).
- Hooks Antigravity (
scripts/orchestrator-hook.sh + ~/.gemini/config/hooks.json chave orchestrator-governor): reservam slot em PreToolUse de invoke_subagent, liberam/marcam em PostToolUse e injetam o orçamento em PreInvocation.
- Plugin OpenCode (
scripts/orchestrator-gate.ts, deploy em ~/.config/opencode/plugins/orchestrator-gate.ts): intercepta o task, reserva slot antes do spawn, libera/marca após, e expõe a tool orchestrator_governor.
- Validação (
scripts/orchestrator-governor.test.sh e orchestrator-governor.check.sh): provam que o cap de N realmente segura os excessos e que o retry por 429 funciona. Rode bash scripts/orchestrator-governor.check.sh.
📐 6. Exemplo de Decisão de Escalonamento
Dada uma fila de 6 subtarefas independentes e o teto de 5:
- Você + 4 subagentes iniciados = 5 ativos. As 2 restantes ficam
QUEUED.
- Um dos subagentes ativos cai com
429. Você o mata → PAUSED. Ativos = 4.
- Libera a próxima
QUEUED como ACTIVE (ativos = 5) e relança a PAUSED (ativos = 6? não: aplica nova espera até ativos < 5).
Ajuste do teto: o valor 5 é o default (MAX_CONCURRENT = 5, contando com o orquestrador). Se o provedor em uso tiver limite menor (ex.: 3 RPM), reduza o teto proporcionalmente. O teto pode ser parametrizado via variável de ambiente ORCH_MAX_CONCURRENT quando o harness permitir.
