Workflows dinâmicos

Workflows dinâmicos orquestram vários subagentes a partir de um único script JavaScript aprovado pelo usuário. O script roda em fases, distribui subagentes em paralelo (iniciando vários de uma vez e esperando por todos), encaminha itens por estágios de processamento, valida saída estruturada contra JSON Schema (um formato padrão para descrever o formato esperado de dados JSON) e devolve um resultado final. Eles foram feitos para tarefas grandes e de vários passos — por exemplo, pesquisar uma questão em muitas fontes ou auditar um repositório inteiro — que de outro modo tomariam muitos turnos manuais.

Workflows dinâmicos consomem bem mais tokens que uma sessão normal. Use-os apenas quando você realmente precisa desse tipo de orquestração.

Nota

Um script de workflow roda em um sandbox (um ambiente isolado que restringe o que o script pode acessar), mas o sandbox é uma fronteira de controle, não uma barreira de segurança. Por isso, no modo de permissão manual, toda execução de workflow exige sua aprovação explícita antes de qualquer coisa executar; nos modos yolo e auto, as execuções são aprovadas automaticamente.

Usando workflows dinâmicos

O agente principal tem a ferramenta Workflow e entra no modo Dynamic Workflow automaticamente em tarefas grandes de várias fases (veja Modo Dynamic Workflow); perfis de subagente como coder e explore nunca incluem a ferramenta, então tarefas delegadas não podem aninhar execuções de workflow.

Para usar um, coloque um script em um diretório de workflow e execute-o com /workflow run <name>, ou peça ao Jarvis Code em linguagem natural para criá-lo ou executá-lo. Use /workflow on para que o agente proponha um workflow em uma tarefa grande mesmo quando ele não entraria sozinho, e /workflow off para desabilitar o modo.

Escrevendo um script de workflow

Um workflow é um arquivo .js. Sua primeira instrução exporta um objeto meta descrevendo o workflow; o resto do arquivo é um corpo assíncrono de nível superior que conduz a orquestração:

export const meta = {
  name: 'repo-audit',
  description: 'Revisa áreas do repositório em paralelo e resume os achados',
  whenToUse: 'Quando o usuário pede uma auditoria ampla do repositório',
  phases: [
    { title: 'Review', detail: 'Distribui um revisor por área' },
    { title: 'Summarize' },
  ],
};

phase('Review');
const reports = await parallel([
  () => agent('Revise src/auth em busca de problemas de segurança', { label: 'auth' }),
  () => agent('Revise src/api em busca de problemas de segurança', { label: 'api' }),
]);

phase('Summarize');
return await agent(`Resuma estes relatórios de auditoria: ${JSON.stringify(reports)}`);

O meta.name é obrigatório, precisa estar em kebab-case e precisa coincidir com o nome do arquivo (sem a extensão .js). O meta.description diz ao modelo o que o workflow faz, o meta.whenToUse opcional descreve quando recorrer a ele, o meta.argumentHint opcional sugere os argumentos esperados no popup de autocompletar, e o meta.phases declara a lista de fases exibida no diálogo de confirmação e no navegador de execuções.

A API do sandbox

O corpo do script orquestra subagentes por um pequeno conjunto de globais:

• args: a string de argumentos passada na invocação, por exemplo o <question> em /workflow run deep-research <question>
• phase(title): marca a fase atual; o título deve vir de meta.phases
• log(message): acrescenta uma mensagem ao log da execução
• agent(prompt, { label?, phase?, schema? }): executa um subagente com o prompt informado. O subagente passa pelo sistema normal de permissões, então suas chamadas de ferramenta são aprovadas do mesmo jeito que em uma sessão comum. Com um schema (um JSON Schema), o subagente devolve um objeto validado em vez de texto livre. Se você recusar o pedido de aprovação do subagente, agent() devolve null; em caso de falha, ele lança
• parallel(fns): executa as funções informadas concorrentemente e espera todos os resultados
• pipeline(items, ...stages): passa cada item pelos estágios em ordem. Os itens fluem de forma independente — não há barreira entre estágios — e um estágio que devolve null pula os estágios restantes daquele item
• return <value>: encerra o workflow com um resultado final; o valor precisa ser serializável em JSON

O sandbox não tem APIs do Node.js: nada de process, require, fs, acesso à rede ou temporizadores. Recursos padrão do JavaScript como URL, URLSearchParams, TextEncoder, TextDecoder, JSON e Math estão disponíveis.

Locais de workflow

O Jarvis Code CLI varre diretórios de workflow em quatro escopos; escopos mais específicos têm prioridade maior: Projeto > Usuário > Extra > Embutido. Dentro de um escopo, o diretório específico do Jarvis Code vence o genérico.

Nível de projeto (raiz do projeto = o diretório mais próximo que contém .git, subindo a partir do diretório de trabalho):

• .jarvis-code/workflows/
• .agents/workflows/

Nível de usuário (vale para todos os projetos):

• $JARVIS_CODE_HOME/workflows/ (padrão: ~/.jarvis-code/workflows/)
• ~/.agents/workflows/

O diretório de workflows de usuário específico do Jarvis Code acompanha JARVIS_CODE_HOME, então raízes de dados isoladas também têm workflows isolados. O diretório genérico ~/.agents/workflows/ permanece no home real do sistema operacional, para ser compartilhado entre ferramentas.

Diretórios extras: declarados por extra_workflow_dirs dentro de [workflows] no config.toml:

[workflows]
extra_workflow_dirs = ["~/team-workflows"]

Workflows embutidos são distribuídos com o CLI e têm a prioridade mais baixa; veja Workflow embutido deep-research.

Um arquivo de workflow com conteúdo inválido — por exemplo um bloco meta ausente ou malformado — é ignorado com um aviso que informa o motivo, e não afeta os demais workflows.

Executando um workflow

Jarvis Code CLI (TUI)

O comando de barra /workflow (alias /workflows) gerencia workflows a partir da TUI:

Comando	Descrição
/workflow list	Lista todos os workflows descobertos
/workflow run <name> [args]	Executa um workflow pelo nome, passando args ao script
/workflow runs	Abre o navegador de execuções (veja Acompanhar execuções)
/workflow show <name>	Mostra os metadados e o script de um workflow
/workflow cancel <runId>	Cancela um workflow em execução
/workflow save <runId> [--user]	Salva o script de uma execução para reúso (veja Salvar um workflow para reúso)
/workflow reload	Reexamina os diretórios de workflow
/workflow on	Habilita o modo Dynamic Workflow (veja abaixo)
/workflow off	Desabilita o modo Dynamic Workflow

Quando você digita /workflow run , o popup de autocompletar lista os workflows disponíveis com suas dicas de argumento, para você encontrar rapidamente o que precisa. O /workflow sem argumentos abre o navegador de execuções diretamente.

Você também pode simplesmente pedir ao Jarvis Code em linguagem natural para criar ou executar um workflow — por exemplo, "pesquise com um workflow como o nosso fluxo de auth trata a renovação de token". O modelo então propõe a execução pela ferramenta Workflow. O que acontece em seguida depende do modo de permissão: no modo manual, nada executa antes de você aprovar; nos modos yolo e auto, a execução é aprovada automaticamente.

A aprovação depende de como a execução começou. Execuções que você mesmo inicia com /workflow run começam imediatamente — o comando em si é a sua confirmação. Execuções propostas pelo modelo pela ferramenta Workflow seguem o modo de permissão: no modo manual, a execução passa por uma revisão de aprovação antes de qualquer coisa executar — o diálogo mostra os metadados, as fases e o script completo do workflow, os limites resolvidos e um aviso de consumo de tokens, e você pode aprovar ou recusar; nos modos yolo e auto, a ferramenta Workflow é aprovada automaticamente e a execução começa sem diálogo.

Outros clientes

A descoberta, a execução e o cancelamento de workflows são expostos pela API do servidor local, então um cliente de terceiros pode conduzir as mesmas operações. Execuções iniciadas por qualquer cliente são visíveis a partir de todos os outros, porque compartilham o mesmo estado de backend. Veja Servidor local e API.

Acompanhar execuções

Execuções de workflow rodam em segundo plano e nunca bloqueiam sua sessão. O /workflow runs abre o navegador de execuções, que lista cada execução com seu status, a fase atual (N/M), o número de chamadas de agente feitas até então e a saída de log, além do resultado final ou do erro quando a execução termina. Atalhos de teclado no navegador permitem cancelar uma execução, salvar seu script ou visualizá-lo.

Eventos de início e conclusão de workflow também aparecem diretamente na conversa, e cada execução surge em /tasks como uma tarefa em segundo plano do tipo workflow, junto com os demais trabalhos em segundo plano. O navegador de tarefas mostra o nome do workflow, o progresso da fase atual e a contagem de chamadas de agente das tarefas de workflow.

Modo Dynamic Workflow

O modo Dynamic Workflow instrui o modelo a analisar a tarefa primeiro e, em tarefas grandes ou de várias fases, propor um script de workflow dinâmico (pela ferramenta Workflow) em vez de executar diretamente. O modo entra automaticamente em requisições grandes e de várias fases — o agente principal entra por conta própria quando um prompt é longo o bastante e apresenta pelo menos dois tipos de sinais de vários passos (listas de tarefas, palavras de sequenciamento, substantivos de fase ou marco, contagens explícitas de passos ou verbos de tarefa) — ou manualmente por /workflow on. O /workflow off o desabilita a qualquer momento.

Um rótulo Dynamic Workflow no rodapé do terminal indica que o modo está ativo.

O modo Dynamic Workflow se combina com todos os modos existentes:

• Plan mode: durante o planejamento, o agente lê a base de código e escreve um plano; ao sair do Plan mode, o agente pode converter o plano aprovado em um script de workflow.
• Modo swarm: o swarm distribui subagentes independentes; o modo de workflow orquestra fases sequenciadas. São independentes e podem estar ativos juntos.
• Modo de metas: a meta conduz turnos autônomos; dentro de um turno o agente pode criar um workflow, que então roda em segundo plano enquanto a meta continua.
• Permissão: no modo manual, toda execução de workflow proposta pelo modelo passa pela revisão de aprovação (workflow-run-review-ask) — o único diálogo de uma execução — mostrando metadados, fases, script e limites; nos modos yolo e auto, a política aprova a ferramenta Workflow e as execuções começam sem diálogo, na mesma semântica de metas e swarm.

Salvar um workflow para reúso

Quando o script de uma execução se mostra útil — inclusive um que o modelo escreveu ad hoc a partir de um pedido em linguagem natural — salve-o enquanto a execução está ativa ou depois que ela termina:

/workflow save <runId>          # salva no projeto (.jarvis-code/workflows/)
/workflow save <runId> --user   # salva no seu diretório de usuário (~/.jarvis-code/workflows/)

Um workflow salvo vira um workflow descoberto comum e pode ser executado pelo nome com /workflow run <name> [args].

Workflow embutido deep-research

O Jarvis Code CLI traz um workflow embutido predefinido, deep-research: pesquisa profunda em múltiplas fontes com verificação adversarial. Ele trabalha em cinco fases — Scope, Search, Fetch, Verify e Synthesize — e faz verificação cruzada do que encontra antes de escrever o relatório final.

/workflow run deep-research Como nosso serviço de billing trata proporcionalidade?

Configuração

A seção [workflows] do config.toml ajusta os limites de execução e declara diretórios extras de workflow:

Campo	Tipo	Padrão	Descrição
max_concurrency	integer	4	Número máximo de subagentes que um workflow executa concorrentemente (1–16)
max_agent_calls	integer	50	Número máximo de chamadas de agent() que uma execução pode fazer
max_duration_ms	integer	1800000 (30 minutos)	Tempo máximo de relógio (milissegundos) de uma execução
max_script_bytes	integer	262144 (256 KB)	Tamanho máximo em bytes de um script de workflow; arquivos maiores são ignorados na descoberta
extra_workflow_dirs	array<string>	—	Diretórios adicionais de workflow, varridos no escopo extra

Veja Arquivos de configuração — workflows para a referência completa de campos.

Comportamento em falhas

Workflows nunca reportam sucesso falso. Um subagente que falha lança para fora de agent(), um pedido de aprovação recusado volta como null para o script poder se abster explicitamente, e cancelar uma execução a encerra como cancelada, não como concluída. Se uma execução termina antes — por erro, por limite ou por cancelamento — o navegador de execuções reporta o resultado parcial junto com o motivo.

Limitações atuais

• O formato do script e os subcomandos de /workflow podem mudar entre releases.
• Somente scripts .js no formato documentado nesta página são suportados; scripts de workflow não são compatíveis com o Claude Code.
• Pedidos em linguagem natural sempre produzem primeiro uma proposta — no modo manual o modelo nunca executa um workflow sem sua aprovação; nos modos yolo e auto as execuções são aprovadas automaticamente.

Próximos passos

• Agentes e subagentes — como os subagentes funcionam e como personalizá-los
• Agent Skills — uma forma mais leve de empacotar instruções reutilizáveis
• Arquivos de configuração — referência completa de campos de [workflows]
• Comandos de barra — referência dos subcomandos de /workflow