Orquestracao Multi-Agent

O modo Multi-Agent transforma o /coder e o /agent em um sistema de orquestracao onde o LLM despacha agents especialistas em paralelo para resolver tarefas complexas de forma mais rapida e eficiente.

Ativacao

O modo multi-agent e ativado por padrao. Para desativa-lo, defina:

CHATCLI_AGENT_PARALLEL_MODE=false

Quando desativado, o /coder e o /agent funcionam exatamente como antes — sem nenhum impacto.

Arquitetura

User Query
    |
    v
AgentMode (ReAct loop existente)
    |
    v  (LLM responde com <agent_call> ou <tool_call> tags)
Dispatcher (fan-out via semaphore)
    |
    |-- FileAgent        |-- CoderAgent       |-- ShellAgent
    |-- GitAgent         |-- SearchAgent      |-- PlannerAgent
    |-- ReviewerAgent    |-- TesterAgent      |-- RefactorAgent
    |-- DiagnosticsAgent |-- FormatterAgent   |-- DepsAgent
    +-- CustomAgent(s)   (devops, security-auditor, etc.)
    |
    v
Results Aggregator -> Feedback para o LLM orquestrador

O LLM orquestrador recebe um catalogo de agents no system prompt e aprende a rotear tarefas usando tags <agent_call>:

<agent_call agent="file" task="Read all .go files in pkg/coder/engine/" />
<agent_call agent="coder" task="Add Close method to Engine struct" />
<agent_call agent="devops" task="Configure CI/CD pipeline with GitHub Actions" />

Multiplas tags agent_call na mesma resposta resultam em execucao paralela.

Dois Modos de Execucao

O orquestrador possui dois mecanismos de execucao, escolhendo o mais adequado por contexto:

Modo	Sintaxe	Quando Usar
agent_call	`<agent_call agent="..." task="..." />`	Novas fases de trabalho, tarefas paralelas, leitura exploratoria, refatoracao multi-arquivo
tool_call	`<tool_call name="@coder" args="..." />`	Fixes rapidos, diagnostico de erros, patches pontuais, validacao pos-agent. IMPORTANTE: multiplos tool_calls independentes devem ser emitidos em uma UNICA resposta

Guia de Decisao

Situacao	Modo
Ler multiplos arquivos + buscar referencias	`agent_call` (file + search em paralelo)
Corrigir um erro de compilacao	`tool_call` (patch direto)
Escrever novo modulo + testes	`agent_call` (coder + shell)
Verificar resultado de um agent	`tool_call` (read/exec rapido)
Fix apos falha de agent	`tool_call` (diagnostico preciso)
Retomar apos fix aplicado	`agent_call` (proxima fase)

Agents Especialistas Embarcados

FileAgent (Leitura e Analise)

Acesso: Somente leitura (read, tree, search)Skills:

batch-read — Script acelerador: le N arquivos em goroutines paralelas sem chamar o LLM
find-pattern — Busca padroes em arquivos
analyze-structure — Analisa estrutura de codigo
map-deps — Mapeia dependencias entre modulos

CoderAgent (Escrita e Modificacao)

Acesso: Leitura/Escrita (write, patch, read, tree)Skills:

write-file — Criacao de novos arquivos
patch-file — Modificacao precisa de codigo existente
create-module — Geracao de boilerplate
refactor — Renomeacao e refatoracao segura

ShellAgent (Execucao e Testes)

Acesso: Execucao (exec, test)Skills:

run-tests — Script acelerador: executa go test ./... -json e parseia resultados
build-check — Script acelerador: executa go build ./... && go vet ./...
lint-fix — Correcao automatica de lint

GitAgent (Controle de Versao)

Acesso: Git ops (git-status, git-diff, git-log, git-changed, git-branch, exec)Skills:

smart-commit — Script acelerador: coleta status + diff para commit inteligente
review-changes — Script acelerador: analisa alteracoes com changed + diff + log
create-branch — Criacao de branches

SearchAgent (Busca no Codebase)

Acesso: Somente leitura (search, tree, read)Skills:

find-usages — Encontra usos de simbolos
find-definition — Encontra definicoes
find-dead-code — Detecta codigo morto
map-project — Script acelerador: mapeia projeto em paralelo (tree + interfaces + structs + funcs)

PlannerAgent (Raciocinio Puro)

Acesso: Nenhum (sem tools — puro raciocinio LLM)Skills:

analyze-task — Analise de complexidade e riscos
create-plan — Criacao de plano de execucao
decompose — Decomposicao de tarefas complexas

ReviewerAgent (Revisao de Codigo e Qualidade)

Acesso: Somente leitura (read, search, tree)Skills:

review-file — Analisa arquivo para bugs, code smells, violacoes SOLID e issues de seguranca
diff-review — Script acelerador: revisa alteracoes staged via git-diff e git-changed
scan-lint — Script acelerador: executa go vet e staticcheck e categoriza issues

TesterAgent (Testes e Cobertura)

Acesso: Leitura/Escrita/Execucao (read, write, patch, exec, test, search, tree)Skills:

generate-tests — Geracao de testes abrangentes para funcoes e pacotes (LLM-driven)
run-coverage — Script acelerador: executa go test -coverprofile e parseia cobertura por funcao
find-untested — Script acelerador: encontra funcoes exportadas sem testes correspondentes
generate-table-test — Geracao de table-driven tests idiomaticos em Go

RefactorAgent (Transformacoes Estruturais)

Acesso: Leitura/Escrita (read, write, patch, search, tree)Skills:

rename-symbol — Script acelerador: renomeia simbolo em todos os .go, ignorando strings e comentarios
extract-interface — Extrai interface a partir dos metodos de um tipo concreto
move-function — Move funcao entre pacotes ajustando imports
inline-variable — Substitui variavel pelo seu valor em todos os pontos de uso

DiagnosticsAgent (Troubleshooting e Investigacao)

Acesso: Leitura/Execucao (read, search, tree, exec)Skills:

analyze-error — Parseia mensagens de erro e stack traces mapeando para localizacoes no codigo
check-deps — Script acelerador: executa go mod tidy, go mod verify e verifica saude das dependencias
bisect-bug — Guia investigacao para encontrar o commit que introduziu um bug
profile-bottleneck — Executa benchmarks ou pprof e analisa hotspots de performance

FormatterAgent (Formatacao e Estilo)

Acesso: Escrita/Execucao (read, patch, exec, tree)Skills:

format-code — Script acelerador: executa gofmt -w (ou goimports -w) nos arquivos Go
fix-imports — Script acelerador: executa goimports para organizar imports
normalize-style — Aplica convencoes de naming e estilo consistentes (LLM-driven)

DepsAgent (Gerenciamento de Dependencias)

Acesso: Leitura/Execucao (read, exec, search, tree)Skills:

audit-deps — Script acelerador: executa go mod verify e govulncheck para auditoria
update-deps — Script acelerador: lista dependencias desatualizadas com atualizacoes disponiveis (dry-run)
why-dep — Script acelerador: explica por que uma dependencia existe via go mod why e go mod graph
find-outdated — Encontra todas as dependencias com versoes mais novas disponiveis

Agents Customizados como Workers

Agents personas definidos em ~/.chatcli/agents/ sao automaticamente carregados como workers no sistema de orquestracao ao iniciar o /coder ou /agent. O LLM pode despacha-los via <agent_call> com o mesmo ReAct loop, leitura paralela e recuperacao de erros dos agents embarcados.

Como Funciona

Escaneamento

Ao iniciar o modo multi-agent, o sistema escaneia ~/.chatcli/agents/

Criacao do CustomAgent

Para cada agent encontrado, cria um CustomAgent que implementa a interface WorkerAgent

Mapeamento de Tools

O campo tools do frontmatter YAML define quais comandos o agent pode usar

Carregamento de Skills

Skills associadas sao carregadas e incluidas no system prompt do worker

Registro no Catalogo

O agent aparece no catalogo do orquestrador e pode ser despachado

Mapeamento de Tools

O campo tools do YAML frontmatter mapeia ferramentas estilo Claude Code para subcomandos do @coder:

Tool no YAML	Comando(s) @coder	Descricao
`Read`	`read`	Ler conteudo de arquivos
`Grep`	`search`	Buscar padroes em arquivos
`Glob`	`tree`	Listar diretorios
`Bash`	`exec`, `test`, `git-status`, `git-diff`, `git-log`, `git-changed`, `git-branch`	Execucao e operacoes git
`Write`	`write`	Criar/sobrescrever arquivos
`Edit`	`patch`	Edicao precisa (search/replace)

Exemplo de Agent Customizado

---
name: "security-auditor"
description: "Especialista em seguranca com foco em OWASP Top 10"
tools: Read, Grep, Glob
skills:
  - owasp-rules
  - compliance
---
# Personalidade Base

Voce e um Security Auditor especialista. Analise codigo buscando
vulnerabilidades OWASP Top 10, injection, XSS, e mas praticas.

Este agent sera somente leitura (apenas Read/Grep/Glob) e o LLM podera despacha-lo assim:

<agent_call agent="security-auditor" task="Audit the authentication module for OWASP vulnerabilities" />

Regras de Protecao

Os 12 nomes de agents embarcados (file, coder, shell, git, search, planner, reviewer, tester, refactor, diagnostics, formatter, deps) sao protegidos e nao podem ser sobrescritos por agents customizados.

Sem tools = read-only: Agents sem campo tools recebem automaticamente read, search, tree e sao marcados como read-only
Duplicatas ignoradas: Se dois agents tiverem o mesmo nome, apenas o primeiro e registrado

Skills: Scripts vs Descritivas

Cada agent possui dois tipos de skills:

Skills Executaveis (Scripts Aceleradores)
Skills Descritivas

Sequencias pre-definidas de comandos que bypassam o LLM para operacoes mecanicas e repetitivas, executando diretamente no engine:

batch-read   -> Le N arquivos em goroutines paralelas (sem LLM call)
run-tests    -> go test ./... -json | parse automatico
build-check  -> go build ./... && go vet ./...
smart-commit -> git status + git diff --cached -> resumo
map-project  -> tree + search interfaces/structs em paralelo

Informam o agent sobre suas capacidades — o agent resolve via seu mini ReAct loop com chamadas ao LLM:

refactor       -> Renomeacao segura com verificacao de referencias
find-dead-code -> Analise de codigo nao utilizado
create-plan    -> Plano estruturado de execucao

Skills V2 (Pacotes)

Skills V2 sao diretorios contendo:

SKILL.md — Conteudo principal com frontmatter
Subskills (.md) — Documentos de conhecimento adicional
scripts/ — Scripts executaveis registrados automaticamente no worker

skills/
+-- clean-code/
    |-- SKILL.md            # Conteudo principal
    |-- naming-rules.md     # Subskill: regras de nomenclatura
    |-- formatting.md       # Subskill: regras de formatacao
    +-- scripts/
        +-- lint_check.py   # Script executavel (registrado como skill)

O worker pode ler subskills com o comando read e executar scripts com exec durante sua operacao autonoma.

Estrategia de Recuperacao de Erros

Quando um agent_call falha, o orquestrador segue um protocolo de recuperacao inteligente:

Diagnostico via tool_call

Usa tool_call direto para ler arquivos relevantes e entender o erro (ja tem o contexto)

Fix via tool_call

Patches, correcoes de arquivo e retentativas sao mais rapidos e seguros via tool_call

Retoma via agent_call

Apos fix aplicado e verificado, retoma usando agent_call para a proxima fase

Regra chave: Recuperacao de erros = tool_call (rapido, preciso). Novas fases de trabalho = agent_call (paralelo, escalavel).

agent_call -> FALHA
    |
    v
tool_call: read (diagnosticar o erro)
    |
    v
tool_call: patch (aplicar fix)
    |
    v
tool_call: exec (verificar fix)
    |
    v
agent_call -> PROXIMA FASE (sucesso)

Configuracao

Variavel	Padrao	Descricao
`CHATCLI_AGENT_PARALLEL_MODE`	`true`	Ativa/desativa o modo multi-agent
`CHATCLI_AGENT_MAX_WORKERS`	`4`	Maximo de goroutines simultaneas
`CHATCLI_AGENT_WORKER_MAX_TURNS`	`10`	Maximo de turnos por worker
`CHATCLI_AGENT_WORKER_TIMEOUT`	`5m`	Timeout por worker

Exemplo de `.env`

# Multi-Agent (Orquestracao Paralela)
CHATCLI_AGENT_PARALLEL_MODE=true    # Desative com false se necessario
CHATCLI_AGENT_MAX_WORKERS=4
CHATCLI_AGENT_WORKER_MAX_TURNS=10
CHATCLI_AGENT_WORKER_TIMEOUT=5m

Seguranca Anti-Race

O sistema implementa multiplas camadas de protecao contra condicoes de corrida:

FileLockManager

Mutex per-filepath (caminhos absolutos normalizados). Operacoes de escrita adquirem lock; leituras nao bloqueiam.

Historico Isolado

Cada worker mantem seu proprio []models.Message, sem compartilhamento.

LLM Clients Independentes

Cada worker cria sua propria instancia de LLM client via factory pattern.

Engine Stateless

Cada worker instancia seu proprio engine.Engine fresh.

Context Tree

O contexto pai pode cancelar todos os workers via context.WithCancel.

Policy Enforcement

Workers respeitam integralmente o coder_policy.json (allow/deny/ask). Acoes com policy “ask” pausam o spinner e exibem um prompt de seguranca serializado para o usuario.

Governanca de Seguranca no Modo Paralelo

Os workers paralelos respeitam todas as regras do arquivo coder_policy.json (global e local). Isso significa que acoes como write, patch, exec passam pela mesma verificacao de policies que o modo sequencial.

Comportamento por Tipo de Regra

Regra	Comportamento no Worker
allow	Acao executada automaticamente, sem interrupcao
deny	Acao bloqueada silenciosamente; worker recebe erro `[BLOCKED BY POLICY]`
ask	Worker pausa, spinner e suspenso, e um prompt de seguranca e exibido ao usuario

Serializacao de Prompts

Quando multiplos workers precisam de aprovacao simultaneamente, os prompts sao serializados via mutex — apenas um prompt e exibido por vez. Apos a resposta do usuario, o proximo worker na fila recebe seu prompt. Isso evita:

Sobreposicao visual de prompts no terminal
Conflito de leitura no stdin
Spinner renderizando sobre o prompt de seguranca

Prompt com Contexto do Agent

O prompt de seguranca no modo paralelo exibe informacoes contextuais sobre qual agent esta solicitando a acao:

+========================================================+
|              SECURITY CHECK                             |
+========================================================+
 Agent:  coder
 Tarefa: Refatorar modulo de autenticacao
 --------------------------------------------------------
 Acao:   Escrever arquivo
         arquivo: pkg/auth/handler.go
 Regra:  nenhuma regra para '@coder write'
 --------------------------------------------------------
 Escolha:
   [y] Sim, executar (uma vez)
   [a] Permitir sempre (@coder write)
   [n] Nao, pular
   [d] Bloquear sempre (@coder write)

Isso permite que o usuario tome decisoes informadas sobre cada acao, sabendo exatamente qual agent esta pedindo e por que.

Respeito ao Provedor/Modelo em Runtime

Os workers paralelos utilizam sempre o provedor e modelo ativos no momento do despacho. Se o usuario trocar de provedor (ex.: de Anthropic para Google AI) via /switch, os proximos despachos de agents usarao o novo provedor corretamente.

Fluxo de Execucao (Exemplo)

Usuario envia a query

“refatore o modulo coder, separe read e write”

LLM orquestrador despacha agents paralelos

<agent_call agent="file" task="Read all .go files in pkg/coder/engine/" />
<agent_call agent="search" task="Find references to handleRead and handleWrite" />

Dispatcher cria goroutines

FileAgent e SearchAgent rodam em paralelo, cada um com seu LLM client e mini ReAct loop isolado (dentro do limite maxWorkers).

Resultados agregados

Feedback e enviado para o orquestrador.

Orquestrador despacha CoderAgent

Para a refatoracao (com FileLock nos arquivos sendo escritos).

Despacha ShellAgent para testes

Executa testes apos a escrita.

Recuperacao de erros (se necessario)

Se testes falharem, usa tool_call para diagnostico e fix rapido.

Validacao final

Orquestrador valida resultado final e reporta ao usuario.

Maximizacao de Paralelismo

O sistema de prompts do ChatCLI instrui explicitamente a IA a maximizar paralelismo em todos os niveis:

tool_call: Operacoes independentes (ler 3 arquivos, buscar + ler) devem ser emitidas em uma UNICA resposta, nao em turnos separados
agent_call: Para 3+ tarefas independentes, preferir agent_call que roda em goroutines paralelas
Per-turn anchor: A cada turno do ReAct loop, um lembrete rereforca a necessidade de paralelismo

Exemplo correto (3 leituras em UMA resposta):

<tool_call name="@coder" args='{"cmd":"read","args":{"file":"main.go"}}' />
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"config.go"}}' />
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"handler.go"}}' />

Exemplo incorreto (3 turnos para operacoes independentes):

Turn 1: read main.go → wait
Turn 2: read config.go → wait
Turn 3: read handler.go → wait

Compatibilidade

CHATCLI_AGENT_PARALLEL_MODE=false: tudo funciona exatamente como antes
Tags <tool_call> continuam funcionando mesmo com parallel mode ativo
Nenhuma assinatura de funcao existente foi alterada
O package cli/agent/workers/ e completamente isolado e nao impacta funcionalidades existentes

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Suporte

Orquestracao Multi-Agent

Ativacao

Arquitetura

Dois Modos de Execucao

Guia de Decisao

Agents Especialistas Embarcados

Agents Customizados como Workers

Como Funciona

Mapeamento de Tools

Exemplo de Agent Customizado

Regras de Protecao

Skills: Scripts vs Descritivas

Skills V2 (Pacotes)

Estrategia de Recuperacao de Erros

Configuracao

Exemplo de `.env`

Seguranca Anti-Race

FileLockManager

Historico Isolado

LLM Clients Independentes

Engine Stateless

Context Tree

Policy Enforcement

Governanca de Seguranca no Modo Paralelo

Comportamento por Tipo de Regra

Serializacao de Prompts

Prompt com Contexto do Agent

Respeito ao Provedor/Modelo em Runtime

Fluxo de Execucao (Exemplo)

Maximizacao de Paralelismo

Compatibilidade

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Suporte

​Ativacao

​Arquitetura

​Dois Modos de Execucao

​Guia de Decisao

​Agents Especialistas Embarcados

​Agents Customizados como Workers

​Como Funciona

​Mapeamento de Tools

​Exemplo de Agent Customizado

​Regras de Protecao

​Skills: Scripts vs Descritivas

​Skills V2 (Pacotes)

​Estrategia de Recuperacao de Erros

​Configuracao

​Exemplo de .env

​Seguranca Anti-Race

FileLockManager

Historico Isolado

LLM Clients Independentes

Engine Stateless

Context Tree

Policy Enforcement

​Governanca de Seguranca no Modo Paralelo

​Comportamento por Tipo de Regra

​Serializacao de Prompts

​Prompt com Contexto do Agent

​Respeito ao Provedor/Modelo em Runtime

​Fluxo de Execucao (Exemplo)

​Maximizacao de Paralelismo

​Compatibilidade

Ativacao

Arquitetura

Dois Modos de Execucao

Guia de Decisao

Agents Especialistas Embarcados

Agents Customizados como Workers

Como Funciona

Mapeamento de Tools

Exemplo de Agent Customizado

Regras de Protecao

Skills: Scripts vs Descritivas

Skills V2 (Pacotes)

Estrategia de Recuperacao de Erros

Configuracao

Exemplo de `.env`

Seguranca Anti-Race

Governanca de Seguranca no Modo Paralelo

Comportamento por Tipo de Regra

Serializacao de Prompts

Prompt com Contexto do Agent

Respeito ao Provedor/Modelo em Runtime

Fluxo de Execucao (Exemplo)

Maximizacao de Paralelismo

Compatibilidade