Pular para conteúdo

Visão geral

O padrão OTIMUS AgentProIA descreve como construir um chatbot WhatsApp que intermedia agendamento de consultas e exames clínicos entre o paciente e o sistema OTIMUS da clínica.

O que o chatbot faz

Em linhas gerais, para cada mensagem recebida no WhatsApp da clínica:

  1. Recebe webhook do WTS Chat (POST /webhook/message).
  2. Valida se é para o agente (instância, equipe, status da sessão).
  3. Se for mídia (imagem, PDF, áudio), transforma em texto via Gemini/Whisper.
  4. Enfileira a mensagem em PostgreSQL com um debounce (2s – 10s).
  5. Após o debounce, agrega todas as mensagens do mesmo paciente no intervalo.
  6. Verifica anti-overlap (só a sessão mais recente processa).
  7. Executa o agente LangGraph ReAct com histórico persistido.
  8. O agente decide chamar uma das tools:
    • consultar_horarios(medico, procedimento, convenio)
    • agendar_consulta(nome, cpf, nascimento, médico, data, hora, procedimento, convenio)
    • transferir_atendimento(motivo)
  9. A tool chama a API OTIMUS (4 endpoints possíveis).
  10. A resposta do agente é dividida por \n\n e enviada em partes ao paciente.

Fluxo ponta-a-ponta

sequenceDiagram
    participant U as Usuário (WhatsApp)
    participant WTS as WTS Chat
    participant API as FastAPI
    participant WF as Workflow
    participant AG as Agente (LLM)
    participant OT as OTIMUS API
    participant DB as PostgreSQL

    U->>WTS: "Quero agendar USG abdome"
    WTS->>API: POST /webhook/message
    API->>WF: run_workflow (thread)
    API-->>WTS: 202 accepted
    WF->>WF: filtra + processa mídia
    WF->>DB: INSERT fila_mensagens
    WF->>WF: sleep(debounce)
    WF->>DB: SELECT + DELETE fila do telefone
    WF->>AG: invoke(mensagem agregada)
    AG->>AG: raciocina (ReAct)
    AG->>OT: POST /agendamento/horarios
    OT-->>AG: lista de horários
    AG->>AG: formata resposta
    AG-->>WF: "Temos terça às 14h..."
    WF->>WTS: send_message (parte 1)
    WF->>WTS: send_message (parte 2)
    WTS->>U: mensagens

Componentes obrigatórios

Componente Responsabilidade Projeto de ref
server.py FastAPI — webhooks de entrada e saída ambos
workflow.py LangGraph entrypoint, filtros, debounce, mídia, anti-overlap ambos
agent.py Definição do agente ReAct, tools, system prompt ambos
scheduling.py / agendamento.py Integração OTIMUS (cliente + regras) ambos
wts_client.py Cliente FlowChat/WTS Chat (enviar, transferir, fetch session) ambos
processors.py Gemini OCR (imagem/PDF) + Whisper (áudio) ambos
tracking.py Dashboard de telemetria (sessões, tokens, erros, tags) ambos
db.py Operações de fila de mensagens no Postgres ambos
config.py Centralização de variáveis de ambiente ambos
init.sql Schema: fila + chat_history + dashboard_* ambos

Stack de dependências-chave

fastapi
uvicorn
langchain-openai
langgraph
langgraph-checkpoint-postgres
psycopg[binary]
google-generativeai
openai                # Whisper
requests
python-dotenv

Conceitos que você precisa dominar

  • ReAct agent (LangGraph): create_react_agent(llm, tools, prompt, checkpointer).
  • Checkpointer PostgresSaver: persiste o histórico de cada thread_id (normalmente session_id do WTS) em Postgres.
  • Contextvars: tools não recebem session_id ou phone como parâmetros — elas leem de contextvars.ContextVar setados antes do invoke.
  • Debounce de mensagens: quando o paciente envia 3 mensagens em 2 segundos, o agente só roda uma vez com texto agregado.
  • Anti-overlap: se uma sessão foi enfileirada e outra chegou depois pelo mesmo telefone, só a mais recente dispara.
  • Split por \n\n: resposta do agente vira N mensagens WhatsApp.