Como construir um agente de IA com LangGraph para automatizar agendamentos

Como construir um agente de IA com LangGraph para automatizar processos de agendamento

Em 2026, a diferença entre um chatbot e um agente de IA ficou clara na prática. Enquanto chatbots respondem mensagens, agentes gerenciam processos de negócio completos — extraem informações de conversas naturais, calculam preços, verificam disponibilidade e confirmam agendamentos. Este tutorial mostra como construir um agente assim usando Python, LangGraph e LangChain, baseado em um caso real: substituir 15 minutos de troca de mensagens com um cliente por uma interação autônoma de ponta a ponta.

✅ O que você ganha

• Um agente stateful capaz de manter contexto entre múltiplas mensagens do cliente
• Extração automática de detalhes de serviço a partir de linguagem natural
• Cálculo de preços e verificação de disponibilidade sem intervenção humana
• Observabilidade completa com LangFuse para monitorar cada execução
• Código-fonte aberto pronto para testar e estender

⚠️ O que você NÃO ganha

• Não é um substituto imediato para produção — requer adaptações para bancos de dados reais e integração com calendários
• Não inclui interface frontend pronta (web, mobile ou WhatsApp)
• Depende de API OpenAI, embora com custo quase insignificante por execução

Pré-requisitos

Passo 1: Entenda o que o agente faz

O agente substitui um atendente humano de uma empresa de limpeza. Ele é capaz de:

• Responder perguntas do cliente e entender suas necessidades
• Extrair informações como tipo de serviço, tamanho do imóvel, endereço e serviços extras
• Calcular o preço com base nos detalhes extraídos
• Lidar com aceitação ou rejeição do orçamento pelo cliente
• Propor horários otimizados e confirmar o agendamento

A vantagem sobre um formulário tradicional é a flexibilidade. Um cliente pode escrever “Preciso de limpeza para meu apartamento de 2 quartos, também quero que limpem dentro da geladeira, estou disponível terça e quarta” — e o agente entende que não precisa fazer mais perguntas, indo direto para o cálculo do preço.

Passo 2: Estruture os detalhes do serviço com Pydantic

O coração do agente é a extração de informações da conversa para um formato estruturado. Usamos Pydantic para definir o modelo BookingDetails:

from pydantic import BaseModel, Field
from enum import Enum

class ServiceType(str, Enum):
    HOUSE = "house"
    APARTMENT = "apartment"  
    COUCH = "couch"

class CleaningDepth(str, Enum):
    BASIC = "basic"
    DEEP = "deep"

class BookingDetails(BaseModel):
    """Informações extraídas da conversa."""
    service_type: ServiceType | None = Field(default=None)
    size_info: float | None = Field(default=None, gt=0)
    cleaning_depth: CleaningDepth | None = Field(default=None)
    add_ons: list[str] = Field(default_factory=list)
    address: str | None = Field(default=None)
    is_complete: bool = False
    next_question: str | None = Field(
        default=None, exclude=True,
        description="Pergunta concisa sobre a informação que ainda falta"
    )

O campo next_question é crucial: o agente só pergunta quando há informação faltando. Se todos os campos obrigatórios estiverem preenchidos, is_complete vira True e o fluxo avança para o cálculo de preço.

Passo 3: Monte o grafo com LangGraph

O LangGraph é usado porque o fluxo de agendamento precisa de estado compartilhado e deve resumir entre múltiplas mensagens. O estado é um TypedDict:

from typing import TypedDict, NotRequired
from langgraph.graph.message import AnyMessage, add_messages

class AgentState(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]
    booking_details: BookingDetails
    calculated_price: NotRequired[float | None]
    time_options: NotRequired[list[TimeOption]]
    selected_slot: NotRequired[TimeOption | None]
    status: BookingStatus
    booking_id: NotRequired[str | None]

O LangGraph gerencia o estado durante a execução do grafo. Cada nó lê o estado atual e retorna atualizações parciais. As funções de roteamento condicional inspecionam o estado para decidir qual nó executar em seguida:

from langgraph.graph import StateGraph, END

graph = StateGraph(AgentState)

# Nó de cálculo de preço
def calculate_price_node(state: AgentState) -> dict:
    return {
        "calculated_price": calculate_price(
            state["booking_details"]
        )
    }

graph.add_node("calculate_price", calculate_price_node)

# Roteamento condicional: continuar para preço ou encerrar turno
def should_continue_to_pricing(state: AgentState) -> str:
    if state["booking_details"].is_complete:
        return "calculate_price"
    return "end"

graph.add_conditional_edges(
    "gather_info",
    should_continue_to_pricing,
    {"calculate_price": "calculate_price", "end": END}
)

Se os detalhes estiverem completos, a execução continua para o nó de preço. Caso contrário, o grafo encerra o turno atual e espera a próxima mensagem do cliente.

Passo 4: Adicione observabilidade com LangFuse

A parte mais crítica de qualquer sistema em produção é a observabilidade. Sem ela, você depende de sorte para resolver problemas. O LangFuse é uma plataforma open-source de engenharia de IA que oferece tracing, monitoramento e debugging para aplicações com LLMs:

import os
from langfuse.langchain import CallbackHandler

def create_langfuse_handler():
    """Retorna handler configurado quando credenciais estão disponíveis."""
    if not os.getenv("LANGFUSE_PUBLIC_KEY") or not os.getenv("LANGFUSE_SECRET_KEY"):
        return None
    return CallbackHandler()

O dashboard do LangFuse mostra cada execução com detalhes de prompts, inputs, outputs, uso de tokens e custo — essencial para detectar rapidamente quando algo sai do orçamento esperado.

Passo 5: Execute e estenda

O projeto inclui uma CLI simples para testar o fluxo de agendamento completo. Com uma chave de API OpenAI, o custo por execução é quase zero.

Extensões possíveis a partir da base modular:

• Interfaces frontend (web, mobile, WhatsApp)
• Banco de dados de produção como PostgreSQL
• Conexão direta com calendários reais e serviços de localização
• Notificações automáticas para prestadores de serviço

Casos de uso reais

• Serviços de limpeza e manutenção: orçamento e agendamento automático com base em conversa natural
• Clínicas e consultórios: triagem de sintomas e agendamento de consultas por WhatsApp
• Locação de equipamentos: cotação de diárias com cálculo de frete baseado em CEP
• Buffet e eventos: orçamento personalizado com número de convidados, cardápio e data
• Suporte técnico: diagnóstico guiado com abertura de chamado e agendamento de visita técnica

Comparação de abordagens

Troubleshooting

❌ O agente sempre pergunta a mesma coisa, mesmo com informação suficiente
→ Verifique se o campo is_complete está sendo atualizado corretamente no nó gather_info. O LLM pode não estar preenchendo todos os campos obrigatórios.

❌ Estado se perde entre mensagens do cliente
→ Confirme que o checkpointer está configurado ao compilar o grafo. Sem ele, o estado é volátil.

❌ LangFuse não aparece no dashboard
→ Verifique se as credenciais LANGFUSE_PUBLIC_KEY e LANGFUSE_SECRET_KEY estão no .env e se flush() está sendo chamado após cada execução.

❌ Custo da API OpenAI acima do esperado
→ Monitore o dashboard do LangFuse para identificar execuções anômalas. Considere usar modelos mais baratos como GPT-4o-mini para extração de informações.

❌ Erro de importação do LangGraph
→ Instale com pip install langgraph langchain langchain-openai. Verifique a compatibilidade de versões entre LangGraph e LangChain.

FAQ

Preciso de GPU para rodar este agente?
Não. Todo o processamento pesado é feito via API OpenAI. O código local apenas gerencia o estado e a lógica de negócio.

Funciona com modelos open-source como Llama?
Sim, desde que o modelo suporte function calling e saída estruturada. Basta trocar o provider no LangChain.

Quanto custa por agendamento?
Com GPT-4o-mini, o custo é de frações de centavo de dólar por conversa completa. O autor relata custo quase zero por execução.

Posso usar em produção imediatamente?
Não. O MVP atual usa armazenamento em memória (MemorySaver). Para produção, você precisa migrar para PostgreSQL e integrar calendários reais.

Qual a diferença entre LangGraph e CrewAI para este caso?
LangGraph é mais adequado para agentes stateful com fluxo condicional complexo. CrewAI é melhor para orquestração de múltiplos agentes especialistas. Para um agente único que gerencia estado entre interações, LangGraph é a escolha natural.

O futuro dos agentes de agendamento

Em 2027, agentes como este estarão integrados diretamente no WhatsApp Business, Instagram Direct e sistemas de CRM. A tendência é que pequenas e médias empresas adotem agentes de IA não como diferencial competitivo, mas como requisito básico de operação — assim como aconteceu com sites e redes sociais na década passada. Começar a construir essa competência agora, com ferramentas como LangGraph e LangFuse, é investir no que será o padrão de atendimento em menos de dois anos.