Você já tentou agendar um serviço por mensagem e ficou preso naquele vai e vem interminável de perguntas?
Tamanho do sofá, material, endereço, tipo de limpeza, horário disponível… são vários minutos trocando mensagem com um atendente até finalmente confirmar o agendamento. No caso que inspirou esse projeto, o processo inteiro de solicitar um orçamento para limpeza de um sofá e, em seguida, para limpeza de um apartamento levou cerca de 15 minutos de conversa. É frustrante para o cliente e caro para o negócio, que precisa manter pessoas disponíveis só para coletar informações básicas e confirmar horários.
Um Agente AI construído com LangGraph e Python consegue resolver exatamente esse problema, e faz isso em segundos. Não estamos falando de um chatbot simples que segue um roteiro fixo de perguntas, daqueles que travam quando o usuário responde algo fora do esperado.
Estamos falando de um agente com estado, capaz de gerenciar um processo de negócio de múltiplas etapas ao combinar inteligência conversacional com regras de negócio determinísticas. Ele entende o que o cliente precisa, calcula preços dinamicamente, propõe horários otimizados e confirma o agendamento, tudo dentro de uma conversa natural. A diferença na experiência do usuário é enorme, e a diferença no custo operacional também. Melhor ainda: uma vez em produção, esse agente trabalha 24 horas por dia, 7 dias por semana, sem pausa.
Ao longo deste artigo você vai ver como esse agente foi construído na prática, passando pela stack técnica com Python, LangGraph e LangChain, por como o processo de agendamento foi modelado em um grafo de estados, pela configuração de observabilidade com Langfuse para monitorar tudo em produção, e pelo potencial real dessa solução como base para um produto comercial. Vale destacar que o código-fonte do projeto está disponível publicamente no GitHub, no repositório chamado customer-service-agent, então você pode clonar e testar por conta própria. Se você tem interesse em ver como agentes de IA funcionam além da teoria, esse aqui é um exemplo bem concreto do que já dá pra construir hoje. 🚀
O Que Esse Agente Realmente Faz
Antes de entrar na parte técnica, vale entender o escopo do agente. Ele faz tudo aquilo que um atendente humano de uma empresa de limpeza faria no dia a dia. Ele responde às dúvidas do cliente e entende o que a pessoa precisa, calcula o preço do serviço e informa esse valor de forma clara, lida com a aceitação ou recusa da proposta pelo cliente, sugere horários otimizados para o agendamento e, por fim, confirma e registra o compromisso.
- E-BOOK GRATUITO
Um guia prático para avaliar, comparar e implementar inteligência artificial com clareza — sem desperdício de tempo ou dinheiro.
Pare de contratar ferramentas sem direção. Criamos um método estruturado para decidir qual IA realmente faz sentido para o seu negócio.
Entrega em PDF no seu e-mail · Sem spam · LGPD
🔒 Seus dados são protegidos conforme a LGPD. Você pode descadastrar a qualquer momento.
A grande vantagem em relação a um formulário tradicional é a flexibilidade. Poderíamos construir uma ferramenta de cotação que faz um conjunto fixo de perguntas e, depois que o cliente aprova o preço, agenda automaticamente. Isso funcionaria, mas obrigaria todo mundo a seguir exatamente o mesmo caminho engessado.
Com um Agente AI, a experiência fica bem mais natural. Imagine um cliente escrevendo algo assim: preciso de uma limpeza para meu apartamento de dois quartos neste endereço, quero também que limpem o interior da geladeira, e estou disponível na terça ou na quarta. Essa única mensagem já contém todas as informações necessárias. Um bom agente entende que não precisa fazer mais nenhuma pergunta nem obrigar o cliente a repetir dados num formulário, e parte direto para calcular e apresentar o orçamento. Além disso, ele tem potencial para orquestrar operações extras, como avisar os profissionais de limpeza sobre novos agendamentos ou procurar alguém disponível nas proximidades para um pedido urgente.
A Stack por Trás do Agente: Python, LangGraph e LangChain
A escolha da stack técnica não foi por acaso. Python continua sendo a linguagem mais madura para trabalhar com inteligência artificial, especialmente quando o objetivo é integrar modelos de linguagem com lógica de negócio real. O ecossistema de bibliotecas, a facilidade de prototipagem e a quantidade de profissionais que dominam a linguagem fazem dela a escolha mais prática para projetos desse tipo. Além disso, praticamente todas as grandes ferramentas de IA têm suporte nativo para Python, o que elimina camadas desnecessárias de adaptação.
O LangGraph entra como o componente central da arquitetura. Ele é uma extensão do LangChain projetada especificamente para construir agentes com controle de fluxo mais sofisticado, usando o conceito de grafos de estado. Na prática, isso significa que cada etapa da conversa é um nó dentro de um grafo, e o agente sabe exatamente em qual ponto do processo de agendamento ele está, quais informações já foram coletadas e qual é o próximo passo lógico. O motivo principal para usar o LangGraph é que o fluxo de agendamento precisa de estado compartilhado e precisa ser retomado ao longo de várias mensagens do cliente. Por isso, precisamos de um agente com estado, e não de um simples fluxo linear.
O LangChain, por sua vez, funciona como a cola entre as peças. Ele facilita a integração com os modelos de linguagem, o gerenciamento de memória e a criação das ferramentas que o agente utiliza para executar ações concretas, como verificar disponibilidade de horários, calcular o valor do serviço com base nas informações coletadas ou registrar o agendamento. Juntos, esses três elementos formam uma base técnica sólida o suficiente para ir direto do protótipo para um ambiente de produção sem grandes refatorações.
Como o Processo de Agendamento Vira um Grafo de Estados
Modelar o processo de agendamento como um grafo de estados é o que diferencia essa abordagem de qualquer chatbot tradicional. Em vez de uma sequência linear de perguntas pré-programadas, o LangGraph permite definir nós que representam etapas do processo, como coletar informações do serviço, calcular o preço, propor horários e confirmar o agendamento, e arestas que definem as transições entre esses nós com base no estado atual da conversa.
O ponto de partida é sempre a interação entre o cliente e o agente. Conversando, o agente tenta obter todas as informações necessárias para o serviço. O resultado desse primeiro bate-papo são os detalhes do agendamento, que o agente converte em uma saída estruturada para que possam ser usados depois pelos mecanismos de preço e de reserva. Esses detalhes são representados por uma classe em Python, tipada com Pydantic, que contém campos como o tipo de serviço, o tamanho do ambiente ou a quantidade de assentos no caso de um sofá, a profundidade da limpeza, os serviços adicionais e o endereço. Todos os campos são opcionais, porque essa mesma estrutura também representa uma extração parcial de informações ao longo da conversa.
Um detalhe importante é que o agente só faz uma nova pergunta quando ainda falta algum dado. Assim, é o próprio agente que decide o que acontece a seguir, e esse ponto é justamente o que separa um Agente AI de um fluxo de trabalho comum. Na prática, se o cliente já mencionou o endereço no início da conversa, o agente não vai perguntar de novo. Se o cliente mudou de ideia sobre o horário, o agente consegue retroceder no fluxo sem perder as outras informações já coletadas.
O estado do agente é definido como uma estrutura tipada que carrega as mensagens da conversa, os detalhes do agendamento, o preço calculado, as opções de horário, o horário selecionado, o status atual e o identificador da reserva. O LangGraph gerencia esse estado durante a execução do grafo. Cada nó lê o estado atual e retorna atualizações parciais, enquanto funções de roteamento condicional inspecionam esse estado para decidir qual nó roda em seguida.
A lógica de cálculo de preço também vive dentro desse grafo, em um nó específico que lê os detalhes do agendamento e retorna o preço por meio de uma função determinística em Python. Isso é importante porque garante consistência nas cotações e evita alucinações do modelo em etapas onde a precisão é crítica. Depois que o nó de coleta de informações roda, uma função de roteamento condicional verifica se há dados suficientes para calcular o preço. Se os detalhes estiverem completos, a execução segue para o nó de precificação. Caso contrário, o grafo encerra o turno atual e espera por outra mensagem do cliente. Por fim, o grafo é compilado com um checkpointer, que garante a persistência do estado entre as interações.
Observabilidade em Produção com Langfuse
Colocar um Agente AI em produção sem observabilidade é como dirigir vendado. Você pode até chegar ao destino nas primeiras vezes, mas na primeira coisa que der errado você não vai saber onde, por que ou como corrigir. E é certo que qualquer sistema em produção terá problemas em algum momento, seja uma linha de produção numa fábrica, um modelo tradicional de machine learning detectando anomalias ou um agente de IA em operação. Sem visibilidade sobre o que acontece dentro do sistema, você acaba dependendo de pura sorte para resolver qualquer questão.
Por isso, a configuração do Langfuse foi tratada como parte essencial da arquitetura desde o início, e não como um recurso opcional para adicionar depois. O Langfuse é uma plataforma open source de engenharia de IA projetada para rastreamento, monitoramento, avaliação e depuração de aplicações com modelos de linguagem. O plano gratuito já é suficiente para testar um projeto como esse: basta gerar as chaves secreta e pública no painel do Langfuse e colá-las no arquivo de variáveis de ambiente, junto com a URL base do serviço.
Com o Langfuse integrado ao LangGraph via callbacks do LangChain, é possível visualizar a trajetória completa de uma conversa dentro do grafo de estados. O painel mostra os prompts, as entradas e as saídas, além do uso de tokens e do custo de cada interação, o que torna muito fácil detectar qualquer situação inesperada no orçamento. No começo, o painel pode parecer complicado, mas depois que você começa a usar, tudo fica bem mais intuitivo.
Receba o melhor conteúdo de inovação em seu e-mail
Todas as notícias, dicas, tendências e recursos que você procura entregues na sua caixa de entrada.
Ao assinar a newsletter, você concorda em receber comunicações da Método Viral. A gente se compromete a sempre proteger e respeitar sua privacidade.
Outro benefício direto da observabilidade com Langfuse é o controle de custos. Como cada chamada ao modelo é registrada com o número de tokens utilizados, fica fácil identificar nós do grafo que estão consumindo mais do que deveriam, seja por prompts mal otimizados ou por chamadas desnecessárias ao modelo em situações onde uma função determinística em Python resolveria com muito mais eficiência. Vale destacar que o custo de rodar esse agente é praticamente irrisório: uma única execução completa do fluxo custa centavos, o que torna a solução extremamente viável mesmo em escala.
O Potencial Real dessa Solução
O que foi construído aqui vai muito além de um exemplo técnico interessante. O projeto inclui uma interface de linha de comando simples para testar o fluxo de agendamento de ponta a ponta, mas seu design modular abre um espaço enorme para melhorias. Todo componente tem acesso ao estado central do agente, o que facilita bastante a extensão do sistema.
Entre as possibilidades de expansão previstas pelo próprio criador do projeto estão a adição de interfaces de frontend, como aplicações web, apps mobile ou plataformas de mensagem como o WhatsApp, a integração com um banco de dados de produção como o PostgreSQL, e conexões diretas com calendários reais de funcionários e serviços baseados em localização. A combinação de LangGraph, Python e um sistema de observabilidade como o Langfuse entrega uma base arquitetural que pode ser adaptada para qualquer tipo de serviço que envolva agendamento com coleta de informações variáveis, como clínicas, salões de beleza, empresas de manutenção, serviços domésticos e consultorias.
Do ponto de vista do produto, o que mais chama atenção é a experiência que essa abordagem entrega para o usuário final. Uma conversa natural, sem formulários, sem menus de opções numeradas, sem aquele bot frustrante que não entende quando você desvia minimamente do roteiro esperado. O cliente descreve o que precisa com suas próprias palavras, e o agente coleta tudo que precisa de forma fluida, confirma o agendamento e encerra a conversa em segundos. Esse nível de experiência, que antes exigia um atendente humano disponível em tempo real, agora pode rodar de forma totalmente automatizada e escalável.
E isso é só o começo. O próprio autor considera essa entrega como uma versão inicial, uma espécie de v0, com planos de adicionar mais funcionalidades por cima dela. Com a evolução contínua dos modelos de linguagem e das ferramentas como o LangGraph, os agentes tendem a ficar cada vez mais capazes de lidar com situações complexas, exceções e preferências individuais dos clientes. O que hoje é uma solução para o processo de agendamento pode amanhã ser expandido para incluir reagendamentos automáticos, lembretes personalizados, histórico de preferências do cliente e integração direta com sistemas de pagamento, tudo dentro da mesma arquitetura de grafo de estados que já está funcionando. O alicerce está construído, e ele é bem sólido. 💪
