Workflows

Salve uma sequência de trabalho com vários agentes e reutilize-a em novas tarefas.

Um workflow diz ao Admiral quais agentes devem trabalhar, em que ordem, o que cada um recebe e como reunir os resultados. Salve essa sequência e reutilize-a em tarefas parecidas. Ele é diferente de um perfil de agente ou de um plano: coordena várias execuções, que você revisa antes de começarem.

Use um workflow integrado

O Clarvis inclui audit, implement e research. Selecione Admiral em /agent e peça o workflow pelo nome:

Use o workflow audit para revisar as alterações de autenticação. Explique o trabalho e o custo antes
de executá-lo.

Antes de iniciar qualquer líder, o Clarvis pede que você revise as rodadas, os agentes e o número de execuções paralelas. A aprovação inicia apenas a primeira rodada. Depois de cada rodada, o Admiral recebe um ponto de controle salvo e precisa decidir se continua ou para.

A sequência abaixo é uma execução real de release-review com um líder em um perfil de demonstração isolado. Ela usa o mesmo caminho de revisão e persistência dos workflows integrados.

Etapa 1 — selecione Admiral. O cabeçalho confirma que o líder atual carrega a capacidade de workflow.

Etapa 2 — revise antes da execução. Nenhum líder começa antes de você inspecionar rodada, perfil, quantidade de execuções paralelas e aprovar explicitamente.

Etapa 3 — monitore a árvore. A barra lateral mantém líder, estado, duração e iterações visíveis ao lado do resultado do gerenciador.

Atenção

A execução de um workflow sempre exige uma revisão interativa. O modo de impressão sem interface pode explicar um workflow, mas não pode aprová-lo e executá-lo.

Crie um workflow

Crie esta estrutura:

.clarvis/workflows/release-review/
├── WORKFLOW.md
└── briefs/
    └── inspect.md

Adicione .clarvis/workflows/release-review/WORKFLOW.md:

---
name: release-review
description: Revise um alvo de lançamento com um líder que coleta evidências.
args:
  - target
rounds:
  - id: inspect
    title: Revisar {{args.target}}
    type: free
    profile: explorer
    over: once
    brief: briefs/inspect.md
---

Resuma a revisão para uma pessoa. Comece pelos bloqueios, depois apresente os riscos e, por fim, as
evidências de que o alvo está pronto.

Adicione .clarvis/workflows/release-review/briefs/inspect.md:

Revise {{args.target}} para determinar se está pronto para lançamento.

Inspecione manifestos, notas de lançamento, documentação pública e as verificações que cobrem a
superfície alterada. Retorne bloqueios e riscos concretos com caminhos do repositório. Não modifique
o workspace.

O diretório do workflow e o name do frontmatter devem ser iguais. A primeira rodada deve usar over: once. Os caminhos de briefs são relativos ao diretório do workflow.

Execute seu workflow

Selecione Admiral e peça:

Use o workflow release-review para o alvo candidate. Explique seu custo antes de executá-lo.

Argumentos como target são obrigatórios quando declarados. /workflow permite navegar pelo histórico de execuções e pela árvore de agentes. Ele não é um editor nem um inicializador de definições de workflow. Enquanto uma sequência aguarda decisão, a tela de workflow e a seção Parallel work mostram awaiting_manager, a revisão do checkpoint e a próxima rodada proposta. Uma decisão obsoleta ou repetida não consegue iniciar a mesma rodada duas vezes.

Etapa 4 — reabra a execução. Use /workflow para inspecionar a árvore persistida do gerenciador aos líderes depois da conclusão.

Etapa 5 — inspecione as evidências. Abra um líder para ler o resultado armazenado completo e os totais de recursos, sem depender apenas da síntese.

Adicione mais rodadas

Cada rodada declara:

• um id exclusivo;
• um type: discovery, findings, verdict ou free;
• um profile de agente opcional;
• um seletor over;
• um title curto;
• um caminho relativo em brief.

Os seletores são intencionalmente simples:

• once executa um líder;
• each(scan.items) executa um líder por item;
• each(scan.items where needs_verification) filtra itens verdadeiros;
• each(scan.items where severity = high) filtra por valor;
• all(scan.items) envia toda a coleção a um líder.

Use fanout somente para cópias realmente independentes de uma rodada. Rodadas repetidas podem parar quando não houver novos resultados ou quando atingirem um limite de orçamento configurado.

Controle os recursos do workflow

Configurações opcionais valem para toda a árvore do workflow:

{
  "workflows": {
    "max_concurrency": 4,
    "max_total_leaders": 32,
    "budget_tokens": 640000000
  }
}

A concorrência padrão é 4, com máximo de 20. max_total_leaders usa 32 por padrão e limita os registros bem-sucedidos de líderes durante toda a vida do gerenciador; líderes concluídos não devolvem uma vaga. O orçamento de tokens auxiliares do workflow é 640000000 por padrão. Use null somente quando quiser deliberadamente remover o limite de tokens do workflow. Ele cobre os filhos em processo do gerenciador, todos os líderes e os subagentes dos líderes. O próprio gerenciador usa seu orçamento independente da execução principal e não consome esse orçamento compartilhado.

Como o orçamento é dividido

As chamadas de modelo ativas dividem o orçamento de tokens disponível. Um líder na fila de concorrência não reserva tokens, e a capacidade não usada volta quando uma chamada termina. Assim, os filhos do gerenciador, os líderes e seus subagentes podem aproveitar o orçamento restante.

Antes de iniciar uma rodada, o Clarvis verifica se o limite acumulado de líderes comporta a rodada inteira. Ele não inicia apenas parte de uma rodada acima do limite. Se os tokens acabarem, os líderes afetados e o workflow falham; confira todos os resultados em /workflow.

Workflows do workspace substituem por inteiro workflows globais ou integrados com o mesmo nome. Uma sobrescrita malformada é ignorada, mantendo disponível a definição válida de menor precedência.

Veja também

• Agentes
• Uso diário
• Escopos e confiança no workspace
• Solução de problemas