From e614763023c15ddfbbbe32db9010b8190a967934 Mon Sep 17 00:00:00 2001 From: Gustavo Date: Sun, 27 Sep 2026 22:17:13 -0300 Subject: [PATCH] docs: registra incidentes de producao Z-PRO (endpoint MCP, horario passado, investigacao midia) Co-Authored-By: Claude Sonnet 5 --- docs/n8n-agendamento-runbook.md | 108 +++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 1 deletion(-) diff --git a/docs/n8n-agendamento-runbook.md b/docs/n8n-agendamento-runbook.md index 168efaf..cce14d8 100644 --- a/docs/n8n-agendamento-runbook.md +++ b/docs/n8n-agendamento-runbook.md @@ -18,7 +18,12 @@ > cobre os workflows de exemplo de AI Agent para **agendamento** desses > mesmos três providers (fechando a lacuna que só a confirmação tinha > preenchido) — ver o inventário geral de todos os workflows de exemplo -> (agendamento + confirmação, nos 4 providers) no final da seção 22. +> (agendamento + confirmação, nos 4 providers) no final da seção 22. A +> seção 23 registra três bugs reais encontrados em produção no Z-PRO +> depois que o gestor da clínica editou o AI Agent pela UI (endpoint MCP +> revertido pro servidor errado, agendamento em horário já passado) e o +> estado da investigação sobre suporte a imagem/áudio (ainda sem +> solução — depende do painel admin do Z-PRO). ## 1. Node MCP: qual usar e como instalar @@ -1005,3 +1010,104 @@ apontando pro respectivo MCP Server nativo já construído. Nenhum foi ativado nem testado com chamada HTTP real — cada um fica pronto pra duplicar assim que a clínica real correspondente e o banco Postgres do cliente existirem. + +## 23. Incidentes reais em produção (Z-PRO, 17/08/2026) — edição manual pela UI + +Depois que o gestor da clínica exemplo editou o node `AI Agent` e o +`OpenAI Chat Model` diretamente pela UI do n8n (troca de modelo), o +agendamento em produção (`Agendamento - GChat - Z-PRO (clínica +exemplo)`, `yG2mi6ECBpPv4Hmn`) parou de funcionar. Três problemas reais +foram encontrados e corrigidos, nesta ordem: + +### 23.1. `endpointUrl` do MCP Client Tool revertido pro servidor errado + +**Sintoma**: toda mensagem caía no branch de erro padrão ("Desculpe, +tive um problema técnico..."). Execução mostrava +`"error": "Error in sub-node MCP - ZPRO (nativo n8n)"` / +`"Could not connect to your MCP server"`. + +**Causa raiz**: o node `MCP - ZPRO (nativo n8n)` (o único `MCP Client +Tool` conectado ao AI Agent deste workflow) apontava pro endpoint de +**teste** do MCP de Mensageria +(`https://devn8n.gtigrupo.com.br/mcp-test/mcp-server-mensageria-zpro`) +em vez do MCP de **agendamento** de produção +(`https://devn8n.gtigrupo.com.br/mcp/mcp-server-zpro-clinica-exemplo`, +servidor `MCP Server - ZPRO` / `qjSaKllvneBIZ7mC`, tools `agendar` + +`consultar_horarios`). Confirmado via execução `248` (12/08, um dia +antes) que o agendamento real só funciona com esse endpoint correto — +o node havia sido apontado pro MCP errado (mensageria, não +agendamento) durante uma edição manual, e a correção foi **revertida +duas vezes** só de reabrir/salvar o node do modelo pela UI (o editor +recarrega o valor antigo em cache do campo `endpointUrl` e resalva o +workflow inteiro). + +**Fix**: `endpointUrl` corrigido pra +`https://devn8n.gtigrupo.com.br/mcp/mcp-server-zpro-clinica-exemplo`. +**Risco de recorrência real** — documentado como aviso pro +gestor: qualquer edição futura do `AI Agent`/`OpenAI Chat Model` pela +UI deve conferir esse campo antes de salvar. + +### 23.2. Modelo trocado para `gpt-5.6-luna` + +O gestor trocou o modelo do `OpenAI Chat Model` de `gpt-4.1-mini` para +`gpt-5.6-luna` (veio do dropdown de modelos da credencial "GPT", +`cachedResultName` igual ao `value` — não foi digitado à mão). Mantido +a pedido do usuário; não identificado como causa de nenhum dos bugs +desta seção (o erro de conexão MCP acontece antes de qualquer chamada +ao modelo). + +### 23.3. Agendamento aceito em horário já passado + +**Sintoma**: paciente pediu "17/08 as 8:30" às 11:48 (mesmo dia) e o +agente agendou sem objeção, mesmo com o horário já tendo passado. + +**Causa raiz**: nem o `systemMessage` do `AI Agent` nem o doc de +prompt da clínica (Google Docs) tinham qualquer regra comparando o +horário pedido com o horário atual — só validavam dia da semana e +horário comercial (seção 3 do doc). O `systemMessage` calculava +`$now` só com **data**, sem hora, então o modelo não tinha como +comparar. + +**Fix**: `systemMessage` do `AI Agent` alterado para incluir data +**e hora** atuais (`yyyy-MM-dd (cccc) HH:mm`) e nova regra 8: nunca +agendar num horário já passado — comparar com o horário atual antes de +confirmar/agendar, e pedir outro horário se o pedido já passou. +Também revisado o doc de prompt da clínica (`docId` +`1NmYRIoF7yD_B6N160_6Bpfv4NyJiryTTO2LFr9xNlYY`, Google Docs) pra +remover a exigência de "consultar disponibilidade antes de agendar" +(o Z-PRO não oferece essa consulta — nunca ofereceu, mesmo nos +agendamentos que funcionaram — então a regra original só confundia o +modelo sem nunca ter sido cumprível). + +### 23.4. Investigação em aberto — suporte a imagem/áudio (sem solução ainda) + +Pedido do usuário: fazer o AI Agent entender imagens e áudios enviados +pelo paciente no WhatsApp. Testado enviando uma imagem e um áudio reais +pro número de produção: + +- **Confirmado por teste direto**: o webhook `Webhook Z-PRO` recebe + ambos exatamente como uma mensagem de texto vazia — + `{"step":"process","entrada":"","number":...,"contactName":...,"protocol":...}` + — sem nenhum campo de mídia, URL, base64 ou tipo de mensagem. +- **Descartado como evidência**: uma mensagem encontrada num ticket + antigo ("No momento, consigo processar apenas mensagens em texto...") + **não é** um aviso de sistema do Z-PRO — vem do chatFlow nativo + `id 78`, nomeado **"GUSTAVO"**, criado em 14/07/2026 dentro do próprio + painel de chatbot do Z-PRO. É texto escrito manualmente por alguém da + equipe num flow separado, não evidência da API. +- A collection pública do Postman do Z-PRO + (`postman.com/comunidade-zdg/z-pro/collection/ksvu6vu`) documenta só + a API de saída (enviar mensagem, criar ticket, `appointment/*`, + etc.) — não tem nenhum endpoint de webhook de entrada nem de busca + de mídia recebida. +- Pista não seguida: o objeto de ticket retornado por + `showticketchatbot` tem campos `n8nStatus`/`n8nUrl` (hoje `false`/ + `null` no ticket testado), sugerindo que o Z-PRO tem alguma + configuração de integração com n8n por ticket/canal cujas opções não + foram investigadas. + +**Pendência real**: confirmar no painel administrativo do Z-PRO (quem +tem acesso) se a configuração do webhook usado por este workflow +(`agendamento-zpro-clinica-exemplo`) tem alguma opção pra incluir mídia +no payload. Sem isso, a feature de entender imagem/áudio não é +implementável só editando o workflow do n8n.