Orquestre subagentos em escala com fluxos de trabalho dinâmicos

Fluxos de trabalho dinâmicos estão disponíveis em todos os planos pagos, com acesso à API Anthropic, e no Amazon Bedrock, Google Cloud’s Agent Platform e Microsoft Foundry. No Pro, ative-os na linha Dynamic workflows em /config.

Um fluxo de trabalho dinâmico é um script JavaScript que orquestra muitos subagentos de uma vez. Claude escreve o script para a tarefa que você descreve, e um runtime o executa em segundo plano enquanto sua sessão permanece responsiva. Recorra a um fluxo de trabalho quando uma tarefa precisar de mais agentes do que uma conversa pode coordenar, ou quando você quiser que a orquestração seja codificada como um script que você possa ler e executar novamente. Os exemplos incluem uma varredura de bugs em toda a base de código, uma migração de 500 arquivos, uma pergunta de pesquisa que precisa ter fontes verificadas cruzadamente uma contra a outra, e um plano difícil que vale a pena ser elaborado de vários ângulos independentes antes de você se comprometer com um.

Quando usar um fluxo de trabalho

Subagentos, skills, equipes de agentes e fluxos de trabalho podem todos executar uma tarefa com várias etapas. A diferença é quem mantém o plano:

	Subagentos	Skills	Equipes de agentes	Fluxos de trabalho
O que é	Um worker Claude que spawna	Instruções que Claude segue	Um agente líder supervisionando sessões entre pares	Um script que o runtime executa
Quem decide o que é executado a seguir	Claude, turno por turno	Claude, seguindo o prompt	O agente líder, turno por turno	O script
Onde os resultados intermediários vivem	Janela de contexto de Claude	Janela de contexto de Claude	Uma lista de tarefas compartilhada	Variáveis de script
O que é repetível	A definição do worker	As instruções	A definição da equipe	A orquestração em si
Escala	Algumas tarefas delegadas por turno	Igual aos subagentos	Um punhado de pares de longa duração	Dezenas a centenas de agentes por execução
Interrupção	Reinicia o turno	Reinicia o turno	Os companheiros de equipe continuam executando	Retomável na mesma sessão

Um fluxo de trabalho move o plano para o código. Com subagentos, skills e equipes de agentes, Claude é o orquestrador: ele decide turno por turno o que spawnar ou atribuir a seguir, e cada resultado chega à janela de contexto. Um script de fluxo de trabalho mantém o loop, a ramificação e os resultados intermediários em si, então o contexto de Claude contém apenas a resposta final. Mover o plano para o código também permite que um fluxo de trabalho aplique um padrão de qualidade repetível, não apenas execute mais agentes: ele pode ter agentes independentes revisando adversarialmente as descobertas um do outro antes de serem relatadas, ou elaborar um plano de vários ângulos e pesá-los um contra o outro, para que você obtenha um resultado mais confiável do que uma única passagem.

Executar um workflow agrupado

A forma mais rápida de ver um workflow em ação é executar /deep-research, o workflow integrado que Claude Code inclui para investigar uma pergunta em muitas fontes. Você verá agentes trabalhando através de um conjunto de fases em segundo plano enquanto sua sessão permanece livre, e obterá um relatório no final em vez de uma transcrição turno a turno.

Executar o workflow

Execute /deep-research com uma pergunta que você deseja investigar. Ele distribui buscas na web em vários ângulos, busca e verifica cruzadamente as fontes que encontra, e sintetiza um relatório citado.

/deep-research What changed in the Node.js permission model between v20 and v22?

Permitir workflows

Claude Code pergunta se deve permitir o workflow. Selecione Sim para continuar. O prompt exato depende do seu modo de permissão. Consulte Aprovar o plano antes de ser executado para as opções por modo.

Acompanhar o progresso

A execução começa em segundo plano. Execute /workflows para abrir sua visualização de progresso:

/workflows

Se /workflows mostrar uma lista de execuções, selecione a execução que você acabou de iniciar e pressione Enter. A visualização mostra cada fase com sua contagem de agentes. Aprofunde-se em qualquer fase para ver seus agentes e o que cada um encontrou. Consulte Acompanhar a execução para o conjunto completo de controles.Você também pode acompanhar a partir do painel de tarefas abaixo da caixa de entrada: um resumo de progresso de uma linha aparece lá enquanto a execução está em andamento. Pressione a seta para baixo para focá-lo e depois Enter para expandir.

Ler o relatório

Quando a execução termina, o relatório chega em sua sessão. Ele cita as fontes de cada afirmação, com afirmações que não sobreviveram à verificação cruzada já filtradas.Quando os agentes verificadores não conseguem verificar uma afirmação, como após um limite de taxa ou erro de API, o relatório lista essa afirmação como não verificada em vez de contá-la como refutada.

Para executar um workflow para sua própria tarefa, peça a Claude para escrever um, e uma vez que uma execução faça o que você desejava, você pode salvá-lo como um comando seu.

Workflows agrupados

Claude Code inclui /deep-research como um workflow integrado:

Comando	O que faz
`/deep-research <question>`	Distribui buscas na web em uma pergunta em vários ângulos, busca e verifica cruzadamente as fontes que encontra, vota em cada afirmação e retorna um relatório citado com afirmações que não sobreviveram à verificação cruzada filtradas. Requer que a ferramenta WebSearch esteja disponível

/deep-research é executado apenas quando você o invoca. Workflows que você salva você mesmo se tornam comandos da mesma forma e aparecem na autocompletar / junto com os agrupados.

Acompanhar a execução

Workflows são executados em segundo plano, portanto a sessão permanece responsiva enquanto os agentes trabalham. Execute /workflows a qualquer momento para listar workflows em execução e concluídos, depois selecione um para abrir sua visualização de progresso. Quando a sessão tem apenas uma execução, /workflows pula a lista e abre essa execução. Para parar um workflow em execução a partir da lista sem abri-lo, selecione-o e pressione x. A visualização de progresso mostra cada fase com suas contagens de agentes. O rodapé lista a chave para cada ação:

Chave	Ação
`↑` / `↓`	Selecionar uma fase ou agente
`Enter` ou `→`	Aprofundar-se na fase selecionada e depois no detalhe de um agente. No detalhe, `Enter` expande ou recolhe
`Esc` ou `←`	Voltar um nível
`j` / `k`	Rolar dentro do detalhe do agente quando ele transborda
`f`	Filtrar a lista de agentes na fase selecionada por status. Pressione novamente para ciclar
`p`	Pausar ou retomar a execução
`x`	Parar o agente selecionado ou parar todo o workflow quando o foco está na execução
`r`	Reiniciar o agente em execução selecionado
`s`	Salvar o script da execução como um comando

O detalhe do agente lista o prompt do agente, suas chamadas de ferramentas recentes e seu resultado. Cada chamada mostra seu estado, como ainda em execução ou falha. Quando o agente mantém uma lista de tarefas própria, o detalhe a mostra também, com o status de cada tarefa. Pressione Enter para expandir o detalhe. O prompt e o resultado então aparecem em sua totalidade, e cada chamada listada mostra sua entrada e o início de seu resultado.

Peça ao Claude para escrever um workflow

Você pode pedir ao Claude para escrever um workflow para sua tarefa de duas formas:

Peça um workflow no seu prompt, com suas próprias palavras ou incluindo a palavra-chave ultracode, e o Claude escreve um para a tarefa.
Deixe o Claude decidir com ultracode: defina /effort ultracode e o Claude planeja um workflow para cada tarefa substancial na sessão.

Você também pode executar um comando de workflow que já existe: um workflow incluído como /deep-research, ou um que você tenha salvo.

Peça um workflow no seu prompt

Para executar uma única tarefa como workflow sem alterar o nível de esforço da sessão, inclua a palavra-chave ultracode no seu prompt. Pedir com suas próprias palavras, por exemplo “use a workflow” ou “run a workflow”, também funciona: o Claude trata uma solicitação direta como a mesma adesão.

ultracode: audit every API endpoint under src/routes/ for missing auth checks

O Claude Code destaca a palavra-chave na sua entrada e o Claude escreve um script de workflow para a tarefa em vez de trabalhar nela turno a turno. A palavra-chave apenas escolhe como o Claude estrutura o trabalho: as chamadas de ferramenta dos agentes recebem as mesmas verificações de permissão e o mesmo sandboxing que qualquer outra chamada de ferramenta na sessão. Se a execução fizer o que você queria, você pode salvá-la como um comando depois. Se você já tem um orquestrador construído de outra forma, como uma pasta de prompts de subagentes ou uma skill que distribui o trabalho, você pode apontar o Claude para ele e pedir um workflow que faça a mesma coisa.

Descartar ou desativar a palavra-chave

Se você não pretendia iniciar um workflow, pressione Option+W no macOS ou Alt+W no Windows e Linux para descartar o destaque neste prompt, ou pressione backspace enquanto o cursor estiver logo após a palavra-chave destacada. Para impedir que a palavra-chave seja acionada, desative Ultracode keyword trigger em /config.

Onde a palavra-chave funciona

A palavra-chave é uma adesão apenas em um prompt que você mesmo digita: no prompt interativo, em um painel de extensão de IDE, em um cliente de Remote Control ou em um aplicativo do Agent SDK que marca a origin da sua entrada de teclado como { kind: "human" }. Ela não inicia um workflow quando chega à sessão de outra forma:

um prompt passado com -p
um prompt que um aplicativo do Agent SDK envia sem marcá-lo como entrada humana
um prompt de tarefa agendada
um payload de webhook ou comentário de pull request retransmitido para a conversa

Deixe o Claude decidir com ultracode

Ultracode é uma configuração do Claude Code que ativa a orquestração automática de workflows para a sessão, em qualquer nível de esforço em que a sessão seja executada. Com ela ativada, o Claude planeja um workflow para cada tarefa substancial em vez de esperar que você peça. Ative-a no prompt do Claude Code:

/effort ultracode

Para iniciar uma sessão com ultracode já ativado, inicie com claude --effort ultracode, o que também define o nível de esforço como xhigh. Para ativá-lo pelo controle deslizante de /effort, pressione Tab para alternar o botão Ultracode e depois Enter para aplicá-lo. Ajustar o nível de esforço lista as formas de ativar o ultracode. Com o ultracode ativado, o Claude decide quando uma tarefa justifica um workflow. Uma única solicitação pode se transformar em vários workflows seguidos: um para entender o código, um para fazer a alteração e um para verificá-la. Isso se aplica a todas as tarefas na sessão, então cada solicitação usa mais tokens e leva mais tempo do que a mesma solicitação sem um workflow. Em um plano de assinatura, esses tokens consomem seus limites de uso, então uma sessão com ultracode ativado atinge um limite de sessão ou semanal antes do que o mesmo trabalho com ele desativado. Ativar o ultracode já significa aderir a execuções grandes, então estas verificações não se aplicam enquanto ele estiver ativado:

O aviso Large workflow não aparece em uma execução de workflow
O limite de subagentes simultâneos da sessão não é aplicado aos subagentes que o Claude cria com a ferramenta Agent
No modo de permissão auto, não é solicitado que você aprove o primeiro lançamento de workflow

/effort ultracode dura pela sessão atual; para que toda sessão comece com ele, defina a configuração ultracode. Desative-o com /effort ultracode off quando voltar ao trabalho rotineiro. O controle deslizante de /effort oferece o botão apenas quando o ultracode está disponível. Antes da v2.1.284, /effort ultracode definia a sessão como xhigh, e /effort ultracode off falhava com Invalid argument.

Aprove o plano antes que ele seja executado

Na CLI, o prompt por execução mostra as fases planejadas e estas opções:

Yes, run it: inicia a execução
Yes, and don’t ask again for <name> in <path>: inicia e pula este prompt para este workflow neste projeto daqui em diante. O Claude Code oferece essa opção quando você executa um workflow incluído, salvo ou de plugin pelo nome, não para um script que o Claude escreveu para a tarefa atual.
View raw script: lê o script antes de decidir
No: cancela

Ctrl+G abre o script no seu editor. Com Yes, run it ou No selecionado, pressione Tab para adicionar um comentário à sua resposta. Se você verá este prompt depende do seu modo de permissão:

Modo de permissão	Quando você é solicitado
Auto	Apenas no primeiro lançamento. Qualquer Yes registra o consentimento nas suas configurações de usuário, e lançamentos posteriores iniciam sem solicitação. Totalmente ignorado quando o ultracode está ativado
Manual, aceitar edições	Toda execução, a menos que você tenha selecionado Yes, and don’t ask again para esse workflow neste projeto
Ignorar permissões	O Claude Code não solicita. A execução começa imediatamente
`claude -p`, Agent SDK	O Claude Code não solicita

Em claude -p e no Agent SDK, o Claude Code nunca mostra este prompt. Ele executa a chamada da ferramenta Workflow pela mesma avaliação de permissões que o restante da sessão, então regras deny, regras ask e o modo dontAsk se aplicam ao lançamento assim como se aplicam a toda chamada de ferramenta. Para permitir que o workflow inicie nessas execuções, use uma destas opções:

Regra de permissão: adicione Workflow às suas regras allow para aprovar todos os workflows, ou Workflow(<name>) para aprovar um workflow salvo pelo nome.
Modo de permissão auto: execute no modo auto, em que o classificador analisa a chamada e pode aprová-la.
Modo de ignorar permissões: execute no modo de ignorar permissões.
Um hook: retorne "allow" para a chamada a partir de um hook PreToolUse. No modo de planejamento, o workflow não inicia apenas com a aprovação do hook, então use uma regra de permissão ou a aprovação do seu host nesse caso.
Seu host: um --permission-prompt-tool ou, com o Agent SDK, um callback canUseTool o aprova.

No aplicativo Desktop, um cartão de aprovação mostra o nome do workflow, a lista de fases e um aviso sobre uso de tokens, com as ações Once, Always e Deny. A visualização de progresso aparece no painel lateral de tarefas em segundo plano. Os subagentes que o workflow cria usam suas regras de permissão, e o Claude Code escolhe o modo de permissão deles pelas regras descritas em em qual modo de permissão um subagente é executado. Para evitar prompts em uma execução longa, adicione as ferramentas de que os agentes precisam às suas regras allow antes de iniciar.

Salve o workflow para reutilização

Quando o Claude escreve um workflow para uma tarefa que você vai repetir, você pode salvar o script dessa execução como um comando. Um processo como uma revisão que você executa em cada branch passa então a executar a mesma orquestração todas as vezes. Execute /workflows, selecione a execução que deseja manter e pressione s. Na caixa de diálogo de salvamento, Tab alterna entre os dois locais de salvamento:

.claude/workflows/ no seu projeto: compartilhado com todos que clonam o repositório
~/.claude/workflows/ no seu diretório pessoal: disponível em todos os projetos, visível apenas para você. Se você definir CLAUDE_CONFIG_DIR, esse local é o diretório workflows/ sob esse caminho.

A caixa de diálogo de salvamento mostra o caminho resolvido para o local pessoal. Pressione Enter para salvar. O workflow é executado como /<name> em sessões futuras a partir de qualquer um dos locais. O Claude Code verifica se há links simbólicos no local de salvamento antes de gravar e mostra um erro em vez de gravar através de um:

Local do projeto: o Claude Code recusa se .claude, .claude/workflows ou o arquivo de destino for um link simbólico.
Local pessoal: o Claude Code recusa apenas se o próprio arquivo de destino for um link simbólico, então um diretório ~/.claude gerenciado por uma ferramenta de dotfiles ainda funciona.

Em um monorepo com vários diretórios .claude/, você pode manter os workflows junto ao pacote ao qual se aplicam. Salvar no local do projeto grava no diretório .claude/workflows/ mais próximo que já existe entre seu diretório de trabalho e a raiz do repositório, ou na raiz do repositório se ainda não existir nenhum. Os workflows de projeto também são carregados de cada .claude/workflows/ ao longo desse caminho e, quando mais de um define o mesmo nome, o Claude Code executa o mais próximo do diretório de trabalho. Se um workflow de projeto e um workflow pessoal compartilharem um nome, o de projeto é executado.

Distribua um workflow em um plugin

Para compartilhar um workflow entre equipes ou repositórios, inclua-o em um plugin. Coloque o script em um diretório workflows/ na raiz do plugin ou aponte para um local diferente com o campo de manifesto workflows. Os workflows de plugin recebem o nome do plugin como namespace. Um plugin chamado acme-tools que contém um script cujo meta.name é release-audit é executado como /acme-tools:release-audit.

Passe entrada para um workflow salvo

Um workflow salvo pode aceitar entrada por meio do parâmetro args. O script a lê como uma variável global chamada args. Use isso para fornecer uma pergunta de pesquisa, uma lista de caminhos de destino ou um objeto de configuração no momento da invocação, em vez de editar o script a cada execução. O prompt a seguir executa um workflow salvo com uma lista de números de issues:

Run /triage-issues on issues 1024, 1025, and 1030

O Claude passa a lista como dados estruturados, então o script pode chamar métodos de array e de objeto diretamente em args sem precisar analisá-la primeiro. Se args for omitido, a variável global é undefined dentro do script.

Exemplos de prompts de fluxo de trabalho

Um fluxo de trabalho se encaixa melhor quando a tarefa é maior do que um agente pode manter em contexto, ou quando a mesma etapa precisa ser executada em muitos itens. Os prompts abaixo mostram formas comuns. Cada um pede ao Claude para escrever e executar um fluxo de trabalho para essa tarefa; você não escreve o script você mesmo.

Auditar muitos arquivos para o mesmo problema

Distribua um agente por arquivo e depois colete e verifique os achados.

use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it

Continue corrigindo até que uma verificação seja aprovada

Execute um verificador, corrija o que falhou e repita até que seja aprovado ou pare de fazer progresso.

use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress

Migrar muitos arquivos em paralelo

Descubra os arquivos a migrar, transforme cada um em uma cópia isolada para que as edições não entrem em conflito e verifique cada resultado.

use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy

Revisar cada arquivo alterado e escrever um resumo

Execute um revisor por arquivo e depois passe todos os achados para um agente que os classifica e deduplica.

use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary

Pesquisar um tópico em muitas fontes

Distribua leitores entre changelogs, problemas e documentação e depois sintetize. O fluxo de trabalho /deep-research incluído faz isso; você também pode descrever uma versão mais restrita.

use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches

Encontrar problemas até que a lista pare de crescer

Continue pesquisando em rodadas e pare quando novas rodadas não encontrarem nada novo.

use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new

Como o script salvo se parece

Quando você salva um fluxo de trabalho, o arquivo em .claude/workflows/ contém um bloco meta seguido por um corpo de script que orquestra subagentes. Você geralmente não precisa editá-lo, mas aqui está a forma de um pequeno para que você possa reconhecer o que Claude gerou:

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

O corpo é JavaScript simples com await no nível superior. agent() gera um subagente, pipeline() executa um por item em uma lista, e parallel() executa um conjunto de tarefas de agente ao mesmo tempo e aguarda todas elas. Uma chamada agent() é resolvida para null se você a interromper no meio da execução ou se ela atingir um erro de API irrecuperável. pipeline() mantém cada null na matriz de resultados, e é por isso que o exemplo termina com .filter(Boolean) para descartar essas entradas, incluindo a posição de um agente que travou em todas as tentativas. No modo automático, o prompt que seu script passa para agent() não conta como uma solicitação sua quando o classificador revisa as ações desse subagente, porque Claude Code o marca como texto que o script calculou. Se você passar um schema em uma chamada agent(), esse subagente retorna JSON correspondente à forma em vez de prosa. Claude Code verifica o schema antes de iniciar o subagente: quando pode provar que o schema se contradiz, a chamada falha com um erro nomeando a contradição, e o subagente nunca é iniciado. Uma contradição que pode provar é uma chave required que additionalProperties: false exclui. Se a saída do subagente ainda falhar na validação após cinco tentativas, a chamada falha com um erro que inclui a última falha de validação. Para alterar a contagem de tentativas, defina MAX_STRUCTURED_OUTPUT_RETRIES.

Editar um script salvo

Para alterar um fluxo de trabalho que você salvou, edite seu arquivo .js ou peça ao Claude para fazer a alteração. Antes de editar ou pedir, execute a skill incluída /workflow-authoring para carregar a referência de escrita de script com a qual Claude trabalha. A skill requer Claude Code v2.1.248 ou posterior. Para executar a versão editada na sessão atual, execute /reload-skills para reler os diretórios de fluxo de trabalho e depois execute /<name> novamente. Claude Code aplica essas regras a cada parte do arquivo quando carrega e executa o script:

Bloco meta: mantenha export const meta como a primeira instrução e mantenha-o um objeto literal simples com um name e uma description. Se contiver algo diferente de valores literais, como uma variável, uma chamada de função ou um spread, Claude Code remove /<name> do autocomplete /.
Corpo: além de agent(), pipeline() e parallel(), você pode chamar phase() para agrupar os agentes que seguem sob um título na visualização de progresso, chamar log() para mostrar uma mensagem acima das fases e ler o global args. Se o corpo tiver um erro de sintaxe, Claude Code o reportará quando você executar o fluxo de trabalho.
phases: se você listá-las em meta, dê a cada entrada exatamente o título que você passa para phase(). Um título phase() sem entrada obtém seu próprio grupo de progresso.
Timestamps e aleatoriedade: Claude Code faz Date.now(), Math.random() e um new Date() sem argumentos lançarem dentro do script, para que uma execução relançada repita as mesmas chamadas agent(). Passe um timestamp através de args em vez disso.

Você também pode editar o script de uma única execução em vez da cópia salva. Retomar após uma pausa cobre quais agentes são executados novamente quando você relança um script editado. Para as entradas da ferramenta Workflow, consulte sua entrada na referência do Agent SDK.

Como um fluxo de trabalho é executado

O runtime do fluxo de trabalho executa o script em um ambiente isolado, separado de sua conversa. Os resultados intermediários permanecem em variáveis de script em vez de chegar ao contexto de Claude. A menos que Claude inicie uma execução a partir do caminho de um arquivo de script, Claude Code escreve o script da execução em um arquivo sob o diretório da sua sessão em ~/.claude/projects/. Claude recebe o caminho do script quando a execução começa, então você pode pedir por ele. Você pode abrir esse arquivo para ler a orquestração que Claude escreveu, fazer um diff com o script de uma execução anterior, ou editá-lo e pedir a Claude para relançar a partir da versão editada. Claude pode iniciar um fluxo de trabalho apenas a partir de um arquivo de script que a sessão já tem permissão para ler. Para executar um script mantido fora do seu diretório de trabalho, adicione seu diretório com /add-dir ou uma regra de permissão Read primeiro. O runtime rastreia o resultado de cada agente conforme a execução progride, o que é o que torna uma execução retomável dentro da mesma sessão.

Prompt caching em um fan-out

Agentes na mesma execução podem ler o prompt cache um do outro. Dois agentes que executam com o mesmo modelo, nível de esforço, tipo de agente, ferramentas, esquema de saída e diretório de trabalho constroem o mesmo prefixo de ferramentas e prompt do sistema, então um agente que começa após a resposta de um irmão correspondente ter começado lê o cache desse irmão em sua primeira solicitação. As solicitações de um agente de fluxo de trabalho ficam fora do bucket de TTL de cache da conversa principal, então seu cache dura cinco minutos por padrão, inclusive em uma assinatura Claude. Para mantê-lo por uma hora, defina subagentPromptCacheTtl como 1h. A API cobra gravações de cache de 1 hora a uma taxa mais alta. Quando um fan-out inicia vários agentes correspondentes de uma vez, Claude Code mantém todos exceto o primeiro até que a resposta do primeiro agente comece, depois libera os agentes mantidos juntos para que suas primeiras solicitações leiam o prefixo compartilhado em vez de cada um processá-lo sem cache. Claude Code limita a retenção a CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS milissegundos, 5000 por padrão. Defina como 0 para desabilitar a retenção.

Comportamento e limites

O runtime aplica as seguintes restrições:

Restrição	Por quê
Sem entrada do usuário durante a execução	Uma execução pausa por conta própria apenas para prompts de permissão de agente e uma espera de limite de uso. Para aprovação entre estágios, execute cada estágio como seu próprio fluxo de trabalho
Sem acesso direto ao sistema de arquivos ou shell do próprio fluxo de trabalho	Agentes leem, escrevem e executam comandos. O script coordena os agentes
Sem carregamento de módulo: um script que contém `import()` falha antes da execução começar	O corpo do script é JavaScript simples. Coloque o trabalho que precisa de uma biblioteca na tarefa de um agente
Até 16 agentes simultâneos por padrão, menos quando Claude Code tem menos CPUs disponíveis, inclusive dentro de um container com CPU limitada. Para alterar o limite, defina `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` para um valor de 1 a 256, o que requer Claude Code v2.1.269 ou posterior	Limita o uso de recursos locais
Em um fan-out, agentes que compartilham o prefixo de prompt-cache do primeiro agente iniciam até 5 segundos depois por padrão	Todos exceto o primeiro leem o prefixo que o primeiro agente armazenou em cache em vez de cada um processá-lo sem cache
Até 4.096 itens em uma única chamada `parallel()` ou `pipeline()`: o runtime rejeita uma lista mais longa com um erro	Um limite silencioso deixaria cair parte da carga de trabalho sem informar o script
1.000 agentes totais por execução	Previne loops descontrolados

Gerenciar execuções

Uma vez que uma execução começa, você a gerencia a partir da visualização /workflows, ou expandindo sua linha de progresso no painel de tarefas abaixo da caixa de entrada. Quando você para uma execução, ela permanece no painel de tarefas enquanto qualquer um dos processos de seus agentes ainda estiver em execução. Se você parar novamente, Claude Code re-sinaliza esses processos.

Retomar após uma pausa

Retome uma execução pausada de /workflows selecionando-a e pressionando p. Para uma execução que você parou, peça a Claude para relançar o fluxo de trabalho com o mesmo script. Se agentes da execução parada ainda não tiverem saído, Claude Code recusa o relançamento até que saiam, para que uma segunda cópia desses agentes não possa ser executada ao lado deles.

Quais agentes são executados novamente

Claude Code reproduz a execução na ordem em que os agentes começam, e cada agente retorna seu resultado salvo ou é executado novamente:

Concluído: retorna seu resultado salvo. O primeiro agente cujo prompt difere da execução anterior, porque você editou o script ou um agente anterior retornou algo diferente, é executado novamente, assim como todos os agentes depois dele, mesmo os que foram concluídos. Antes da v2.1.305, agentes concluídos também podiam ser executados novamente quando você relançava um script não editado cujos itens de pipeline() ou tarefas de parallel() executavam mais de um agente cada. Para evitar essas reexecuções em novas execuções, atualize Claude Code.
Ainda em execução quando você parou: começa novamente. Parar toda a execução não conta nenhum agente como falho.
Falhou: é executado novamente, assim como todos os agentes que o script inicia depois dele, mesmo os que foram concluídos. Parar um agente sozinho, selecionando-o em /workflows e pressionando x, conta como falha.

Esse último caso significa que uma falha no meio de um fan-out reexecuta trabalho que já foi concluído. Se um script inicia A, B, C e D nessa ordem e B falha, relançar retorna A do cache e executa B, C e D novamente. Se você editar um script que iniciava A, B, C e D para que ele inicie A, C, B e D, o segundo agente a iniciar agora é C, onde a execução anterior iniciou B. Relançar retorna A do cache e executa C, B e D novamente.

Retomar após sair da sessão

Se você colocar sua sessão em segundo plano ou sair de Claude Code enquanto uma execução de fluxo de trabalho está em andamento, a execução não continua por conta própria. A execução só continua quando Claude a relança com uma chamada Workflow, que reproduz a execução a partir de seus resultados salvos.

Você colocou a sessão em segundo plano ou escolheu Move to background and exit: se a execução não tiver continuado quando você verificar a sessão em segundo plano, peça a Claude nela para relançar o fluxo de trabalho. Dependendo do seu modo de permissão, Claude Code pede que você aprove o relançamento primeiro. Se a sessão aparecer em Needs input no agent view, conecte-se a ela para responder ao prompt de aprovação.
O relançamento na sessão em segundo plano falhou com nothing to resume: peça a Claude para iniciar o fluxo de trabalho novamente como uma nova execução. Se Claude iniciou a execuç��o a partir do caminho de um arquivo de script fora de ~/.claude/projects/, como um no seu diretório de trabalho, Claude não consegue relançá-la na sessão em segundo plano.
Você escolheu Exit and stop tasks, ou Move to background and exit não foi oferecido: a execução parou com a sessão, e Claude Code mantém os resultados salvos da execução no diretório dessa sessão em ~/.claude/projects/. Retome a sessão com claude --resume no seu shell e, em seguida, peça a Claude para relançar o fluxo de trabalho. Em uma sessão nova, Claude não tem nenhuma execução anterior para relançar e inicia o fluxo de trabalho do zero.

Em uma sessão em nuvem, Claude Code também salva os resultados da execução com o histórico de conversa da sessão, que sobrevive quando a VM da sessão é recuperada. Quando você reabre tal sessão e pede a Claude para relançar o fluxo de trabalho, agentes concluídos ainda retornam seus resultados salvos. Em sessões locais e em nuvem, quando Claude relança uma execução anterior e Claude Code não consegue encontrar os resultados salvos dessa execução, o relançamento falha com um erro nothing to resume em vez de iniciar a execução novamente por conta própria. Peça a Claude para iniciar o fluxo de trabalho novamente como uma nova execução.

Quando uma execução atinge seu limite de uso

Quando um agente atinge seu limite de uso do claude.ai, a execução pausa em vez de falhar esse agente: os agentes que atingem o limite aguardam a redefinição, e nenhum novo agente inicia. Pouco depois que o limite é redefinido, os agentes em espera são executados novamente e a execução continua por conta própria. Requer Claude Code v2.1.271 ou posterior; em versões anteriores, os agentes afetados falham. Enquanto a execução aguarda, sua linha de progresso no painel de tarefas e o cabeçalho /workflows mostram quando o limite é redefinido. A execução pausa apenas quando todos esses itens se aplicam; quando um não se aplica, o agente afetado falha em vez disso:

A sessão é interativa e conectada com uma assinatura claude.ai. Uma execução não pausa em modo não interativo com claude -p ou no Agent SDK, em uma sessão em segundo plano, ou em uma sessão de colega de Remote Control ou agent team.
autoContinueAtUsageLimit está ativado, a mesma configuração que permite que a sessão em si aguarde a redefinição de um limite de uso. Se você desativá-lo durante uma espera, a espera termina e os agentes em espera falham.
O limite é redefinido dentro de 24 horas. Um limite semanal pode ser redefinido mais adiante.
A execução ainda não aguardou duas vezes. Quando atinge o limite pela terceira vez, o agente falha.

Quando um agente trava e reinicia

Um agente cuja saída para de chegar por tempo suficiente começa novamente a partir do mesmo prompt. Em /workflows, seu nome ganha um sufixo (retry 1) e seu detalhe mostra attempt 2 (stalled). A reinicialização é automática, então você não precisa fazer nada. A nova tentativa começa sem a transcrição da tentativa travada. Arquivos que a tentativa travada já alterou permanecem alterados, e os tokens que ela gastou permanecem no total da execução. A janela de travamento é quanto tempo Claude Code aguarda por saída de um agente antes de encerrar a tentativa. O tempo que o agente passa aguardando suas próprias chamadas de ferramenta ou uma redefinição do limite de uso não conta para a janela de travamento. Um agente reinicia no máximo cinco vezes, contando qualquer reinicialização que você solicite com r. Se a sexta tentativa também travar, a chamada agent() falha, e o início do erro diz o motivo:

agent stalled on all 6 attempts: todas as tentativas passaram a janela inteira sem saída. Se o trabalho do agente o mantém em silêncio por tanto tempo, aumente a janela
agent lost its reply on all 6 attempts: o stream de resposta de cada tentativa ficou em silêncio e Claude Code desistiu de aguardá-lo. Aumentar a janela de travamento não ajuda, já que um watchdog de inatividade de streaming encerrou a resposta primeiro e CLAUDE_STREAM_IDLE_TIMEOUT_MS define o timeout desse watchdog
agent abandoned after 6 attempts: as tentativas terminaram de maneiras diferentes, que o erro lista em ordem

Para dar a um agente mais tempo para produzir saída antes que a janela termine:

Um agente: passe stallMs em milissegundos na sua chamada agent(), como agent(prompt, { stallMs: 1800000 }) para 30 minutos
Todos os agentes: defina CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS, que também se aplica a subagentes fora de fluxos de trabalho

Se a execução continua após a falha depende de como seu script chamou o agente:

Dentro de parallel() ou pipeline(): a execução prossegue com null no lugar do resultado do agente
Aguardado diretamente: a execução termina com o erro

Para tentar novamente, peça a Claude para relançar o fluxo de trabalho. Retomar após uma pausa cobre o que é executado novamente.

Custo

Um fluxo de trabalho spawna muitos agentes, então uma única execução pode usar significativamente mais tokens do que trabalhar através da mesma tarefa em conversa. As execuções contam para o uso do seu plano e limites de taxa. Para avaliar o gasto antes de se comprometer com uma tarefa grande, execute o fluxo de trabalho em um pequeno recorte primeiro: um diretório em vez de todo o repositório, ou uma pergunta estreita em vez de uma ampla. A visualização /workflows mostra o uso de tokens de cada agente conforme a execução progride, e você pode parar a execução lá a qualquer momento, geralmente sem perder o trabalho concluído. Retomar após uma pausa cobre o que uma execução parada mantém. Os limites de agente do runtime limitam quantos agentes uma única execução pode spawnar, o que limita o custo de um script descontrolado. Para manter execuções com menos agentes, escolha a diretriz de tamanho small. Claude Code também sinaliza uma execução que cresce incomumente grande. Quando um fluxo de trabalho agenda mais de 25 agentes, ou sua projeção de token total passa 1,5 milhão, sua linha de progresso no painel de tarefas abaixo da caixa de entrada mostra um aviso Large workflow. O aviso aponta você para /workflows, onde você pode parar a execução. O aviso é consultivo: ele não pausa ou limita a execução. Duas configurações mudam quando você o vê:

Se você escolher uma diretriz de tamanho você mesmo, a contagem de agentes dela substitui o limite de 25 agentes. A diretriz padrão integrada deixa o limite em 25.
Sessões com ultracode ativado não mostram o aviso, porque ativar ultracode já o opta para execuções grandes.

Claude Code escolhe o modelo de cada agente de fluxo de trabalho na mesma ordem que usa para subagentes. Um modelo que o script nomeia para um estágio conta como o modelo por invocação nessa ordem. Quando nada mais atribui um, o agente é executado no modelo da sua sessão. Para controlar o custo do modelo:

Verifique /model antes de uma execução grande se você geralmente muda para um modelo menor para trabalho de rotina
Peça a Claude para usar um modelo menor para estágios que não precisam do mais forte quando você descreve a tarefa

Quando a availableModels allowlist da sua organização bloqueia um modelo que o script solicita para um agente, esse agente é executado em um modelo substituído em vez disso, seguindo as mesmas regras de substituição que subagentes.

Defina uma diretriz de tamanho

Uma diretriz de tamanho diz a Claude quantos agentes visar quando escreve um fluxo de trabalho dinâmico. Claude Code envia a diretriz para Claude como conselho, não um limite, então um prompt que pede uma escala diferente ainda a sobrescreve. Cada valor mapeia para uma contagem de agentes:

Valor	Contagem de agentes que Claude visa
`unrestricted`	Sem diretriz: Claude dimensiona o fluxo de trabalho para a tarefa
`small`	Menos de 5 agentes
`medium`	Menos de 10 agentes
`large`	Menos de 50 agentes

O padrão é medium, ou small quando você está conectado em um plano Pro com Claude Code v2.1.271 ou posterior. Até você escolher um valor, a linha /config marca o valor como padrão, e a linha Running in background do fluxo de trabalho nomeia o tamanho em vigor. Para alterar a diretriz, escolha um valor para a configuração Dynamic workflow size em /config, ou execute /config workflowSizeGuideline=small. Você também pode definir a chave workflowSizeGuideline em qualquer arquivo de configurações; esse valor tem precedência sobre /config, e Claude Code oculta a linha /config enquanto um arquivo de configurações fornece um. As alterações entram em vigor no próximo prompt. Os limites de agente do runtime ainda se aplicam independentemente da configuração.

Desativar fluxos de trabalho

Fluxos de trabalho estão disponíveis na CLI, no aplicativo Desktop, nas extensões IDE, modo não interativo com claude -p, e no Agent SDK. As mesmas configurações de desativação se aplicam em cada superfície. Para desativar fluxos de trabalho para você:

Alterne Dynamic workflows desativado em /config. Persiste entre sessões.
Defina "disableWorkflows": true em ~/.claude/settings.json. Persiste entre sessões.
Defina CLAUDE_CODE_DISABLE_WORKFLOWS=1. Lido na inicialização, então se aplica onde quer que você o defina.

Para desativar fluxos de trabalho para toda a sua organização, defina "disableWorkflows": true em configurações gerenciadas, ou use o alternador na página configurações de administrador de Claude Code. Quando fluxos de trabalho estão desativados:

/workflows, os comandos de fluxo de trabalho e a skill /workflow-authoring não estão disponíveis
A palavra-chave ultracode não dispara mais uma execução, e o alternador Ultracode é removido de /effort

Uma execução que já estava em progresso continua. Desativar fluxos de trabalho também torna ultracode indisponível. Nenhuma configuração gerenciada descarta ultracode sozinho: onde quer que esteja disponível, os usuários podem ativá-lo com /effort ultracode. Um limite de esforço reduz o nível de esforço que uma sessão com ultracode ativado executa, mas não desativa ultracode.

Executar agentes em paralelo: comparar subagentos, visualização de agente, equipes de agentes e fluxos de trabalho
Criar subagentos personalizados: a primitiva de worker que fluxos de trabalho orquestram
Gerenciar custos: como execuções multi-agente contam para limites de uso

​Quando usar um fluxo de trabalho

​Executar um workflow agrupado

​Workflows agrupados

​Acompanhar a execução

​Peça ao Claude para escrever um workflow

​Peça um workflow no seu prompt

​Descartar ou desativar a palavra-chave

​Onde a palavra-chave funciona

​Deixe o Claude decidir com ultracode

​Aprove o plano antes que ele seja executado

​Salve o workflow para reutilização

​Distribua um workflow em um plugin

​Passe entrada para um workflow salvo

​Exemplos de prompts de fluxo de trabalho

​Auditar muitos arquivos para o mesmo problema

​Continue corrigindo até que uma verificação seja aprovada

​Migrar muitos arquivos em paralelo

​Revisar cada arquivo alterado e escrever um resumo

​Pesquisar um tópico em muitas fontes

​Encontrar problemas até que a lista pare de crescer

​Como o script salvo se parece

​Editar um script salvo

​Como um fluxo de trabalho é executado

​Prompt caching em um fan-out

​Comportamento e limites

​Gerenciar execuções

​Retomar após uma pausa

​Quais agentes são executados novamente

​Retomar após sair da sessão

​Quando uma execução atinge seu limite de uso

​Quando um agente trava e reinicia

​Custo

​Defina uma diretriz de tamanho

​Desativar fluxos de trabalho

​Recursos relacionados

Quando usar um fluxo de trabalho

Executar um workflow agrupado

Workflows agrupados

Acompanhar a execução

Peça ao Claude para escrever um workflow

Peça um workflow no seu prompt

Descartar ou desativar a palavra-chave

Onde a palavra-chave funciona

Deixe o Claude decidir com ultracode

Aprove o plano antes que ele seja executado

Salve o workflow para reutilização

Distribua um workflow em um plugin

Passe entrada para um workflow salvo

Exemplos de prompts de fluxo de trabalho

Auditar muitos arquivos para o mesmo problema

Continue corrigindo até que uma verificação seja aprovada

Migrar muitos arquivos em paralelo

Revisar cada arquivo alterado e escrever um resumo

Pesquisar um tópico em muitas fontes

Encontrar problemas até que a lista pare de crescer

Como o script salvo se parece

Editar um script salvo

Como um fluxo de trabalho é executado

Prompt caching em um fan-out

Comportamento e limites

Gerenciar execuções

Retomar após uma pausa

Quais agentes são executados novamente

Retomar após sair da sessão

Quando uma execução atinge seu limite de uso

Quando um agente trava e reinicia

Custo

Defina uma diretriz de tamanho

Desativar fluxos de trabalho

Recursos relacionados