Introdução ao LangGraph

Dá para montar um agente de inteligência artificial que responde perguntas sobre a inflação brasileira sem pagar nada por isso. Você pergunta "qual foi o IPCA de março de 2025?" em português, e o programa decide sozinho que precisa consultar a série do Banco Central, faz a consulta e devolve o número certo. O modelo de linguagem roda na sua máquina, na CPU, e ocupa cerca de 1,5 GB.

Este tutorial constrói esse agente com LangGraph, o framework da LangChain para orquestrar aplicações com IA, passando pelos três blocos do framework e pelo ciclo ReAct até um aplicativo web em Streamlit. Sem chave de API em nenhuma etapa.

O bloco "Ver o que o agente fez" mostra que o ciclo deu duas voltas e qual ferramenta devolveu o número, o que num sistema que responde sobre dados deixa de ser detalhe e vira requisito de funcionamento.

Testar o agente agora →
O aplicativo está publicado e aberto: pergunte sobre qualquer mês do IPCA.

O que o LangGraph resolve

Um programa comum executa na ordem que você escreveu, enquanto um modelo de linguagem recebe texto e devolve texto, nem sempre o que você esperava. Uma aplicação que responde sobre dados precisa das duas coisas ao mesmo tempo, porque o modelo tem que interpretar a pergunta do usuário enquanto o sistema garante que a base certa será consultada.

O LangGraph descreve esse fluxo como um grafo, em que as caixas são as etapas e as setas são as transições possíveis, de forma que você desenha o caminho e o framework o segue.

LangGraph e LangChain são coisas diferentes

O LangChain oferece as peças: interface padronizada para conversar com modelos, definir ferramentas e montar prompts. O LangGraph orquestra essas peças, definindo ordem, condições e ciclos. São pacotes separados, usados quase sempre juntos.

Os três blocos de um grafo

Toda aplicação em LangGraph se apoia em três conceitos, e entendidos esses três o resto passa a ser detalhe de implementação.

O ciclo ReAct, que faz o agente ser um agente

ReAct vem de Reasoning and Acting, raciocinar e agir: em vez de responder de uma vez, o modelo alterna entre decidir o que fazer e observar o resultado do que fez.

A seta de volta merece atenção, porque um programa que chama o modelo uma vez e imprime a resposta funciona como um formulário. O comportamento de agente aparece quando o sistema, depois de ver o resultado da ferramenta, ainda pode chamar outra, repetir a mesma ou encerrar e responder.

O que é uma ferramenta

Uma ferramenta é uma função comum do seu programa, descrita para o modelo em JSON Schema: o nome, para que serve e quais argumentos aceita. Essa descrição viaja junto com a pergunta.

O modelo não executa nada por conta própria: no lugar de texto, ele responde algo equivalente a "execute consultar_ipca com o argumento mes = 2025-03", e quem executa é o seu código, que devolve o resultado para o modelo continuar. A escolha fica com o modelo e a execução fica com o programa.

Como o ciclo pode se repetir, ele precisa de um freio, já que um modelo confuso continuaria pedindo ferramenta indefinidamente e o programa nunca terminaria. No nosso agente o limite é de três voltas, verificado pela aresta condicional a cada passagem.

O modelo local: por que um modelo de 0,6 bilhão de parâmetros basta

A maioria dos tutoriais usa a API da OpenAI ou do Gemini, o que exige cadastro, chave e cartão, enquanto aqui o modelo roda na sua máquina, sem custo, sem enviar dados para fora e sem depender de internet depois de baixado.

Usamos o Qwen3-0.6B, um dos menores modelos abertos treinados para tool calling, a capacidade de emitir chamadas de ferramenta em vez de apenas conversar. Cada resposta leva cerca de dez segundos numa CPU comum. Dois ajustes decidem se o projeto funciona nesse tamanho, e os dois vieram de teste, não de manual.

Desligar o modo de raciocínio

O Qwen3 escreve um bloco de pensamento antes de responder, e num modelo de 600 milhões de parâmetros o orçamento de tokens se esgota dentro desse bloco, de modo que a chamada de ferramenta nunca chega a sair. Com o raciocínio ligado, o modelo falhou nas quatro perguntas de teste, e desligando essa opção ele passou a acertar três das quatro.

Instrução afirmativa, nunca negativa

Este resultado é contraintuitivo e vale para qualquer modelo pequeno. Testamos dois prompts de sistema, com o mesmo modelo e a mesma pergunta:

Efeito do prompt de sistema sobre o Qwen3-0.6B, mesma pergunta nos dois casos.

A segunda instrução parece mais segura e produz justamente o comportamento que se queria evitar, porque um modelo pequeno segue a ordem ao pé da letra e "diga que não sabe" é uma ação bem mais barata do que consultar uma base. Modelos grandes absorvem esse tipo de frase sem prejuízo, mas os pequenos passam a se apoiar nela.

Quem faz o que: a divisão que salva o projeto

A escolha central do tutorial está em repartir as tarefas entre o modelo e o código, deixando para cada um o que ele resolve melhor.

Essa divisão resolve o principal defeito do modelo pequeno, que nos testes escolhia a ferramenta certa e errava o formato da data, devolvendo 01-01 para "janeiro de 2024" e apenas 06 para "junho de 2026". Em vez de insistir no prompt, o código reconstrói a data lendo o mês e o ano do texto da pergunta, e com essa correção os seis casos de teste passaram.

Um segundo mecanismo cobre a falha oposta: quando a pergunta cita um mês concreto e o modelo tenta responder de cabeça, o programa ignora esse texto e força a consulta à base. A regra de negócio manda no fluxo, e o modelo não tem a última palavra sobre o número.

Como o agente foi montado

O projeto se divide em quatro etapas, cada uma num módulo separado, e é essa separação que permite testar a camada de dados sem envolver o modelo de linguagem.

Um aviso sobre a versão do framework: o LangGraph chegou ao 1.0 e a função create_react_agent, do módulo langgraph.prebuilt, foi descontinuada em favor do create_agent, agora no pacote langchain. Boa parte do material na internet ainda ensina a API antiga. Aqui o grafo é montado à mão, o que deixa o ciclo visível em vez de escondido dentro de uma função pronta.

Os resultados

O agente foi testado em sete perguntas, incluindo as que deveriam falhar, e todas se comportaram como o desenho previa.

Bateria de testes do agente. Fonte: BCB (SGS, série 433), com dados até julho de 2026.

Os dois últimos casos merecem atenção, porque um agente que serve para alguma coisa precisa dizer que não tem o dado em vez de inventar um número, e precisa deixar a ferramenta quieta quando a pergunta não é sobre inflação.

O acumulado está em 4,44%, acima da meta de 3,0% e dentro do intervalo de tolerância, cujo teto é 4,5%. O número não foi digitado à mão em lugar nenhum, porque sai do produto dos fatores mensais calculado pela ferramenta, já que a inflação de um mês incide sobre os preços corrigidos pelo mês anterior e somar as variações daria um valor diferente.

Considerações finais

Um modelo de 0,6 bilhão de parâmetros não substitui um modelo de fronteira, e o que este exercício mostra é outra coisa: num agente bem desenhado, o modelo carrega uma parcela pequena da responsabilidade, que é interpretar a pergunta e escolher a ferramenta, enquanto a precisão do número vem do código.

Isso muda o cálculo de quem trabalha com dados econômicos. Se a exatidão depende da sua função de consulta, e não da memória do modelo, o custo cai porque um modelo pequeno resolve, a auditoria fica possível porque cada número tem origem rastreável, e o sistema fica testável porque as ferramentas são funções Python comuns.

Os dois mecanismos de proteção deste tutorial seguem o mesmo princípio: deixe o modelo fazer o que ele faz bem, que é lidar com linguagem, e deixe o código fazer o que ele faz bem, que é aplicar regra determinística.

Para quem isso é útil

• Analista macro — um assistente que responde sobre séries do BCB e do IBGE sem sair da mesa, com o dado rastreável até a fonte.
• Economista de instituição — o modelo local mantém dado sensível dentro da máquina, sem enviar nada para servidor de terceiro.
• Profissional de risco e compliance — cada resposta registra qual ferramenta foi chamada e o que ela devolveu, o que torna o sistema auditável.
• Quem está começando em Python — o projeto cobre coleta de dados, funções, estruturas de controle e uma interface web, num caso concreto.