🔄 O ciclo real de execução

Novo aqui? O ciclo de execução é a sequência que o agente repete várias vezes dentro de uma sessão: ler o passo do workflow, escolher uma ferramenta, executar, olhar o resultado e decidir o que fazer a seguir. Não é um passo único — é um loop (laço, repetição: a mesma sequência rodando de novo e de novo) que continua até a tarefa estar completa.

No módulo 1.1 você viu a analogia da cozinha: receita (workflow), cozinheiro (agente), utensílios (tools). Ali ficou parada, como uma foto do prato pronto. Este módulo é o filme — o cozinheiro lendo o próximo passo, pegando a faca certa, cortando, provando o resultado e só então virando a página. É esse "ler → decidir → agir → provar → repetir" que transforma uma receita parada em trabalho de verdade — um relatório pronto, uma newsletter enviada, um lote de notas fiscais organizado.

Cada volta completa do loop é chamada de iteração. Uma tarefa simples leva 3 ou 4; organizar um mês de notas fiscais pode levar dezenas — o agente decide, a cada volta, se já terminou.

Legenda: essa linha do tempo é UMA iteração do loop — uma volta completa. O passo 5 aponta de volta para o passo 1 (não desenhado aqui) porque o ciclo recomeça até o workflow terminar.

Cada vez que o ciclo recomeça, o agente precisa saber "em que ponto da receita estou". Numa sessão de Claude Code isso normalmente acontece dentro de uma única conversa: o histórico da conversa faz o papel de memória de curto prazo, lembrando o que já foi feito. Já num workflow salvo em arquivo (o que vamos praticar no módulo 1.5), o passo atual pode ficar explícito no próprio texto ou ser inferido pelo que já existe no disco — por exemplo, se o arquivo "relatorio-semana.md" já existe, o passo 4 já foi cumprido.

Novo aqui? Contexto é tudo que o agente "enxerga" ao decidir: a conversa até ali, os arquivos já lidos, o CLAUDE.md e o resultado das ferramentas já rodadas. Pense no contexto como a mesa de trabalho do cozinheiro — só o que está em cima dela é o que ele usa na hora; um ingrediente num armário fechado (arquivo nunca aberto) simplesmente não existe para ele. Esse contexto tem um custo, medido em tokens — pedaços de texto que o modelo processa a cada rodada. Quanto mais coisa "em cima da mesa", mais tokens gastos só para olhar tudo antes de decidir.

Exemplo: num workflow de "responder e-mails de clientes", a cada iteração o agente lê o próximo e-mail (o "onde estou"), decide se responde com modelo pronto ou escala para um humano, executa e observa se o envio deu certo. O "estado" é só quantos e-mails já foram processados.

Essa é a parte mais "inteligente" do ciclo: dado o passo atual e a lista de ferramentas disponíveis, o agente escolhe a que melhor resolve aquilo. Se o passo é "somar por categoria", ele pode escolher rodar um script de cálculo em vez de tentar somar manualmente. Se o passo é "publicar no site", ele escolhe a ferramenta de deploy (assunto da Trilha 4), não uma de e-mail.

Essa escolha depende diretamente de quais ferramentas foram disponibilizadas ao agente — é por isso que as Trilhas 2 (MCP) e 3 (Skills) deste curso tratam de ensinar e conectar ferramentas: quanto mais claro o menu de opções, melhor a escolha.

Outro exemplo: num "relatório de vendas semanal", o passo "somar faturamento por vendedor" tem duas ferramentas candidatas — script que soma, ou fórmulas manuais. Um agente bem configurado escolhe o script, mais rápido e determinístico — se estiver disponível. Se não, ele se vira, o que nos leva ao erro mais comum.

Depois de executar, o agente não segue cegamente para o próximo passo — ele lê o que a ferramenta devolveu. Um comando pode devolver um erro, um arquivo vazio, um número fora do esperado, ou exatamente o que deveria. Essa leitura do resultado é o gatilho da auto-correção, aprofundada no módulo 1.3.

Legenda: o laço roda da esquerda para a direita a cada passo do workflow; a seta pontilhada de volta mostra a auto-correção — o agente refazendo um passo que não saiu como esperado.

"Observar" não é opcional nem automático — é uma decisão ativa de parar e ler o que voltou antes de seguir. No exemplo da newsletter (módulo 1.5), depois de "enviar e-mail" o agente confere se veio "sucesso" ou um código de erro. Com notas fiscais, depois de mover um arquivo ele confere se ele realmente está na pasta — não assume que deu certo só porque o comando "rodou sem travar".

Essa leitura tem três saídas: (1) bateu com o esperado, segue adiante; (2) veio um erro claro, o agente tenta corrigir ou avisa você; ou (3) o resultado é ambíguo — nem certo nem claramente errado — e é aí que entra o julgamento aprofundado no módulo 1.3 sobre auto-correção.

1. Leia a pasta atual e liste os arquivos .txt que existem.
2. Para cada arquivo .txt encontrado, conte quantas linhas ele tem.
3. Crie um arquivo resumo.md com o nome de cada arquivo e sua contagem de linhas.
4. Confira se resumo.md foi criado e se o número de linhas listadas bate com os arquivos originais.

O ciclo se repete passo a passo até o workflow acabar. Em cada volta, o agente também decide se precisa repetir o passo atual (por exemplo, se um comando falhou por um motivo temporário) ou se deve parar e pedir ajuda a você (por exemplo, se falta uma senha que só você tem). Esse segundo caso — parar e avisar — é tão importante quanto executar: um bom agente sabe reconhecer quando não deve seguir sozinho.

Novo aqui? Esse momento de decisão — avaliar seguir, repetir ou parar com base no resultado observado — é o que chamamos de raciocínio do agente. Sem ele, o ciclo seria só uma sequência cega de comandos, incapaz de reagir a imprevistos.

No exemplo de e-mails: loop saudável repete "enviar" só se a falha for temporária, e para depois de 2-3 tentativas, escalando para você. Loop travado insiste no mesmo erro dezenas de vezes sem resultado novo.

O ciclo termina de três formas: (1) o workflow chegou ao último passo e tudo bateu — sucesso; (2) o agente identificou que falta algo que só você pode dar e parou para perguntar; ou (3) travou repetindo e é hora de você intervir. Reconhecer qual das três está acontecendo é o assunto central do módulo 1.4.

Vale reforçar a diferença entre os finais 2 e 3 — parecidos à primeira vista, os dois terminam sem o resultado pronto. No final 2 (pausa por decisão), o agente sabe o que falta e faz uma pergunta específica, como "preciso da chave da API do Gmail — onde encontro?". No final 3 (travamento), ele não sabe mais o que tentar e repete algo que já provou não funcionar — aí a saída é você ajustar o workflow, não responder.

No exemplo de notas fiscais: sucesso é todas as notas nas pastas certas com um resumo por categoria; pausa por decisão é o agente achando uma nota sem categoria clara e perguntando onde ela entra; travamento é tentar abrir um PDF corrompido repetidamente sem conseguir — hora de você olhar o arquivo na mão.