From 34b5fc8a2e376121cbd1988baac6bc202bccb95f Mon Sep 17 00:00:00 2001 From: Gustavo Date: Tue, 11 Aug 2026 09:49:44 -0300 Subject: [PATCH] =?UTF-8?q?docs:=20registra=20configura=C3=A7=C3=A3o=20da?= =?UTF-8?q?=20IA=20via=20Google=20Docs=20(Z-PRO)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nova seção 15: 4 nodes adicionados ao workflow de produção (yG2mi6ECBpPv4Hmn) para buscar o systemMessage de negócio de um Google Doc público por clínica, com fallback seguro em caso de falha. Documenta o bug real encontrado e corrigido durante a implementação: HTTP Request substitui o $json inteiro, quebrando a Memória da Sessão por perda do sessionId -- fix foi reconstruir os campos explicitamente a partir do node anterior ao HTTP Request. Testado de ponta a ponta em produção: conteúdo do Doc aparece na resposta, regras fixas continuam valendo, caminho de falha confirmado sem quebrar o atendimento. Co-Authored-By: Claude Sonnet 5 --- docs/n8n-agendamento-runbook.md | 86 ++++++++++++++++++++++++++++++++- 1 file changed, 85 insertions(+), 1 deletion(-) diff --git a/docs/n8n-agendamento-runbook.md b/docs/n8n-agendamento-runbook.md index c668027..463d2b5 100644 --- a/docs/n8n-agendamento-runbook.md +++ b/docs/n8n-agendamento-runbook.md @@ -370,7 +370,10 @@ correto, data correta, um único agendamento por teste, confirmado visualmente no Z-PRO. Workflow **ativo em produção** (`yG2mi6ECBpPv4Hmn`), junto com os 3 workflows do MCP Server nativo (`qjSaKllvneBIZ7mC`, `5ZEOqTOk4Xex6jUQ`, `yfKkhSTDZaIYCPqP`) — todos precisam permanecer -`active: true`. +`active: true`. Desde a seção 15, o `systemMessage` também depende de um +Google Doc externo (leitura pública, `docId` fixo em "Config Clínica") — +se o Doc for despublicado ou o `docId` mudar, o atendimento continua +funcionando (fallback seguro), só perde a personalização da clínica. ## 14. Providers adicionais via MCP Server nativo (Klingo, SysLife, ClinicAll) @@ -424,3 +427,84 @@ Reforçando o que já vale desde a seção 13, agora confirmado em mais três im - Tools de leitura nunca reformatam o corpo de sucesso — devolvem cru, sem inventar um envelope que não foi confirmado por um exemplo real de resposta. - Mapeamento de parâmetros `$fromAI(...)` nas tools do servidor é sempre um passo manual na UI (resourceMapper não é confiável via API do n8n) — feito pelo usuário, não pela automação. - Nenhuma credencial é criada automaticamente pela automação — sempre pré-requisito manual do usuário na UI do n8n, mesmo quando o valor é só um placeholder de rascunho. + +## 15. Configuração da IA via Google Docs — autonomia do gestor (só Z-PRO) + +**Data:** 11/08/2026. Ver design completo em +`docs/superpowers/specs/2026-08-11-config-ia-google-docs-design.md` e +plano em `docs/superpowers/plans/2026-08-11-config-ia-google-docs.md`. + +**Motivação**: o `systemMessage` do AI Agent era texto fixo hardcoded no +workflow. Com o número de clientes crescendo (1 workflow de agente por +clínica), editar manualmente o prompt de cada um toda vez que um gestor +quisesse ajustar tom de voz, saudação, horário de funcionamento ou uma +regra específica não escala. Solução: um Google Doc por clínica, +público só para leitura (sem exigir credencial no n8n), editável +diretamente pela conta do gestor — o `systemMessage` passa a concatenar +as regras fixas de segurança (inalteradas) com o conteúdo do Doc. + +**Arquitetura implementada** (4 nodes novos no workflow +`yG2mi6ECBpPv4Hmn`): + +``` +"É step=process?" → Config Clínica → Buscar config da clínica ─┬→ Doc OK ──────┐ + (docId fixo) (GET export?format=txt, └→ Doc falhou ─┴→ AI Agent + sem credencial) +``` + +- **Config Clínica** (`Set`): `docId` do Google Doc desta clínica, + fixo por cópia do workflow (mesmo padrão de `clinicId`/`baseUrl` dos + outros providers) — setado uma vez na instalação, nunca mais mexido + depois disso. +- **Buscar config da clínica** (`HTTP Request`): `GET + https://docs.google.com/document/d/{docId}/export?format=txt`, sem + autenticação (Doc público só para leitura), `onError: + continueErrorOutput`. +- **Doc OK** / **Doc falhou** (`Set`): reconstroem o item explicitamente + a partir de `$('Config Clínica').item.json` + `docContent` (do corpo + da resposta ou vazio, respectivamente). +- **`systemMessage` do AI Agent**: ganhou uma seção final + `"Instruções específicas desta clínica:\n{{ $json.docContent }}"`, + depois de todas as 7 regras fixas originais (que continuam idênticas, + sem alteração de texto). + +**Bug real encontrado e corrigido durante a implementação — perda de +contexto depois de um `HTTP Request`**: o node `HTTP Request` **substitui +o `$json` inteiro** pelo corpo da resposta, descartando qualquer campo +que viesse do item anterior (`sessionId`, `mensagem`, `telefone`, +`nomeContato`, `clinicId`). Isso quebrou a "Memória da Sessão" +(`Key parameter is empty`, porque `sessionKey` depende de +`$json.sessionId`) logo na primeira tentativa. Mesma classe de bug já +registrada na seção 5 deste runbook (expressões em sub-nodes de IA), só +que desta vez a causa foi upstream do AI Agent, não dentro dele. + +**Fix**: os nodes `Doc OK`/`Doc falhou` **não podem confiar em +`includeOtherFields`** quando há um `HTTP Request` no meio do caminho — +precisam reconstruir cada campo explicitamente referenciando o node +anterior ao HTTP Request por nome +(`={{ $('Config Clínica').item.json.sessionId }}`, etc.), exatamente +como já era feito em `Classificar resultado` nos sub-workflows de +`agendar` dos MCP Servers (seção 13/14) — a lição "depois de um HTTP +Request, resgate os campos anteriores pelo nome do node, nunca confie +em passthrough automático" vale pra qualquer node no meio do fluxo +principal, não só dentro de sub-workflows de tool. + +**Teste real de validação (11/08/2026)**, com um Google Doc de teste +contendo a regra fictícia `"não atendemos às segundas-feiras"`: + +1. Conteúdo do Doc apareceu naturalmente na resposta do agente + (pergunta genérica sobre dias de atendimento). +2. Regras fixas continuaram valendo (agente pediu confirmação do nome + completo antes de agendar). +3. Caminho de falha testado de propósito (`docId` inválido) — Google + Docs respondeu `404`, capturado pelo `onError: continueErrorOutput`, + roteado pro branch `Doc falhou`, atendimento **não quebrou** + (resposta normal, só sem a personalização da clínica). +4. `docId` revertido pro valor real de teste depois da validação. + +**Resultado**: workflow ativo em produção com a configuração de negócio +já externalizada para o Google Doc de teste +(`1NmYRIoF7yD_B6N160_6Bpfv4NyJiryTTO2LFr9xNlYY`). Falta trocar pelo Doc +real de produção da clínica exemplo quando o gestor tiver o conteúdo +definitivo. Padrão pronto pra replicar em Klingo/SysLife/ClinicAll +quando esses tiverem workflow de agente.