Construindo um Assistente Bancário Inteligente com LangGraph: Arquitetura Multi-Agente na Prática

Introdução

"

"Desculpe, não entendi. Digite 1 para saldo, 2 para extrato..."

Se você já interagiu com um chatbot bancário, provavelmente reconhece essa frustração. Segundo pesquisa da Gartner, 64% dos clientes preferem não usar chatbots justamente pela rigidez e incapacidade de entender contexto. Mas não precisa ser assim.

Neste artigo, apresento o Banco Ágil: um sistema de atendimento bancário multi-agente que desenvolvi para demonstrar como construir soluções de IA conversacional sofisticadas usando arquitetura moderna e boas práticas de engenharia de software.

O projeto combina orquestração de agentes com LangGraph, Clean Architecture, Domain-Driven Design e uma experiência conversacional natural em português brasileiro.

O Problema

Atendimentos bancários digitais tradicionais sofrem de vários problemas:

Rigidez de fluxo: Chatbots baseados em árvores de decisão são inflexíveis e frustrantes.

Falta de contexto: Cada interação é tratada isoladamente, forçando o usuário a repetir informações.

Experiência fragmentada: Navegar por menus confusos para tarefas simples.

Dificuldade de extensão: Adicionar novas funcionalidades requer reescrever lógica existente.

A Solução

O Banco Ágil resolve esses problemas através de uma arquitetura que separa responsabilidades e permite evolução natural:

Arquitetura multi-agente: Cada domínio de negócio (crédito, câmbio, entrevista) tem um agente especializado que entende profundamente seu contexto.

Grafo de estados: LangGraph gerencia transições e contexto entre agentes de forma explícita e debugável.

Parsing inteligente: Reconhece múltiplas formas de expressar valores e intenções em português brasileiro.

Separação de responsabilidades: Clean Architecture garante que cada camada tenha um propósito claro.

Funcionalidades

Arquitetura do Sistema

O sistema segue uma arquitetura em camadas inspirada em Clean Architecture e Hexagonal Architecture:

┌───────────────────────────────┐
│      PRESENTATION LAYER       │
│        (Streamlit UI)         │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│     ORCHESTRATION LAYER       │
│         (LangGraph)           │
│   • Router                    │
│   • Nodes (Agentes)           │
│   • Edges (Transições)        │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│      APPLICATION LAYER        │
│         (Services)            │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│        DOMAIN LAYER           │
│   (Entities & Value Objects)  │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│    INFRASTRUCTURE LAYER       │
│   (APIs, Repositórios, LLMs)  │
└───────────────────────────────┘

Diagrama de Componentes

O fluxo segue da UI para o Router, que direciona para os agentes especializados (Triagem, Crédito, Entrevista, Câmbio). Cada agente acessa seus respectivos services, que por sua vez interagem com a camada de infraestrutura (repositórios CSV, Tavily API, cliente LLM).

Os Quatro Agentes

O coração do sistema são quatro agentes especializados, cada um responsável por um domínio de negócio. O Router recebe todas as mensagens e direciona para o agente correto. Cada agente pode pausar para aguardar input, encerrar a conversa, ou redirecionar para outro agente.

Responsabilidades

Fluxo de Exemplo: Aumento de Limite

Para ilustrar como os componentes interagem, veja o fluxo completo de um pedido de aumento de limite:

1. Usuário inicia pedindo aumento de limite
2. Triagem solicita CPF e data de nascimento para autenticação
3. Após autenticar, Triagem identifica intenção de crédito e redireciona
4. Crédito informa limite atual (R$ 5.000) e pergunta quanto deseja
5. Usuário pede R$ 15 mil, mas máximo permitido é R$ 10 mil
6. Crédito oferece entrevista para aumentar o teto
7. Entrevista coleta 5 dados financeiros e calcula novo score (780)
8. Com novo score, limite máximo sobe para R$ 20 mil
9. Crédito confirma e atualiza para R$ 15 mil solicitados

Stack Tecnológica

O sistema suporta múltiplos providers de LLM (Groq, Google Gemini, OpenAI) com fallback automático.

Decisões Arquiteturais

Por que LangGraph?

Avaliei diversas alternativas antes de escolher:

Conclusão: LangGraph oferece o equilíbrio ideal entre controle fino e simplicidade para sistemas multi-agente com estado compartilhado e fluxos bem definidos.

Por que Clean Architecture?

A separação em camadas traz benefícios concretos:

Testabilidade: Services podem ser testados isoladamente com mocks, sem subir o grafo inteiro.

Baixo acoplamento: Trocar CSV por PostgreSQL não afeta a lógica de negócio.

Single Responsibility: Cada módulo tem um propósito claro e bem delimitado.

Independência de frameworks: O domínio não conhece LangGraph ou Streamlit.

Por que Streamlit?

Para um projeto que prioriza demonstrar lógica de negócio sobre interface, Streamlit permite focar no essencial com desenvolvimento rápido e deploy gratuito.

Padrões de Design Utilizados

Lições Aprendidas

1. Gerenciamento de Estado entre Turnos

O LangGraph executa o grafo completamente a cada invocação. Para manter contexto em conversas multi-turno, implementei um flag awaiting_input que sinaliza ao grafo para pausar e aguardar input do usuário. Combinado com MemorySaver, o estado persiste naturalmente entre invocações.

2. Prevenção de Loops Infinitos

Ao redirecionar entre agentes, a mensagem anterior era reprocessada, causando loops. A solução foi um flag just_redirected que indica primeiro turno no novo agente: ele mostra seu menu e ignora a mensagem que causou o redirecionamento.

3. Parsing Flexível de Inputs

Usuários brasileiros expressam valores de formas muito variadas: "5000", "5.000", "R$ 5.000,00", "5mil", "5k", "cinco mil". Criei um parser dedicado que normaliza texto e reconhece múltiplos padrões, incluindo números por extenso. Isso melhora drasticamente a experiência conversacional.

4. Resiliência em Integrações Externas

APIs de cotação podem falhar. Implementei fallbacks em cascata: cache fresco → API principal → cache stale. O usuário sempre recebe uma resposta, mesmo que seja uma cotação de alguns minutos atrás.

5. System Prompts Efetivos

Prompts estruturados com seções claras (Identidade, Tom de Voz, Regras, Restrições) produzem respostas mais consistentes do que instruções soltas. A estrutura ajuda o modelo a "lembrar" do contexto mesmo em conversas longas.

Boas Práticas Aplicadas

Código

• Type hints em todo o código com mypy strict
• Pydantic para validação de entidades e configurações
• Logging estruturado com contexto (agent, cpf_masked)
• Exceções de domínio específicas

Segurança

• CPF nunca aparece completo em logs (mascaramento)
• Limite de 3 tentativas de autenticação
• API keys protegidas com SecretStr

Testes

• Suite completa com pytest
• Cobertura com relatório HTML
• Isolamento total entre testes

Conclusão

O Banco Ágil demonstra que é possível construir sistemas conversacionais sofisticados mantendo qualidade arquitetural. A combinação de LangGraph para orquestração, Clean Architecture para organização, e Pydantic para validação resulta em um sistema modular, testável e extensível.

Principais aprendizados:

1. Grafos de estado oferecem controle superior a chains lineares para fluxos complexos
2. Separação de responsabilidades facilita manutenção e evolução
3. Parsing robusto é essencial para UX conversacional em português
4. Fallbacks em cascata garantem resiliência em integrações externas

Referências

• LangGraph Documentation
• Clean Architecture - Robert C. Martin
• Domain-Driven Design - Eric Evans
• Pydantic Documentation
• Streamlit Documentation

Desenvolvido por Alexsander Valente: 2026