Skip to main content
A camada Agent Squad transforma a Orquestração Multi-Agent em um time de verdade. Você dá um prompt; o orquestrador planeja o trabalho em cards, despacha workers especialistas, acompanha onde cada um está, devolve o feedback de review para o coder, agenda continuações e só entrega depois de validar — sem você precisar ser babá de nada. São quatro peças, cada uma utilizável sozinha:

​
Quando o squad ativa?

Não existe um “botão de squad” no código — o orquestrador decide por turno, guiado por uma escada de decisão ensinada no system prompt dele (sempre presente no /coder e no /agent, já que o modo multi-agent é ligado por padrão). Conhecer a escada evita a confusão clássica de “pedi algo e nenhum card apareceu”: Existem também dois gatilhos determinísticos: tarefas de alta complexidade disparam o Plan-and-Solve antes do loop (um plano estruturado naturalmente vira cards), e qualquer [SQUAD MAIL] na inbox é injetado no boundary do turno com instrução de reagir antes de continuar.
Você sempre pode forçar: /plan <objetivo> planeja primeiro, e uma instrução explícita no prompt — “crie cards no board e me entregue revisado” — vence a heurística. O meio-termo é julgamento do modelo por design: o playbook dá uma régua, não um if/else rígido.

​
Registry de runs — onde está cada agent?

Toda execução de agent se registra num registry process-wide: o loop do orquestrador, cada worker despachado, subagents delegados, membros do painel Mixture-of-Agents e runs headless do scheduler. Os runs formam uma árvore pai → filho, e cada um reporta seu turno ReAct atual e a ação em andamento. O painel de dispatch ao vivo usa o registry para mostrar progresso real por agent:

​
/agents

​
@agents (para a IA)

O orquestrador usa o mesmo registry através da tool @agents (list, show, cancel) — assim verifica o que já está rodando antes de despachar trabalho duplicado e mata um worker que esteja em loop sem progresso. O cancelamento é por run: cancela o contexto daquele run e tudo que ele criou, nunca o lote inteiro.

​
Board de trabalho — o kanban do time

O board é a unidade de trabalho compartilhada: cards fluindo por backlog → doing → review → blocked → done. Um card carrega assignee (tipo de worker agent), notas com timestamp (veredictos de review, resumos de entrega), IDs de runs e de jobs do scheduler vinculados, e todo o histórico de transições.
A IA gerencia o mesmo board via @board (create, list, show, move, assign, note, link, archive). Os resultados dos agents incluem o run_id, então o orquestrador vincula cada execução ao seu card para rastreabilidade. A persistência é um documento JSON único escrito atomicamente em ~/.chatcli/board.json (sobrescreva com CHATCLI_BOARD_PATH). Arquivo corrompido gera erro — nunca é apagado silenciosamente.

​
Squad mail — agents conversando entre si

O squad mail é um bus de mensagens direcionadas entre agents. As mensagens são injetadas no contexto do destinatário no próximo boundary de turno — o único ponto que não quebra um tool call nativo e seu resultado.
  • Workers ganham a tool nativa universal send_mail (independente do allowlist de comandos): um reviewer entrega o veredicto direto ao coder em pleno voo.
  • O orquestrador drena a própria inbox a cada turno (entregue como blocos [SQUAD MAIL]) e usa @mail (send, inbox, history).
  • Você pode redirecionar qualquer agent sem interrompê-lo:

​
Durável e cross-process

O squad mail é persistido no store SQLite do Conversation Hub (modo WAL): mensagens sobrevivem a restarts e fluem entre processos. Uma diretiva digitada no seu REPL alcança agents rodando dentro do daemon do Chat Gateway, e vice-versa. Acks de entrega impedem que outros processos (e a hidratação pós-restart) reentreguem mensagens já consumidas.

​
O playbook de entrega

Com observabilidade, board e mensageria no lugar, o system prompt do orquestrador ensina o ciclo autônomo completo:
  1. Plan — quebra o objetivo em cards (@board create, um por entregável, assignee = tipo de agent).
  2. Develop — move o card para doing, despacha os workers designados, vincula o run_id.
  3. Review — move para review, despacha reviewer/tester, registra o veredicto como nota do card. Review reprovado → os achados voltam para o coder (novo dispatch ou @mail send coder), o card volta para doing.
  4. Deliver — valida de verdade (build + testes, red → green) e move para done com nota de entrega.
  5. Loop — repete até nenhum card ficar fora de done. Trabalho contínuo ou adiado é agendado via @scheduler com o job vinculado ao card.
O orquestrador é instruído a nunca terminar um run com cards inacabados, exceto em blocked com nota explicando o bloqueio.

​
Telemetria estruturada no gateway

Quando o squad roda dentro do Chat Gateway (Telegram, Slack, …), o progresso é emitido a partir de eventos tipados do agent em vez de raspar a saída do terminal: linhas de raciocínio, início/fim de tool com duração, contadores de plano e uma linha por mudança de estado de worker (turno e ação atuais, depois status terminal).
O caminho legado de scraping continua disponível com CHATCLI_GATEWAY_STRUCTURED_PROGRESS=false.

​
Configuração

Todas aparecem em /config agent e /config gateway.
As tools do squad são expostas à LLM tanto no catálogo de tools do prompt quanto como definições nativas de function calling (agents_runs, board_cards, squad_mail), então a orquestração funciona em qualquer provider.