Lição 1: Quando um loop só não basta

Objetivos de aprendizado:

• Usar uma tarefa real que quebra agentes de loop único para mostrar por que “arrume uma janela maior” não resolve o problema de forma
• Enunciar a distinção arquitetural entre fluxos de trabalho e agentes, e usar “quem detém o plano” para situar qualquer sistema nesse eixo
• Listar os gatilhos para subir de nível e as condições para ficar onde está, com latência e custo de tokens na mesa antes de tudo

Pré-requisitos: Concluir os 11 primeiros cursos desta série, saber escrever à mão um loop de harness dirigido por stop_reason (curso 7, “Fundamentos do Harness de Agente: Laços e Controle”) | Próxima: Lição 2 >>

No módulo 30, alguma coisa está errada

Você precisa migrar um repositório de backend do framework de RPC interno v1 para o v2. Antes de começar, precisa de um inventário: o repositório tem 40 módulos, e cada módulo precisa de uma avaliação de migração — listar os pontos de risco, estimar o tamanho das mudanças, anexar um manifesto de dependências. O trabalho não é difícil, é só numeroso. Você tem aquele harness do curso 7 desta série:

(Um harness é o código hospedeiro que envolve as chamadas ao modelo: manda a requisição, executa as ferramentas que o modelo quer usar, devolve os resultados, decide se continua.)

Você entrega a lista dos 40 módulos de uma vez, escreve “avalie cada um, um relatório por módulo” e vai fazer café.

Os 5 primeiros módulos ficam ótimos: ele faz grep dos pontos de chamada, lê configurações, confere arquivos de teste, e os relatórios saem mais detalhados do que você esperava.

No módulo 15, você volta e olha os logs. O array messages já está impressionante: saída de grep dos primeiros 14 módulos, pedaços inteiros de arquivos de configuração lidos, recibos de sucesso de escrita de arquivo, rastros de caminhos tomados e depois abandonados — tudo isso ainda ocupando aquela linha do tempo. Nada desse conteúdo estava errado — cada coisa foi necessária no seu momento. Mas a função atual delas ficou reduzida a uma só: ocupar espaço.

No módulo 30, a qualidade desaba. Ele copia a conclusão do módulo 27 para o módulo 30 porque os nomes são parecidos; pula caladinho a etapa “conferir se há interceptadores customizados” que tinha feito todas as vezes anteriores; no módulo 34, até o formato da saída começa a derivar.

Sua primeira reação provavelmente é: trocar para um modelo com uma janela de contexto maior.

Essa reação só leva você até a metade do caminho. Dobre a janela e o ponto de colapso provavelmente sai do módulo 30 para o módulo 55. O seu próximo repositório tem 120 módulos. Você não resolveu o problema, você comprou uma suspensão da execução.

O que se esgotou de verdade não é a janela, é a forma de “um loop só”: 40 itens independentes forçados a dividir uma linha do tempo, um orçamento de atenção. A qualidade da avaliação do módulo 30 depende de quanto resíduo os 29 primeiros módulos deixaram para trás — e essas duas coisas não têm nada a ver uma com a outra.

O que este curso faz é trocar essa forma.

Primeiro, acerte o vocabulário oficial

Agentes conseguem lidar com tarefas sofisticadas, mas a implementação deles costuma ser direta. Tipicamente são apenas LLMs usando ferramentas com base em feedback do ambiente, dentro de um loop¹. Aquele while que você escreveu no curso 7 desta série é exatamente isso, sem uma linha de diferença. Então se posicione: você já construiu um agente, este curso não começa do zero.

Uma camada acima. A Anthropic classifica todas essas variações como sistemas agênticos (em linguagem direta: sistemas montados a partir de modelos, ferramentas e alguma forma de fluxo de controle, capazes de percorrer várias etapas por conta própria), mas dentro dessa categoria ampla ela traça uma distinção arquitetural importante¹:

• Fluxos de trabalho são sistemas em que LLMs e ferramentas são orquestrados por caminhos de código predefinidos¹. “Caminhos de código predefinidos” é a expressão-chave — o que acontece em seguida está escrito no código.
• Agentes, por outro lado, são sistemas em que os LLMs dirigem dinamicamente seus próprios processos e o uso de ferramentas, mantendo controle sobre como realizam as tarefas¹. O que acontece em seguida, o modelo decide na hora.

Mais um termo fundamental que você vai usar repetidamente nas próximas lições. Em computação, sistemas determinísticos produzem a mesma saída toda vez, dadas entradas idênticas, enquanto sistemas não determinísticos — como agentes — podem gerar respostas variadas mesmo com as mesmas condições iniciais².

Aplique essa definição ao seu while e você verá que são duas coisas costuradas: como mandar a requisição, como executar as chamadas de ferramenta, quando parar — isso é determinístico, escrito por você em código; enquanto “o que dar grep em seguida, se este relatório está terminado” — isso é não determinístico, decidido pelo modelo na hora. A cirurgia que você está prestes a fazer é mover o poder de decisão entre essas duas metades.

O eixo de “quem detém o plano”

A documentação do Claude Code pergunta isso de forma mais direta: Subagentes, skills, times de agentes e fluxos de trabalho conseguem, todos, rodar uma tarefa de várias etapas. A diferença é quem detém o plano³.

(“Subagente” = um assistente que trabalha de forma independente na sua própria janela de contexto e devolve só um resumo; “fan-out” = despachar vários subagentes para trabalharem ao mesmo tempo. O curso 6 desta série cobriu os dois termos.)

Essa frase corta um monte de abordagens que parecem semelhantes. Pegue “rodar avaliações para 40 módulos”:

• Você deixa o modelo percorrer os 40 em uma única conversa — o plano está nas mãos do modelo, e é implícito, escondido no histórico da conversa. Você teria que garimpar logs para adivinhar o caminho que ele pretendia.
• Você faz do modelo um orquestrador, e ele decide a cada turno qual subagente despachar para qual módulo — o plano continua nas mãos do modelo, só um pouco mais explícito.
• Você escreve um script, e o próprio script percorre aqueles 40 módulos com um for — o plano está no código. Você pode abrir o arquivo e lê-lo de ponta a ponta, e rodá-lo de novo amanhã sem mudar nada.

A terceira abordagem tem uma descrição precisa: Um fluxo de trabalho move o plano para dentro do código. O script do fluxo de trabalho detém ele mesmo o loop, a ramificação e os resultados intermediários, então o contexto do Claude guarda apenas a resposta final³. E os resultados intermediários ficam em variáveis do script em vez de aterrissarem no contexto do Claude³. A saída do grep do módulo 27 fica em um array JavaScript, então a avaliação do módulo 30 naturalmente não consegue vê-la — não porque o modelo aprendeu a ignorá-la, mas porque ele nunca teve a chance de vê-la.

Para as duas pontas desse eixo, a orientação oficial dá a cada uma uma frase sobre adequação: Quando mais complexidade se justifica, fluxos de trabalho oferecem previsibilidade e consistência para tarefas bem definidas, enquanto agentes são a melhor opção quando flexibilidade e tomada de decisão conduzida pelo modelo são necessárias em escala¹.

Uma coisa a esclarecer: este curso chama esse eixo de “espectro de determinismo” e chama os padrões de composição da lição 5 de “grafos”, “nós”, “arestas”. Esses rótulos são metáforas de engenharia do próprio curso e nunca aparecem nas fontes primárias — os materiais primários só fornecem as definições das duas pontas (caminhos de código predefinidos vs. decisões conduzidas pelo modelo)¹ e o enquadramento de “quem detém o plano”³. Tomamos emprestadas as metáforas do espectro e do grafo porque são convenientes para arrumar padrões que existem de verdade; você não vai ler esses termos em nenhuma documentação oficial, então não os apresente como conceitos oficiais.

Quando subir de nível

“Um loop só não basta” soa como intuição, mas há gatilhos que dá para enunciar.

Gatilho um: a tarefa precisa de mais agentes do que uma conversa consegue coordenar, ou você quer a orquestração codificada como um script que dá para ler e rodar de novo³. A primeira metade é uma questão de capacidade, a segunda é uma questão de engenharia — mesmo que uma conversa consiga coordenar aquilo no limite, “dá para rodar exatamente do mesmo jeito amanhã?” já se qualifica como motivo por si só.

Gatilho dois: quando a tarefa é maior do que um agente consegue segurar no contexto, ou quando a mesma etapa precisa rodar sobre muitos itens³. Essas duas frases juntas descrevem exatamente o cenário dos 40 módulos do começo. Note a segunda frase: a quantidade de itens é, por si só, um motivo, independentemente de cada item ser difícil ou não.

Gatilho três: quando uma tarefa lateral inundaria a sua conversa principal. A descrição de cenário da documentação de subagentes: quando uma tarefa lateral inundaria a sua conversa principal com resultados de busca, logs ou conteúdos de arquivo que você não vai consultar de novo, despache um subagente — ele faz esse trabalho no próprio contexto e devolve apenas o resumo⁴, preservando contexto ao manter exploração e implementação fora da sua conversa principal⁴. Repare que esse gatilho prescreve “despache um subagente” — o plano continua nas mãos do modelo; isso e “mover o plano para dentro do código” são duas coisas diferentes. As colunas B e C do exercício do Nível 2 vão colocar essa distinção lado a lado.

Olhe este código para pegar o jeito de como fica a forma depois de trocada:

O loop continua sendo aquele loop — dentro de runHarnessLoop está o while que você escreveu no curso 7 desta série. Só uma coisa mudou: quem conta até 40. Antes, o modelo estava contando. Agora, o for é que conta.

Quando ficar onde está

Atrás dos sinais de gatilho existe uma lista de conferência do lado oposto, igualmente longa, e essa é mais fácil de pular.

Ache a solução mais simples possível, e só aumente a complexidade quando necessário. Isso pode significar não construir sistemas agênticos de jeito nenhum¹. Para muitas aplicações, no entanto, otimizar chamadas únicas de LLM com recuperação e exemplos no contexto costuma bastar¹. Aquele trabalho de renomear uma função em 12 lugares não precisa de harness, não precisa de orquestração — uma chamada mais um grep e está feito.

Alguns domínios hoje não são uma boa escolha para sistemas multiagente: aqueles que exigem que todos os agentes compartilhem o mesmo contexto, ou em que há muitas dependências entre agentes. O texto nomeia um exemplo — a maior parte das tarefas de programação envolve menos tarefas genuinamente paralelizáveis do que pesquisa, e agentes LLM ainda não são muito bons em coordenar e delegar a outros agentes em tempo real⁵. Você está refatorando um módulo de pedidos fortemente acoplado, e as mudanças se propagam por uma cadeia de chamadores — abrir isso em fan-out para cinco subagentes só deixa tudo mais lento e mais bagunçado, porque todos precisam olhar para a mesma coisa, e quem se mexer primeiro invalida a informação de todos os outros.

Na direção contrária, as condições positivas de adequação são declaradas com a mesma clareza: eles descobriram que sistemas multiagente se destacam em tarefas que envolvem paralelização pesada, informação que excede janelas de contexto únicas, e interação com numerosas ferramentas complexas⁵, e tarefas em que o valor da tarefa é alto o bastante para pagar pelo desempenho adicional⁵. Quanto mais dessas três condições você acertar, mais vale a pena subir de nível.

Há também uma categoria de tarefas que deve ficar com loops autônomos, sem ser forçada para dentro de orquestração: problemas em aberto, em que é difícil ou impossível prever o número de etapas necessárias, e em que você não consegue fixar um caminho rígido no código — esses podem ser entregues a agentes, eles vão potencialmente operar por muitos turnos, e você precisa ter algum nível de confiança na tomada de decisão deles¹. O próprio sistema de pesquisa da Anthropic é desse tipo: trabalho de pesquisa envolve problemas em aberto em que é muito difícil prever de antemão as etapas necessárias. Você não consegue fixar um caminho rígido para explorar temas complexos, porque o processo é inerentemente dinâmico e dependente do caminho⁵.

Então “devo migrar para orquestração?” não é uma barra de progresso de mão única. A avaliação dos 40 módulos deve caminhar para orquestração porque as etapas são fixas, só numerosas; “devemos trocar a fila de mensagens de A para B?” não deve caminhar para orquestração porque você nem sabe quantos artigos vai precisar ler.

Ponha o custo na mesa antes de tudo

Antes de começar a aprender os cinco padrões, abra a contabilidade.

Sistemas agênticos com frequência trocam latência e custo por melhor desempenho na tarefa, e você deveria considerar quando essa troca faz sentido¹. Nem uma palavra aqui é retórica: está descrevendo uma troca.

Quão caro? A Anthropic fornece um conjunto de observações dos próprios dados: agentes tipicamente usam cerca de 4× mais tokens do que interações de chat, e sistemas multiagente usam cerca de 15× mais tokens do que chats⁵. Daí a conclusão deles — para viabilidade econômica, sistemas multiagente exigem tarefas em que o valor da tarefa seja alto o bastante para pagar pelo desempenho adicional⁵.

Note o contexto desse número: ele vem dos dados deles, não de um benchmark universal, e não é “toda abordagem de orquestração custa 15× mais”. Mas a direção é clara: a cada passo que você dá rumo a “mais agentes, mais paralelismo”, a conta sobe um degrau. Delimitando rápido: esse multiplicador mede sistemas multiagente em relação a chat, não a etiqueta de preço de “mover o plano para dentro do código” em si — os materiais primários nunca deram um número de custo isolado para scripts de orquestração. É também por isso que aqueles 40 módulos valem a subida enquanto as 12 renomeações não — não porque uma é “complexa” e a outra é “simples”, mas porque uma avaliação de migração que economiza duas semanas de retrabalho consegue bancar esse custo.

As próximas cinco lições

O resto deste curso começa pela forma mais leve e constrói rumo à composição:

• Lição 2: Encadeamento e roteamento: quebrar uma tarefa em etapas fixas com gates programáticos entre elas; classificar e então despachar para prompts especializados. A forma mais leve de “plano no código”.
• Lição 3: Paralelização: seccionamento (dividir em subtarefas independentes rodadas em paralelo) e votação (rodar a mesma tarefa várias vezes para obter saídas diversas), mais como agregar resultados em código.
• Lição 4: Orquestrador-workers: um LLM central decompõe tarefas dinamicamente, delega-as a LLMs workers e sintetiza seus resultados. A diferença-chave: as subtarefas não são predefinidas.
• Lição 5: Loops de avaliação, e composição de padrões em grafos: checar-corrigir-rechecar até passar ou parar de progredir, e então costurar os padrões anteriores. Aquela lição vai repetir: “grafo” é visualização do próprio curso.
• Lição 6: Mão na massa: elevar aquele harness de loop único do curso 7 desta série a um script de orquestração determinístico.

Essa taxonomia de padrões não é relíquia de 2024: a documentação atual de orquestração multiagente da plataforma Claude ainda nomeia, de forma independente, Parallelization (fan-out de subtarefas independentes ao mesmo tempo, com o coordenador sintetizando os resultados), Specialization (rotear para agentes com prompts de sistema e ferramentas focados em domínio), Escalation (consultar um agente ou modelo mais capaz para um subconjunto de subtarefas complexas)⁶. A pele mudou, o esqueleto é o mesmo.

Mais uma coisa sobre como este curso se divide em relação aos dois anteriores: o curso 2 desta série ensinou o conceito de fluxos de trabalho — etapas, estado, ramificação, entendimento em nível de diagrama; o curso 6 desta série ensinou divisão de trabalho e comunicação em colaboração multiagente — fan-out, prompts de delegação autocontidos, produtor-revisor. Este curso não reensina nenhum dos dois. O que ele cobre é o próprio fluxo de controle: quem conta, quem ramifica, para onde vão os resultados intermediários, o que acontece quando quebra. Ponte rápida de vocabulário: o que o curso 6 desta série chamou de “produtor-revisor”, os materiais primários chamam de evaluator-optimizer¹, e a documentação de fluxos de trabalho do Claude Code chama de fazer agentes independentes revisarem adversarialmente os achados uns dos outros³.

Proporcionalidade: tudo tem que passar pela “melhora mensurável”

Este curso vai ensinar cinco padrões e um monte de métodos de composição. Todos compartilham a mesma linha de reconhecimento, e o texto original é inequívoco: Estes blocos de construção não são prescritivos. São padrões comuns que desenvolvedores podem moldar e combinar para atender a diferentes casos de uso. A chave do sucesso, como em qualquer funcionalidade com LLM, é medir desempenho e iterar nas implementações. Repetindo: você só deveria considerar acrescentar complexidade quando ela comprovadamente melhora os resultados¹.

“Comprovadamente melhora os resultados” exige sustentação concreta, e ela vem das avaliações do curso 10 e da observabilidade do curso 11 desta série: sem um conjunto de avaliação, você não consegue dizer com clareza “acrescentar roteamento melhorou mesmo as coisas?”. O fecho do texto canônico segue esta ordem: comece com prompts simples, otimize-os com avaliação abrangente, e acrescente sistemas agênticos de várias etapas só quando as soluções mais simples ficarem aquém¹.

Então, depois de aprender cada padrão, pergunte a si mesmo: consigo produzir um número mostrando que os resultados melhoraram depois de acrescentá-lo? Se não consegue, ainda não acrescente.

💻 Exercícios

Recapitulação

• Aquele while que você escreveu no curso 7 desta série é um agente — agentes conseguem lidar com tarefas sofisticadas, mas a implementação deles costuma ser direta; tipicamente são apenas LLMs usando ferramentas com base em feedback do ambiente, dentro de um loop¹.
• Essas variações são chamadas coletivamente de sistemas agênticos, e dentro delas se traça uma distinção arquitetural: fluxos de trabalho são sistemas em que LLMs e ferramentas são orquestrados por caminhos de código predefinidos; agentes são sistemas em que os LLMs dirigem dinamicamente seus próprios processos e o uso de ferramentas, mantendo controle sobre como realizam as tarefas¹.
• O eixo que distingue os dois é “quem detém o plano”: um fluxo de trabalho move o plano para dentro do código, o próprio script detém o loop, a ramificação e os resultados intermediários, então o contexto do Claude guarda apenas a resposta final³. Este curso chama esse eixo de “espectro de determinismo” e chama a visualização de composição da lição 5 de “grafos” — os dois termos são metáforas do próprio curso e não aparecem nos materiais primários.
• Gatilhos para subir de nível: a tarefa precisa de mais agentes do que uma conversa consegue coordenar, ou você quer a orquestração codificada como um script que dá para ler e rodar de novo³; quando a tarefa é maior do que um agente consegue segurar no contexto, ou quando a mesma etapa precisa rodar sobre muitos itens³; quando uma tarefa lateral inundaria a sua conversa principal com conteúdo que você não vai consultar de novo⁴.
• Condições para ficar onde está: ache a solução mais simples possível, acrescente complexidade só quando necessário, o que pode significar não construir sistemas agênticos de jeito nenhum¹; para muitas aplicações, otimizar chamadas únicas de LLM com recuperação e exemplos no contexto costuma bastar¹; domínios que exigem contexto compartilhado ou muitas dependências entre agentes hoje não são boa escolha para multiagente, e a maior parte das tarefas de programação envolve menos tarefas genuinamente paralelizáveis do que pesquisa⁵.
• Manter com loops autônomos: problemas em aberto, difíceis de prever a contagem de etapas, sem como fixar um caminho rígido¹ — trabalho do tipo pesquisa é o caso típico, o processo é inerentemente dinâmico e dependente do caminho⁵.
• Pegue a conta primeiro: sistemas agênticos com frequência trocam latência e custo por melhor desempenho na tarefa¹; nos dados deles, agentes usam cerca de 4× mais tokens do que chat, multiagente cerca de 15×, e a viabilidade econômica exige que o valor da tarefa sustente essa melhora⁵.
• Tudo o que este curso ensina tem que passar pelo mesmo portão: acrescentar complexidade só quando ela comprovadamente melhora os resultados¹; comece com prompts simples, otimize-os com avaliação abrangente, e acrescente sistemas agênticos de várias etapas só quando as soluções mais simples ficarem aquém¹.

>> Lição 2: Encadeie, roteie: encadeamento e roteamento