Orquestrador de Tarefas Multi-Agente

Visão Geral

Um padrão testado em produção para coordenar múltiplos agentes de IA através de um único orquestrador. Em vez de deixar os agentes trabalharem independentemente (e entrarem em conflito), um orquestrador decompõe tarefas, as encaminha para especialistas, evita trabalho duplicado e verifica os resultados antes de marcar qualquer coisa como concluída. Testado em batalha em mais de 10.000 tarefas ao longo de 6 meses.

Quando Usar Esta Habilidade

• Use quando você tem 3+ agentes especializados que precisam coordenar em tarefas complexas
• Use quando os agentes estão fazendo trabalho duplicado ou conflitante
• Use quando você precisa de trilhas de auditoria mostrando quem fez o quê e quando
• Use quando a qualidade da saída do agente é inconsistente e precisa de portões de verificação

Como Funciona

Etapa 1: Definir a Identidade do Orquestrador

O orquestrador precisa saber o que ele É e o que ele NÃO É. Isso o impede de fazer trabalho em vez de delegar:

You are the Task Orchestrator. You NEVER do specialized work yourself.
You decompose tasks, delegate to the right agent, prevent conflicts,
and verify quality before marking anything done.

WHAT YOU ARE NOT:
- NOT a code writer — delegate to code agents
- NOT a researcher — delegate to research agents
- NOT a tester — delegate to test agents

Este padrão de "bloco-NÃO" reduz o desvio de tarefas em ~35% em produção.

Etapa 2: Construir um Registro de Tarefas

Antes de atribuir trabalho, verifique se alguém já está fazendo esta tarefa:

import sqlite3
from difflib import SequenceMatcher

def check_duplicate(description, threshold=0.55):
    conn = sqlite3.connect("task_registry.db")
    c = conn.cursor()
    c.execute("SELECT id, description, agent, status FROM tasks WHERE status IN ('pending', 'in_progress')")
    for row in c.fetchall():
        ratio = SequenceMatcher(None, description.lower(), row[1].lower()).ratio()
        if ratio >= threshold:
            return {"id": row[0], "description": row[1], "agent": row[2]}
    return None

Etapa 3: Encaminhar Tarefas para Especialistas

Use pontuação por palavras-chave para combinar tarefas com o melhor agente:

AGENTS = {
    "code-architect": ["code", "implement", "function", "bug", "fix", "refactor", "api"],
    "security-reviewer": ["security", "vulnerability", "audit", "cve", "injection"],
    "researcher": ["research", "compare", "analyze", "benchmark", "evaluate"],
    "doc-writer": ["document", "readme", "explain", "tutorial", "guide"],
    "test-engineer": ["test", "coverage", "unittest", "pytest", "spec"],
}

def route_task(description):
    scores = {}
    for agent, keywords in AGENTS.items():
        scores[agent] = sum(1 for kw in keywords if kw in description.lower())
    return max(scores, key=scores.get) if max(scores.values()) > 0 else "code-architect"

Etapa 4: Aplicar Portões de Qualidade

A saída do agente é uma AFIRMAÇÃO. A saída de teste é EVIDÊNCIA.

After agent reports completion:
1. Were files actually modified? (git diff --stat)
2. Do tests pass? (npm test / pytest)
3. Were secrets introduced? (grep for API keys, tokens)
4. Did the build succeed? (npm run build)
5. Were only intended files touched? (scope check)

Mark done ONLY after ALL checks pass.

Etapa 5: Executar Heartbeats de 30 Minutos

Every 30 minutes, ask:
1. "What have I DELEGATED in the last 30 minutes?"
2. If nothing → open the task backlog and assign the next task
3. Check for idle agents (no message in >30min on assigned task)
4. Relance idle agents or reassign their tasks

Exemplos

Exemplo 1: Delegando uma Tarefa de Código

[ORCHESTRATOR -> code-architect] TASK: Add rate limiting to /api/users
SCOPE: src/middleware/rate-limit.ts only
VERIFICATION: npm test -- --grep "rate-limit"
DEADLINE: 30 minutes

Exemplo 2: Lidando com um Duplicado

User asks: "Fix the login bug"
Registry check: Task #47 "Fix authentication bug" is IN_PROGRESS by security-reviewer
Decision: SKIP — similar task already assigned (78% match)
Action: Notify user of existing task, wait for completion

Melhores Práticas

• Sempre defina blocos-NÃO para cada agente (o que eles devem se recusar a fazer)
• Use SQLite para o registro de tarefas (leve, sem necessidade de servidor)
• Defina o limite de similaridade em 55% para anti-duplicação (menor = muitos falsos positivos)
• Exija portões de qualidade baseados em evidências (não apenas afirmações do agente)
• Registre cada delegação com: ID da tarefa, agente, escopo, prazo, comando de verificação

Armadilhas Comuns

• Problema: O orquestrador começa a fazer trabalho em vez de delegar Solução: Adicione blocos-NÃO explícitos e limites de função

…