Como construir uma interface Streamlit para seu agente LangGraph

Por que isso importa agora

Em 2026, construir agentes de IA não é mais privilégio de grandes estúdios de software. Frameworks como LangGraph permitem orquestrar fluxos complexos de agentes com algumas dezenas de linhas de código Python, e o Streamlit transforma esses agentes em interfaces utilizáveis em minutos. Mas a ponte entre os dois ainda é pouco documentada — a maioria dos tutoriais ou cobre o backend do agente ou o frontend da interface, raramente os dois juntos.

O tutorial de Soner Yıldırım no Towards Data Science preenche exatamente essa lacuna: um passo a passo completo de como construir uma interface Streamlit para um agente LangGraph, com persistência de memória, streaming de tokens e seleção dinâmica de ferramentas.

O que o tutorial entrega

O projeto construído no tutorial é um agente de busca de dados meteorológicos com as seguintes capacidades:

• Busca por clima atual de qualquer cidade usando a API OpenWeatherMap
• Streaming de tokens — o usuário vê a resposta do LLM sendo gerada em tempo real, caractere por caractere
• Persistência de memória — o agente lembra do contexto de conversas anteriores via MemorySaver do LangGraph
• Seleção dinâmica de ferramentas — o agente decide quando usar a ferramenta de clima e quando responder diretamente
• Interface completa com barra lateral de configuração, área de chat com scroll automático e indicador de status do agente

Arquitetura do agente

O fluxo do LangGraph usado no tutorial segue este grafo:

1. Nó de agente: recebe a mensagem do usuário, chama o LLM (GPT-4o) com as ferramentas disponíveis
2. Nó de ferramentas: executa a chamada de API quando o agente decide usar get_current_weather
3. Aresta condicional: decide se continua processando ferramentas ou retorna a resposta final

O MemorySaver do LangGraph atua como um checkpoint que persiste o estado da conversa entre execuções. Isso permite que o agente mantenha contexto em sessões longas — essencial para qualquer aplicação real.

A interface Streamlit

O Streamlit foi escolhido por sua simplicidade: a interface inteira é construída em um único script Python de aproximadamente 200 linhas. Os componentes principais incluem:

• Barra lateral (sidebar): campo para chave da API OpenWeatherMap, controle deslizante de temperatura do LLM e botão para limpar histórico
• Área de chat: renderização de mensagens com st.chat_message, diferenciando visualmente o usuário do agente
• Indicador de status: spinner com mensagens como “Buscando dados meteorológicos…” enquanto a ferramenta está em execução
• Captura de erros: tratamento de falhas na API, erros de conexão e respostas inesperadas do LLM

Pontos técnicos que fazem diferença

Alguns detalhes de implementação que merecem atenção:

• Streaming com astream_events: o tutorial usa o método astream_events do LangGraph (modo “messages”) para capturar tokens do LLM em tempo real e exibi-los no Streamlit via st.write_stream
• Tool calling declarativo: as ferramentas são definidas como funções Python com docstrings e anotações de tipo — o LangGraph gera automaticamente o schema JSON para o LLM
• Estado tipado: o estado do agente é uma subclasse de TypedDict do Python, com campos messages (lista de mensagens do LangChain) e city (última cidade consultada)

Limitações a considerar

• O agente usa GPT-4o como LLM padrão — para uso local, seria necessário adaptar para modelos open-source como Llama 4 ou Kimi K3
• A única ferramenta disponível é a busca de clima — o padrão de grafo, no entanto, é extensível para múltiplas ferramentas
• O Streamlit é single-session por padrão — para produção com múltiplos usuários, seria necessário adicionar gerenciamento de sessões
• A memória é volátil (em memória RAM) — para persistência real entre reinicializações, seria necessário um backend como SQLite ou Redis

Para quem este tutorial é útil

Este é um excelente ponto de partida para desenvolvedores que já conhecem Python e querem dar o salto de “faço scripts de IA” para “construo agentes com interface”. Não é para iniciantes absolutos — você precisa entender conceitos como APIs, LLMs e programação assíncrona — mas também não é um tratado acadêmico sobre arquitetura de agentes. É o tutorial pragmático que faltava na documentação.