Arquitetura

Um projeto OTIMUS AgentProIA é um serviço Python único empacotado em Docker que expõe endpoints HTTP e mantém estado em PostgreSQL. Abaixo, cada camada com responsabilidade e arquivos-fonte correspondentes.

Visão em camadas

flowchart TB
    subgraph Ingress [Camada de ingresso]
        SV[server.py<br/>FastAPI]
    end

    subgraph Orchestration [Camada de orquestração]
        WF[workflow.py<br/>LangGraph Functional API]
        PR[processors.py<br/>Gemini / Whisper]
        DB[db.py<br/>Fila de mensagens]
    end

    subgraph Agent [Camada do agente]
        AG[agent.py<br/>create_react_agent]
        CTX[contextvars<br/>session / phone / name]
        CKPT[(PostgresSaver<br/>chat history)]
    end

    subgraph Integration [Camada de integração]
        SC[scheduling.py / agendamento.py<br/>Cliente OTIMUS + regras]
        WT[wts_client.py<br/>WTS Chat API]
        TR[tracking.py<br/>Telemetria]
    end

    subgraph External [Serviços externos]
        OT[(OTIMUS API)]
        WTSAPI[(WTS Chat API)]
        OAI[(OpenAI)]
        GEM[(Google Gemini)]
        PG[(PostgreSQL)]
    end

    SV --> WF
    WF --> PR
    WF --> DB
    WF --> AG
    AG --> SC
    AG --> WT
    AG --> CTX
    AG --> CKPT
    SC --> OT
    WT --> WTSAPI
    AG --> OAI
    PR --> GEM
    PR --> OAI
    DB --> PG
    CKPT --> PG
    TR --> PG

Fluxos HTTP expostos

Método	Path	Quem chama	Função
POST	/webhook/message	WTS Chat	Recebe mensagem do paciente
POST	/webhook/transfer	interno/WTS	Move sessão para departamento humano
POST	/webhook/consultar	tool do agente	Proxy para consultar_horarios_workflow (Clinfeto)
POST	/webhook/agendar	tool do agente	Proxy para agendar_consulta_workflow (Clinfeto)
GET	/health	load balancer	Health check

Diferença entre MEDCENTER e CLINFETO

• MEDCENTER: as tools do agente chamam diretamente as funções Python (consultar_horarios, agendar_consulta) — in-process.
• CLINFETO: as tools fazem requests.post() para os endpoints /webhook/consultar e /webhook/agendar do próprio serviço — loopback HTTP. Esse design permite trocar o backend do agendamento sem tocar no agente, mas adiciona latência e uma hop de falha.

Para projetos novos: prefira o padrão in-process (MEDCENTER) salvo justificativa explícita.

Processos de longa duração

1. Uvicorn / FastAPI — serve os webhooks (worker único por enquanto; thread-safe porque cada request é processada em thread separada).
2. Thread de workflow — iniciada a cada /webhook/message com threading.Thread(target=_run_workflow, daemon=True).start(). Permite retornar 202 accepted ao WTS imediatamente.
3. Conexão persistente PostgresSaver — única conexão autocommit ao Postgres, inicializada no módulo agent.py.

Isolamento por projeto

Cada projeto possui:

• Seu container Docker (ver Dockerfile).
• Seu schema PostgreSQL com prefixo próprio de tabela (*_medcenter, *_clinfeto).
• Seu subdomínio OTIMUS com token próprio.
• Seu CHANNEL_ID e DEPARTMENT_ID do WTS Chat.
• Seu ALLOWED_INSTANCE (número da instância WhatsApp) e ALLOWED_TEAM.

Não compartilhar credenciais entre projetos

O token do OTIMUS de uma clínica é exclusivo dela. Ver Autenticação.

Persistência

PostgreSQL
├── n8n_fila_mensagens_<projeto>     # fila debounce
├── dados_cliente_<projeto>          # chat history (LangGraph)
├── checkpoint* (tabelas LangGraph)  # criadas pelo PostgresSaver.setup()
├── dashboard_sessions
├── dashboard_token_usage
├── dashboard_errors
└── dashboard_tags

Nenhum dado de paciente/agendamento fica no DB local. Tudo é delegado ao OTIMUS. O DB serve apenas para:

• Debounce de mensagens (n8n_fila_mensagens_<projeto>)
• Histórico de chat do agente (tabelas do checkpointer)
• Telemetria/analytics (dashboard)

Modelos usados

Uso	Modelo	Onde
Chat / tool calling	gpt-4.1 (MEDCENTER) / gpt-4.1-mini (CLINFETO)	agent.py
OCR imagens, PDFs	gemini-2.5-flash (MEDCENTER) / gemini-2.0-flash (CLINFETO)	processors.py
Transcrição de áudio	whisper-1	processors.py

Observabilidade

Telemetria mínima é gravada em tempo real nas tabelas dashboard_*:

• dashboard_sessions — toda sessão nova (phone, contact_name, content_type).
• dashboard_token_usage — cada chamada LLM (prompt, completion, custo USD + BRL).
• dashboard_errors — exceções do workflow e do agente.
• dashboard_tags — tags aplicadas ao contato via WTS.

Ver Telemetria para o schema e a função log_token_usage / log_error.