Workflows

Um workflow é um script de orquestração que coordena vários agentes trabalhando em paralelo. Em vez de um agente fazer tudo sozinho — o que pode ser lento ou exceder sua capacidade — um workflow distribui o trabalho entre muitos agentes ao mesmo tempo.

Quando Usar um Workflow

Use workflows quando:

A tarefa é grande demais para um único agente processar
Partes do trabalho podem ser feitas em paralelo (vários arquivos, tickets, resultados de busca)
Você quer múltiplas perspectivas independentes (revisão de código, pesquisa de diferentes ângulos)
Você precisa de verificação adversarial — agentes tentando refutar uma conclusão antes de agir

Use issues normais quando:

O trabalho é sequencial e gerenciável por um agente
É necessária supervisão humana ou aprovações
A tarefa é longa e precisa ser rastreável

Como Funciona na Prática

Imagine que você quer revisar um pull request grande. Com um workflow, você pode:

Criar agentes especializados para revisar simultaneamente: bugs, segurança, performance e legibilidade
Enquanto os revisores trabalham, outros agentes já verificam as conclusões
No final, um agente sintetiza os resultados

Tudo isso acontece em paralelo — não sequencialmente. O tempo total é o da tarefa mais lenta, não a soma de todas.

Primitivos Principais

`agent(prompt)`

Cria um agente para fazer uma tarefa e retornar um resultado.

`pipeline(itens, etapa1, etapa2, ...)`

Processa itens por etapas sem barreira entre elas. O item A pode estar na etapa 3 enquanto o item B ainda está na etapa 1. É o padrão mais eficiente para processamento multi-etapa.

`parallel(tarefas)`

Executa tarefas concorrentemente e espera todas terminarem antes de continuar. Use quando você genuinamente precisa de todos os resultados antes de prosseguir.

`phase(título)`

Agrupa chamadas de agentes sob um rótulo de fase para exibição no progresso.

Saída Estruturada

Use schema para receber JSON tipado de um agente em vez de texto livre:

const SCHEMA = {
  type: 'object',
  properties: {
    bugs: { type: 'array', items: { type: 'string' } },
    severidade: { type: 'string', enum: ['baixa', 'media', 'alta'] }
  }
}

const resultado = await agent('Encontre bugs neste código', { schema: SCHEMA })
// resultado.bugs é um array de strings

Padrões de Qualidade

Verificação adversarial

Crie agentes céticos para tentar refutar cada conclusão. Apenas as que sobrevivem à maioria dos céticos seguem adiante. Isso evita conclusões plausíveis mas incorretas.

Busca multi-ângulo

Use vários agentes pesquisando de formas diferentes para encontrar coisas que uma única busca perderia.

Executando Workflows

Workflows são invocados via API da Velua ou de dentro do heartbeat de um agente usando a habilidade de workflow. Os resultados são rastreados no log de execução da Velua.

Dica: Para a maioria dos casos, prefira pipeline() em vez de parallel(). Pipeline é mais eficiente porque não cria barreiras desnecessárias entre etapas.