Files
KLINGO-CLINICAL-SYSLIFE-GCHAT/docs/superpowers/plans/2026-08-11-workflows-exemplo-agente-agendamento.md
T

429 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Workflows de Exemplo de AI Agent para Agendamento (Klingo, ClinicAll, SysLife) Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task (não subagent-driven-development — as tasks são chamadas de API do n8n via MCP, não commits de código; não há diff de git pra revisar por task). Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Construir 3 workflows de exemplo de AI Agent (um por provider — Klingo, ClinicAll, SysLife), cada um conectando via webhook Z-PRO/GChat num agente conversacional com acesso a todas as tools do respectivo MCP Server de agendamento já existente, todos validados estruturalmente (0 erros) e deixados **inativos de propósito** (sem clínica real de nenhum dos três providers).
**Architecture:** Réplica do esqueleto já usado nos 3 workflows de exemplo de confirmação de agenda (Klingo/ClinicAll/SysLife, seções 18-20 do runbook): `Webhook` (contrato Z-PRO/GChat) → `Extrair campos do webhook` (`Set`) → `AI Agent` com `OpenAI Chat Model` (credencial real compartilhada) + `Postgres Chat Memory` (credencial placeholder) + `MCP Client Tool` conectado ao MCP Server de agendamento do provider, com `include: "all"` (diferente dos exemplos de confirmação, que filtravam tools específicas — aqui o agente precisa de todas as tools do provider pra completar um agendamento). Nenhum sub-workflow novo é criado — os MCP Servers de agendamento já existem e são só referenciados pela URL do endpoint MCP.
**Tech Stack:** n8n (`devn8n.gtigrupo.com.br`), MCP tools do n8n (`n8n_create_workflow`, `n8n_update_partial_workflow`, `n8n_validate_workflow`), MCP Servers de agendamento já existentes (Klingo `3eiFEnfOTLnutP78`, ClinicAll `igaKjoHcPNYRAxPS`, SysLife `TYu78UqIUr2yCBHK`).
## Global Constraints
- Nenhum sub-workflow de tool é criado ou modificado nesta rodada — só os 3 workflows de agente e a conexão `MCP Client Tool` que aponta pros servidores já existentes.
- Contrato do webhook Z-PRO/GChat idêntico ao já documentado na seção 6 do runbook e reaproveitado nos 3 exemplos de confirmação: `body.protocol`→`sessionId`, `body.entrada`→`mensagem`, `body.contactName`→`nomeContato`, `body.number`→`telefone`.
- `OpenAI Chat Model` usa a credencial real e compartilhada já em uso em produção e nos exemplos de confirmação: `openAiApi` id `29vMIDah5DTIhUYJ`, nome "GPT" — não é credencial inventada.
- `Postgres Chat Memory` usa credencial placeholder (`PLACEHOLDER_SEM_CREDENCIAL`) — sem cliente real, sem banco provisionado, mesma disciplina dos exemplos de confirmação.
- `MCP Client Tool` de cada workflow usa `include: "all"` (não `"selected"` como nos exemplos de confirmação) — o agente de agendamento precisa de todas as tools do provider pra completar um fluxo de ponta a ponta.
- Webhook paths distintos por provider, pra não colidir entre si nem com os exemplos de confirmação já existentes: `agendamento-klingo-exemplo`, `agendamento-clinicall-exemplo`, `agendamento-syslife-exemplo`.
- Os 3 workflows ficam **inativos de propósito** ao final deste plano — sem clínica real de nenhum provider e sem credencial Postgres válida, ativá-los só geraria execuções com erro.
- O `systemMessage` do agente do Klingo precisa avisar explicitamente sobre a limitação real conhecida: `consultar_horarios` sempre retorna `SLOT_MAPPING_UNAVAILABLE` — o agente deve informar isso ao paciente em vez de inventar horários ou tentar chamar `agendar` sem um `slotId` real.
Spec de referência: `docs/superpowers/specs/2026-08-11-workflows-exemplo-agente-agendamento-design.md`
---
### Task 1: Workflow de exemplo "Agendamento - GChat - Klingo (exemplo)"
**Interfaces:**
- Consumes: MCP Server de agendamento Klingo (`3eiFEnfOTLnutP78`, path `mcp-server-klingo`, tools `consultar_horarios` + `agendar`).
- Produces: workflow `Agendamento - GChat - Klingo (exemplo)`.
- [ ] **Step 1: Criar o workflow (webhook + AI Agent + modelo + memória)**
`n8n_create_workflow`:
```json
{
"name": "Agendamento - GChat - Klingo (exemplo)",
"nodes": [
{
"id": "webhook",
"name": "Webhook GChat",
"type": "n8n-nodes-base.webhook",
"typeVersion": 2.1,
"position": [0, 0],
"parameters": { "httpMethod": "POST", "path": "agendamento-klingo-exemplo", "responseMode": "lastNode", "options": {} }
},
{
"id": "extrair-campos",
"name": "Extrair campos do webhook",
"type": "n8n-nodes-base.set",
"typeVersion": 3.4,
"position": [224, 0],
"parameters": {
"assignments": {
"assignments": [
{ "name": "sessionId", "type": "string", "value": "={{ $json.body.protocol }}" },
{ "name": "mensagem", "type": "string", "value": "={{ String($json.body.entrada || '').trim() }}" },
{ "name": "nomeContato", "type": "string", "value": "={{ $json.body.contactName }}" },
{ "name": "telefone", "type": "string", "value": "={{ $json.body.number }}" }
]
}
}
},
{
"id": "ai-agent",
"name": "AI Agent",
"type": "@n8n/n8n-nodes-langchain.agent",
"typeVersion": 2.1,
"position": [448, 0],
"parameters": {
"text": "={{ $json.mensagem }}",
"systemMessage": "Você é um assistente de agendamento de consultas médicas, via WhatsApp, para uma clínica que usa o sistema Klingo. Seu trabalho: 1) entender o que o paciente quer agendar; 2) usar a tool consultar_horarios para ver horários disponíveis. ATENÇÃO — limitação real conhecida desta integração: consultar_horarios pode retornar o erro SLOT_MAPPING_UNAVAILABLE, porque a API do Klingo não documenta publicamente o formato de cada horário individual. Se isso acontecer, informe educadamente ao paciente que a consulta de horários está temporariamente indisponível por essa integração e que ele será atendido de outra forma — nunca invente um horário nem um slotId; 3) se consultar_horarios funcionar e devolver um slotId real, use a tool agendar com esse slotId e os demais dados do paciente para concluir o agendamento; 4) responda sempre em português, de forma clara e cordial."
}
},
{
"id": "openai-chat-model",
"name": "OpenAI Chat Model",
"type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
"typeVersion": 1.3,
"position": [448, -160],
"parameters": { "model": { "mode": "id", "value": "gpt-4o-mini" }, "builtInTools": {}, "options": {} },
"credentials": { "openAiApi": { "id": "29vMIDah5DTIhUYJ", "name": "GPT" } }
},
{
"id": "memoria",
"name": "Memória da Sessão (Postgres)",
"type": "@n8n/n8n-nodes-langchain.memoryPostgresChat",
"typeVersion": 1.4,
"position": [448, 160],
"parameters": { "sessionIdType": "customKey", "sessionKey": "={{ $json.sessionId }}", "tableName": "n8n_chat_histories", "contextWindowLength": 20 },
"credentials": { "postgres": { "id": "PLACEHOLDER_SEM_CREDENCIAL", "name": "Postgres - (sem cliente real)" } }
}
],
"connections": {
"Webhook GChat": { "main": [[{ "node": "Extrair campos do webhook", "type": "main", "index": 0 }]] },
"Extrair campos do webhook": { "main": [[{ "node": "AI Agent", "type": "main", "index": 0 }]] },
"OpenAI Chat Model": { "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]] },
"Memória da Sessão (Postgres)": { "ai_memory": [[{ "node": "AI Agent", "type": "ai_memory", "index": 0 }]] }
}
}
```
Anotar o `id` retornado.
- [ ] **Step 2: Conectar o MCP Client Tool com todas as tools do MCP Klingo**
`n8n_update_partial_workflow`, numa única chamada atômica:
```json
{
"id": "<id do workflow do Step 1>",
"operations": [
{
"type": "addNode",
"node": {
"id": "mcp-client-klingo-agendamento",
"name": "MCP Klingo Agendamento",
"type": "@n8n/n8n-nodes-langchain.mcpClientTool",
"typeVersion": 1,
"position": [448, 320],
"parameters": {
"endpointUrl": "https://devn8n.gtigrupo.com.br/mcp/mcp-server-klingo",
"authentication": "none",
"include": "all"
}
}
},
{ "type": "addConnection", "source": "MCP Klingo Agendamento", "target": "AI Agent", "sourceOutput": "ai_tool", "targetIndex": 0 }
]
}
```
- [ ] **Step 3: Validar**
`n8n_validate_workflow`. Esperado: `errorCount: 0` (warnings de
credencial `postgres` placeholder são aceitáveis).
- [ ] **Step 4: Deixar inativo**
Não ativar — sem clínica Klingo real nem credencial Postgres válida.
---
### Task 2: Workflow de exemplo "Agendamento - GChat - ClinicAll (exemplo)"
**Interfaces:**
- Consumes: MCP Server de agendamento ClinicAll (`igaKjoHcPNYRAxPS`, path `mcp-server-clinicall`, 8 tools).
- Produces: workflow `Agendamento - GChat - ClinicAll (exemplo)`.
- [ ] **Step 1: Criar o workflow (webhook + AI Agent + modelo + memória)**
`n8n_create_workflow`:
```json
{
"name": "Agendamento - GChat - ClinicAll (exemplo)",
"nodes": [
{
"id": "webhook",
"name": "Webhook GChat",
"type": "n8n-nodes-base.webhook",
"typeVersion": 2.1,
"position": [0, 0],
"parameters": { "httpMethod": "POST", "path": "agendamento-clinicall-exemplo", "responseMode": "lastNode", "options": {} }
},
{
"id": "extrair-campos",
"name": "Extrair campos do webhook",
"type": "n8n-nodes-base.set",
"typeVersion": 3.4,
"position": [224, 0],
"parameters": {
"assignments": {
"assignments": [
{ "name": "sessionId", "type": "string", "value": "={{ $json.body.protocol }}" },
{ "name": "mensagem", "type": "string", "value": "={{ String($json.body.entrada || '').trim() }}" },
{ "name": "nomeContato", "type": "string", "value": "={{ $json.body.contactName }}" },
{ "name": "telefone", "type": "string", "value": "={{ $json.body.number }}" }
]
}
}
},
{
"id": "ai-agent",
"name": "AI Agent",
"type": "@n8n/n8n-nodes-langchain.agent",
"typeVersion": 2.1,
"position": [448, 0],
"parameters": {
"text": "={{ $json.mensagem }}",
"systemMessage": "Você é um assistente de agendamento de consultas médicas, via WhatsApp, para uma clínica que usa o sistema ClinicAll. Seu trabalho: 1) entender o que o paciente quer agendar (especialidade, convênio, profissional, procedimento), usando as tools especialidade, convenio, profissional e procedimento conforme necessário pra resolver os códigos certos; 2) confirmar/consultar o paciente com a tool paciente; 3) usar consultar_horarios para ver os horários livres de uma unidade+profissional — cada horário livre já é um registro existente, identificado por um idAgenda; 4) para concluir, chamar agendar passando EXATAMENTE o idAgenda do horário livre escolhido no passo anterior — agendar não cria um registro novo do zero, ele concilia (atualiza) esse mesmo idAgenda com os dados do paciente/procedimento/convênio. Nunca invente um idAgenda; 5) responda sempre em português, de forma clara e cordial."
}
},
{
"id": "openai-chat-model",
"name": "OpenAI Chat Model",
"type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
"typeVersion": 1.3,
"position": [448, -160],
"parameters": { "model": { "mode": "id", "value": "gpt-4o-mini" }, "builtInTools": {}, "options": {} },
"credentials": { "openAiApi": { "id": "29vMIDah5DTIhUYJ", "name": "GPT" } }
},
{
"id": "memoria",
"name": "Memória da Sessão (Postgres)",
"type": "@n8n/n8n-nodes-langchain.memoryPostgresChat",
"typeVersion": 1.4,
"position": [448, 160],
"parameters": { "sessionIdType": "customKey", "sessionKey": "={{ $json.sessionId }}", "tableName": "n8n_chat_histories", "contextWindowLength": 20 },
"credentials": { "postgres": { "id": "PLACEHOLDER_SEM_CREDENCIAL", "name": "Postgres - (sem cliente real)" } }
}
],
"connections": {
"Webhook GChat": { "main": [[{ "node": "Extrair campos do webhook", "type": "main", "index": 0 }]] },
"Extrair campos do webhook": { "main": [[{ "node": "AI Agent", "type": "main", "index": 0 }]] },
"OpenAI Chat Model": { "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]] },
"Memória da Sessão (Postgres)": { "ai_memory": [[{ "node": "AI Agent", "type": "ai_memory", "index": 0 }]] }
}
}
```
Anotar o `id` retornado.
- [ ] **Step 2: Conectar o MCP Client Tool com todas as tools do MCP ClinicAll**
`n8n_update_partial_workflow`, numa única chamada atômica:
```json
{
"id": "<id do workflow do Step 1>",
"operations": [
{
"type": "addNode",
"node": {
"id": "mcp-client-clinicall-agendamento",
"name": "MCP ClinicAll Agendamento",
"type": "@n8n/n8n-nodes-langchain.mcpClientTool",
"typeVersion": 1,
"position": [448, 320],
"parameters": {
"endpointUrl": "https://devn8n.gtigrupo.com.br/mcp/mcp-server-clinicall",
"authentication": "none",
"include": "all"
}
}
},
{ "type": "addConnection", "source": "MCP ClinicAll Agendamento", "target": "AI Agent", "sourceOutput": "ai_tool", "targetIndex": 0 }
]
}
```
- [ ] **Step 3: Validar**
`n8n_validate_workflow`. Esperado: `errorCount: 0`.
- [ ] **Step 4: Deixar inativo**
Não ativar — sem clínica ClinicAll real nem credencial Postgres válida.
---
### Task 3: Workflow de exemplo "Agendamento - GChat - SysLife (exemplo)"
**Interfaces:**
- Consumes: MCP Server de agendamento SysLife (`TYu78UqIUr2yCBHK`, path `mcp-server-syslife`, 7 tools).
- Produces: workflow `Agendamento - GChat - SysLife (exemplo)`.
- [ ] **Step 1: Criar o workflow (webhook + AI Agent + modelo + memória)**
`n8n_create_workflow`:
```json
{
"name": "Agendamento - GChat - SysLife (exemplo)",
"nodes": [
{
"id": "webhook",
"name": "Webhook GChat",
"type": "n8n-nodes-base.webhook",
"typeVersion": 2.1,
"position": [0, 0],
"parameters": { "httpMethod": "POST", "path": "agendamento-syslife-exemplo", "responseMode": "lastNode", "options": {} }
},
{
"id": "extrair-campos",
"name": "Extrair campos do webhook",
"type": "n8n-nodes-base.set",
"typeVersion": 3.4,
"position": [224, 0],
"parameters": {
"assignments": {
"assignments": [
{ "name": "sessionId", "type": "string", "value": "={{ $json.body.protocol }}" },
{ "name": "mensagem", "type": "string", "value": "={{ String($json.body.entrada || '').trim() }}" },
{ "name": "nomeContato", "type": "string", "value": "={{ $json.body.contactName }}" },
{ "name": "telefone", "type": "string", "value": "={{ $json.body.number }}" }
]
}
}
},
{
"id": "ai-agent",
"name": "AI Agent",
"type": "@n8n/n8n-nodes-langchain.agent",
"typeVersion": 2.1,
"position": [448, 0],
"parameters": {
"text": "={{ $json.mensagem }}",
"systemMessage": "Você é um assistente de agendamento de consultas médicas, via WhatsApp, para uma clínica que usa o sistema SysLife. Siga esta ordem: 1) use a tool especialidade para identificar a especialidade desejada pelo paciente; 2) use a tool medico para listar os médicos daquela especialidade/origem; 3) em qualquer ordem, use as tools convenio, paciente e procedimento conforme necessário pra resolver os códigos de convênio/plano, os dados do paciente (CPF, matrícula ou celular) e o procedimento/valor; 4) use consultar_horarios (tool Horario) para ver os horários disponíveis do médico escolhido; 5) para concluir, chame agendar com todos os códigos já resolvidos nos passos anteriores (data, hora, número da consulta, origem, paciente, convênio, plano, tabela de procedimento, procedimento, médico, especialidade, celular) — nunca invente um código que não veio de uma das tools anteriores; 6) responda sempre em português, de forma clara e cordial."
}
},
{
"id": "openai-chat-model",
"name": "OpenAI Chat Model",
"type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
"typeVersion": 1.3,
"position": [448, -160],
"parameters": { "model": { "mode": "id", "value": "gpt-4o-mini" }, "builtInTools": {}, "options": {} },
"credentials": { "openAiApi": { "id": "29vMIDah5DTIhUYJ", "name": "GPT" } }
},
{
"id": "memoria",
"name": "Memória da Sessão (Postgres)",
"type": "@n8n/n8n-nodes-langchain.memoryPostgresChat",
"typeVersion": 1.4,
"position": [448, 160],
"parameters": { "sessionIdType": "customKey", "sessionKey": "={{ $json.sessionId }}", "tableName": "n8n_chat_histories", "contextWindowLength": 20 },
"credentials": { "postgres": { "id": "PLACEHOLDER_SEM_CREDENCIAL", "name": "Postgres - (sem cliente real)" } }
}
],
"connections": {
"Webhook GChat": { "main": [[{ "node": "Extrair campos do webhook", "type": "main", "index": 0 }]] },
"Extrair campos do webhook": { "main": [[{ "node": "AI Agent", "type": "main", "index": 0 }]] },
"OpenAI Chat Model": { "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]] },
"Memória da Sessão (Postgres)": { "ai_memory": [[{ "node": "AI Agent", "type": "ai_memory", "index": 0 }]] }
}
}
```
Anotar o `id` retornado.
- [ ] **Step 2: Conectar o MCP Client Tool com todas as tools do MCP SysLife**
`n8n_update_partial_workflow`, numa única chamada atômica:
```json
{
"id": "<id do workflow do Step 1>",
"operations": [
{
"type": "addNode",
"node": {
"id": "mcp-client-syslife-agendamento",
"name": "MCP SysLife Agendamento",
"type": "@n8n/n8n-nodes-langchain.mcpClientTool",
"typeVersion": 1,
"position": [448, 320],
"parameters": {
"endpointUrl": "https://devn8n.gtigrupo.com.br/mcp/mcp-server-syslife",
"authentication": "none",
"include": "all"
}
}
},
{ "type": "addConnection", "source": "MCP SysLife Agendamento", "target": "AI Agent", "sourceOutput": "ai_tool", "targetIndex": 0 }
]
}
```
- [ ] **Step 3: Validar**
`n8n_validate_workflow`. Esperado: `errorCount: 0`.
- [ ] **Step 4: Deixar inativo**
Não ativar — sem clínica SysLife real nem credencial Postgres válida.
---
### Task 4: Atualizar o runbook e commit
**Interfaces:**
- Consumes: os 3 workflow ids criados nas Tasks 1–3.
- [ ] **Step 1: Adicionar seção 22 ao runbook**
Adicionar em `docs/n8n-agendamento-runbook.md`, após a seção 21, uma
seção "22. Workflows de exemplo de AI Agent para Agendamento (Klingo,
ClinicAll, SysLife)" cobrindo: o motivo (os MCP Servers de agendamento
existiam sem workflow de agente cliente, diferente da confirmação),
os 3 ids de workflow criados, a correção do número real de tools de
cada provider (Klingo 2, ClinicAll 8, SysLife 7 — não os 8 do Klingo
Telefonia que tinha sido citado por engano antes), a limitação real do
Klingo (`SLOT_MAPPING_UNAVAILABLE`) e como o `systemMessage` lida com
ela, e o status "estrutura pronta, inativos de propósito — falta
clínica real de qualquer um dos três providers".
- [ ] **Step 2: Atualizar a tabela da seção 21 (opcional, se fizer sentido)**
Adicionar uma linha na tabela comparativa da seção 21 com o id do
workflow de agendamento de exemplo de cada provider, complementando as
linhas já existentes de confirmação — só se isso não deixar a tabela
poluída; caso contrário, deixar a seção 22 autocontida sem tocar na 21.
- [ ] **Step 3: Commit**
```bash
cd "D:\PROJETOS\KLINGO-CLINICAL-SYSLIFE-GCHAT-AGENDAMENTO"
git add docs/n8n-agendamento-runbook.md
git commit -m "docs: registra workflows de exemplo de AI Agent para agendamento (Klingo, ClinicAll, SysLife)
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>"
```
---
## Observação sobre execução
Mesma disciplina dos planos anteriores: validar
(`n8n_validate_workflow`) depois de cada workflow criado/modificado.
Os 3 workflows deste plano ficam **intencionalmente inativos** ao
final — sem clínica real de nenhum dos três providers e sem credencial
Postgres válida, ativá-los só geraria execuções com erro. O
`systemMessage` do Klingo é o único que precisa de atenção redobrada:
ele documenta uma limitação real da API (não um bug desta
implementação) — não simplificar nem remover esse aviso ao escrever o
texto final.