Um relatório mensal do IPCA, com gráficos, tabelas e a análise escrita de cada seção, pode ser refeito por um único comando quando você monta um pipeline com agentes no Claude Code: scripts Python calculam as métricas, um time de sete agentes investiga por que o número surpreendeu o mercado e escreve os textos, e o Quarto monta o HTML final.
Este tutorial mostra a arquitetura desse pipeline, o critério que decide o que vira script e o que vira agente, e o resultado que saiu da máquina num mês em que houve o que explicar. O caso é real: em março de 2026, o IPCA veio 0,28 ponto percentual acima do que o mercado projetava.
Os dois números da figura pedem uma apresentação. A pesquisa Focus é o levantamento semanal do Banco Central com as projeções de mais de cem instituições financeiras; a mediana Focus é o valor central dessas projeções e funciona como o consenso do mercado. Quando o número que o IBGE divulga fica longe desse consenso, o desvio é chamado de surpresa inflacionária — e a de março, de +0,28 ponto percentual, foi a maior dos doze meses anteriores.
Quer construir um pipeline como este?
Na Imersão Claude Code para economistas, administradores e contadores você monta, passo a passo, projetos como o deste tutorial: da instalação do Claude Code ao time de agentes gerando relatório na sua máquina.
A pergunta que o script não responde
Calcular a surpresa é uma subtração: realizado menos mediana, e qualquer script resolve. A pergunta que paga o salário do analista é outra — por que o número veio tão acima?
A resposta de março estava espalhada em quatro lugares. A abertura por grupos do IBGE mostrava alimentação acelerando; o noticiário apontava o conflito no Oriente Médio pressionando combustíveis; a ata do Copom registrava leituras de alimentos acima do esperado; e o padrão sazonal histórico dizia que março costuma ser um mês leve para a inflação. Juntar essas peças e escrever três parágrafos defensáveis exige ler, comparar e julgar, e nada disso cabe num script.
Essa divisão organiza o projeto inteiro. O quanto é determinístico: baixar a série, buscar a mediana, subtrair, acumular em 12 meses, desenhar o gráfico. O porquê não tem gabarito: exige pesar evidências de fontes dispersas e construir uma narrativa que um leitor exigente aceite.
As três camadas do projeto
A arquitetura separa o pipeline em três camadas com fronteiras nítidas, e cada camada só faz o que a sua natureza permite conferir.
⚙️
🧠
📄
A camada de apresentação tem um detalhe de resiliência: o relatório inclui os textos dos agentes em vez de gerá-los, e essa pasta de textos é a única parte reescrita a cada divulgação. Se os agentes falharem, o relatório ainda renderiza com os textos do mês anterior, porque a parte determinística não depende deles.
Script ou agente: as três perguntas
Antes de criar qualquer agente, o projeto fixa o critério que decide para onde vai cada tarefa. Três perguntas resolvem a maioria dos casos: a tarefa é determinística (mesma entrada, mesma saída)? O resultado é verificável por igualdade, com um teste ou uma comparação de números? A fonte é estruturada, como uma API ou um CSV de colunas conhecidas? Três respostas "sim" pedem um script; qualquer "não" aponta para agente.
O argumento econômico do critério está no custo da conferência. Número que sai de um script não precisa de revisão: se o código rodou, o valor é o que a API devolveu. Número que sai de um modelo de linguagem precisa ser conferido sempre, porque o modelo produz um valor errado com a mesma naturalidade com que produz um certo. Delegar cálculo a um agente é pagar duas vezes: uma pela geração, outra pela auditoria que ela obriga.
Por isso o erro mais comum desse tipo de projeto é o agente calculando. Pedir a um agente que "leia os CSVs e calcule as variações" funciona, mas cria a necessidade de um segundo agente só para conferir as contas. Neste pipeline, a calculadora fica nos scripts de uma vez, e os agentes ficam só com o que nenhum script entrega: leitura, investigação e texto.
O que é um subagente no Claude Code
Um subagente é um auxiliar especializado que o agente principal do Claude Code invoca para uma tarefa: ele roda numa conversa própria, com contexto separado, faz o trabalho e devolve só o resultado. O principal não vê os passos intermediários, e é isso que mantém a conversa principal enxuta mesmo quando o trabalho por trás envolve baixar PDFs e varrer noticiário.
Na prática, cada subagente é um arquivo markdown dentro do projeto, com um cabeçalho de quatro campos e um corpo de instruções. O cabeçalho de um dos coletores deste pipeline ilustra o formato:
description: Baixa a ata do Copom e resume o que o comitê disse sobre inflação
tools: Bash, Read, Write
model: sonnet
Cada campo tem papel prático. A description é o gatilho da delegação: é o que o Claude lê para decidir se a tarefa encaixa naquele auxiliar. O campo tools é o cinto de segurança, porque um coletor de evidências não precisa editar arquivos e um checador não deve escrever no relatório — menos ferramentas, menos formas de errar. E uma convenção que o projeto adota em todos os sete: o corpo termina declarando os limites ("não calcula", "não opina", "só aponta"), já que subagente sem limite explícito tende a fazer mais do que devia.
Quatro coletores de evidência em paralelo
A primeira etapa do "porquê" é juntar evidência, e cada fonte fica com um especialista. O leitor-relatorio lê os CSVs de métricas e extrai os sinais do mês; o leitor-release busca a divulgação do IPCA na API de notícias do IBGE e lê o caderno em PDF; o reporter-noticias varre o noticiário e devolve manchetes com veículo e data; e o leitor-ata baixa as três atas mais recentes do Copom e resume a trajetória do discurso do comitê, com citações literais.
Os quatro rodam ao mesmo tempo porque o agente principal os dispara numa única mensagem — o chamado fan-out, o padrão de abrir várias tarefas paralelas de uma vez em vez de esperar uma terminar para começar a outra. O ganho é de tempo: em fila, o total é a soma das quatro coletas; em paralelo, é o tempo da mais lenta.
O paralelo é seguro quando duas condições valem: as tarefas não leem o resultado umas das outras, e cada uma escreve num arquivo diferente. É o caso aqui, porque o que a ata do Copom diz não depende do que saiu no jornal. Os subagentes não conversam entre si; quem junta os resultados e alimenta a etapa seguinte é sempre o agente principal.
Um investigador, três instâncias
Com as evidências na mesa, o pipeline formula três hipóteses para a surpresa — em março: transportes puxados por combustíveis, alimentação, administrados — e testa cada uma. A tentação é criar três arquivos de investigador quase idênticos; o projeto cria um investigador genérico e deixa a hipótese viajar no prompt de cada invocação, como uma função que recebe argumentos. O agente principal invoca o mesmo arquivo três vezes em paralelo, uma instância por hipótese.
Cada investigação sai com veredito (sustentada, parcialmente sustentada ou não sustentada), grau de confiança e as evidências decisivas com a fonte nomeada — inclusive as evidências contra, que um analista criterioso não esconde. Em março, a hipótese dos transportes fechou em "sustentada, confiança alta": o grupo contribuiu sozinho com mais do que a surpresa inteira, embora a alimentação tenha vindo logo atrás, o que mostrou que a surpresa teve dois vetores.
O ciclo redator–checador tem teto
Os dois últimos papéis separam quem escreve de quem confere. O redator lê CSVs, evidências e investigações e produz os cinco textos do relatório; o checador confere se cada número citado existe nos CSVs, se cada citação existe nas evidências e se os sinais são coerentes (surpresa para cima combina com realizado acima da mediana), e devolve um parecer que ou libera a renderização ("ok") ou lista as correções.
Esse ciclo tem um teto de dois turnos, porque dois agentes podem discordar para sempre e pipeline que não termina é pior que pipeline que falha. Na terceira divergência, o processo para e devolve a lista de problemas para o humano decidir. A regra inegociável do checador resume a filosofia do projeto: número sem fonte nos CSVs impede o "ok".
Um comando orquestra tudo: /gerar-relatorio
Cada peça funciona sozinha, e um comando de projeto costura a execução: /gerar-relatorio roda os scripts, dispara os quatro coletores em paralelo, formula as hipóteses, abre as três instâncias do investigador, aciona redator e checador e, com o "ok", renderiza o HTML datado. Falha de script para o pipeline; texto reprovado duas vezes também.
Na execução deste tutorial, os dois scripts imprimiram seus resumos, os quatro coletores subiram juntos, as três investigações rodaram em paralelo e o ciclo redator–checador fechou em dois turnos. A maior parte do tempo ficou nos coletores, que baixam e leem PDFs do Banco Central e do IBGE.
O relatório que saiu da máquina
No HTML final, os gráficos calculados pelos scripts aparecem lado a lado com a leitura escrita pelos agentes. A síntese que abriu o relatório de março, escrita pelo redator e aprovada pelo checador, diz que o IPCA de 0,88% superou a mediana Focus de 0,60% em +0,28 ponto percentual, a maior surpresa altista dos doze meses da série, e aponta o vetor central: a alta de 13,90% do diesel, associada ao conflito no Oriente Médio, encareceu o frete e pressionou ao mesmo tempo os transportes e os alimentos — um canal de transmissão que o mercado não havia precificado.
Cada número desse parágrafo tem endereço. O 0,88% e o 0,60% estão no CSV da surpresa; a sequência de surpresas altistas sai das doze linhas do mesmo arquivo; o diesel de 13,90% vem dos arquivos de evidência. O parecer do checador registra a conferência valor a valor, e é essa rastreabilidade que separa um relatório gerado por IA de um relatório defensável gerado por IA: se um leitor duvidar de qualquer afirmação, o caminho está escrito — texto, investigação, evidência, CSV, API oficial.
O ciclo de correção trabalhou nessa execução. A primeira rodada do redator contou errado as surpresas altistas anteriores e citou um valor que não batia com o CSV; o checador pegou as duas falhas, devolveu o parecer com a lista, e a segunda rodada saiu aprovada. É o teto de dois ciclos fazendo o que promete: barrar número errado antes de ele virar relatório publicado.
No mês seguinte, quando o IBGE divulgar o próximo IPCA, o relatório inteiro se refaz com o mesmo comando: novos dados, novos gráficos, nova investigação e novos textos. O que não muda é a estrutura — scripts calculando os números, agentes investigando as causas por trás deles.
Considerações finais
Este pipeline resolve o problema central de automatizar relatórios com IA, que é manter cada número conferível. A divisão de trabalho faz isso sozinha: o cálculo fica em código, cujo resultado é o que a API oficial devolveu, enquanto o julgamento vai para agentes com papéis definidos, limites explícitos e um checador no fim. Com isso, o relatório se refaz a cada divulgação sem perder a rastreabilidade de nenhuma afirmação.
A mesma arquitetura — fontes oficiais, métricas em arquivos conferíveis, agentes investigando variações e um ciclo de checagem antes de publicar — se transporta para qualquer rotina que combine números e narrativa:
- Economistas: relatórios de conjuntura, monitores de inflação e de atividade que se atualizam a cada divulgação, com todo número rastreável ao dado oficial e a análise investigada por hipótese.
- Administradores: relatórios gerenciais em que planilhas e sistemas calculam vendas, custos e indicadores, e o time de agentes investiga por que o mês desviou da meta antes de o texto circular na diretoria.
- Contadores: fechamentos mensais e análises de variação de receitas e despesas em que a explicação de cada linha é conferida contra os números de origem antes de ir ao cliente.
O passo seguinte é praticar: montar as pastas, escrever os subagentes com seus limites e rodar o comando de orquestração sobre um relatório que você já produz hoje.
Você viu a arquitetura; aprenda a construí-la
Na Imersão Claude Code para economistas, administradores e contadores, você constrói este e outros projetos passo a passo: scripts, subagentes, comandos de orquestração e o relatório rodando na sua máquina. Quem quer acesso a todos os cursos e formações da casa tem o AM Black, a assinatura anual.
Leia também:
