Spec: workflows de exemplo de AI Agent para agendamento (Klingo, ClinicAll, SysLife)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/superpowers/specs/2026-08-11-workflows-exemplo-agente-agendamento-design.md

@@ -0,0 +1,137 @@
+# Design — Workflows de Exemplo de AI Agent para Agendamento (Klingo, ClinicAll, SysLife)
+
+**Data:** 2026-08-11
+**Status:** Aprovado pelo usuário, aguardando plano de implementação.
+
+## Objetivo
+
+Os MCP Servers de agendamento do Klingo, ClinicAll e SysLife existem e
+estão validados estruturalmente há algum tempo, mas nenhum tem um
+workflow de agente cliente (AI Agent + prompt + `MCP Client Tool`) —
+isso foi explicitamente adiado em cada design ("sem clínica real nem
+canal de mensagens definido"). Mesmo padrão que já resolvemos pra
+**confirmação de agenda** dos mesmos três providers (seções 18-20 do
+runbook): construir um workflow de exemplo/esqueleto, sem cliente real
+associado, pronto pra duplicar quando houver clínica de verdade.
+
+## Relação com o trabalho anterior
+
+- Reaproveita **exatamente** o esqueleto já usado nos três exemplos de
+  confirmação de agenda (webhook Z-PRO/GChat → `Extrair campos` →
+  `AI Agent` com `OpenAI Chat Model` real + `Postgres Chat Memory`
+  placeholder), só trocando as tools conectadas.
+- Conecta nas tools de **agendamento**, não nas de confirmação — decisão
+  explícita do usuário: "só agendamento por enquanto", mesmo padrão do
+  Z-PRO em produção (que também só tem agendamento).
+- Os três MCP Servers de agendamento já existem, ativos ou não conforme
+  cada design; workflows e ids reaproveitados diretamente, nenhum
+  sub-workflow novo é criado nesta rodada — só o workflow de agente e a
+  conexão via `MCP Client Tool`.
+
+## Escopo real de cada MCP Server de agendamento (conferido nos designs)
+
+| Provider | MCP Server (id) | Tools | Observação |
+| --- | --- | --- | --- |
+| **Klingo** | `3eiFEnfOTLnutP78` (path `mcp-server-klingo`) | `consultar_horarios`, `agendar` (2 tools) | **Limitação real conhecida**: `consultar_horarios` sempre retorna `SLOT_MAPPING_UNAVAILABLE` — a API do Klingo responde com sucesso, mas o formato de cada horário individual não é documentado publicamente. Consequência: `agendar` exige um `slotId` que, na prática, não há hoje como obter por esta integração. |
+| **ClinicAll** | `igaKjoHcPNYRAxPS` (path `mcp-server-clinicall`) | `unidade`, `especialidade`, `convenio`, `profissional`, `procedimento`, `paciente`, `consultar_horarios`, `agendar` (8 tools) | `agendar` usa `PUT` (suposição não verificada) e **concilia** um `idAgenda` de horário livre já existente (obtido via `consultar_horarios`) — não cria um registro do zero. |
+| **SysLife** | `TYu78UqIUr2yCBHK` (path `mcp-server-syslife`) | `especialidade`, `medico`, `convenio`, `paciente`, `procedimento`, `consultar_horarios`, `agendar` (7 tools) | Fluxo linear padrão: consulta os recursos de apoio, resolve os códigos, agenda via `PUT /Agenda`. |
+
+**Correção em relação à conversa inicial**: o Klingo tinha sido
+apresentado como tendo 8 tools de agendamento (confundindo com a API
+de Telefonia, que essa sim tem 6 tools de confirmação) — na verdade
+são só 2. A tabela acima é a fonte de verdade, extraída direto dos
+designs já commitados.
+
+## Decisão sobre a limitação do Klingo
+
+**Decisão explícita do usuário**: construir o workflow de exemplo do
+Klingo mesmo assim, documentando a limitação — tanto no `systemMessage`
+do agente (pra ele explicar ao paciente que não consegue consultar
+horários no momento, em vez de inventar uma resposta) quanto na spec e
+no runbook. Não é um bug desta implementação; é uma lacuna real e já
+conhecida da documentação pública da API do Klingo, fora do escopo
+resolver aqui.
+
+## Arquitetura
+
+Três workflows novos, um por provider, todos seguindo o mesmo esqueleto:
+
+```
+[Webhook GChat] → [Extrair campos do webhook] → [AI Agent] → resposta
+                                                    ├─ tools:   MCP de Agendamento do provider (MCP Client Tool, todas as tools)
+                                                    ├─ modelo:  OpenAI Chat Model (credencial real "GPT", 29vMIDah5DTIhUYJ)
+                                                    └─ memória: Postgres Chat Memory (credencial placeholder, sem cliente real)
+```
+
+- `Agendamento - GChat - Klingo (exemplo)` — conecta nas 2 tools do MCP
+  Klingo (`3eiFEnfOTLnutP78`).
+- `Agendamento - GChat - ClinicAll (exemplo)` — conecta nas 8 tools do
+  MCP ClinicAll (`igaKjoHcPNYRAxPS`).
+- `Agendamento - GChat - SysLife (exemplo)` — conecta nas 7 tools do
+  MCP SysLife (`TYu78UqIUr2yCBHK`).
+
+Mesmo contrato de webhook Z-PRO/GChat já documentado (seção 6 do
+runbook): `body.protocol`→`sessionId`, `body.entrada`→`mensagem`,
+`body.contactName`→`nomeContato`, `body.number`→`telefone`.
+
+## Componentes
+
+### `systemMessage` de cada agente
+
+Adaptado do fluxo real de cada API (não genérico, não inventado):
+
+- **Klingo**: instrui o agente a seguir `consultar_horarios` →
+  `agendar`, mas **avisa explicitamente** que `consultar_horarios`
+  pode retornar `SLOT_MAPPING_UNAVAILABLE` — nesse caso, o agente deve
+  informar ao paciente que a consulta de horários está temporariamente
+  indisponível por essa integração, sem inventar horários nem tentar
+  chamar `agendar` sem um `slotId` real.
+- **ClinicAll**: instrui o agente a consultar especialidade/convênio/
+  profissional/procedimento conforme necessário, usar
+  `consultar_horarios` para obter um `idAgenda` de horário livre, e
+  então chamar `agendar` **nesse mesmo `idAgenda`** (nunca inventar um
+  novo) — deixando explícito que é uma conciliação, não uma criação.
+- **SysLife**: instrui o agente a seguir a ordem
+  `especialidade` → `medico` → (`convenio`/`paciente`/`procedimento`,
+  qualquer ordem) → `consultar_horarios` → `agendar`, mesma ordem já
+  documentada no design do MCP SysLife.
+
+Nenhum dos três usa configuração via Google Docs (workflows de exemplo,
+sem gestor real).
+
+### Tools conectadas
+
+Via `MCP Client Tool` nativo, `include: "all"` (diferente dos exemplos
+de confirmação, que filtravam tools específicas — aqui faz sentido
+conectar todas as tools do MCP de agendamento, já que o agente precisa
+de todas elas pra completar um agendamento).
+
+### Memória e modelo
+
+Idênticos aos três exemplos de confirmação já construídos: `Postgres
+Chat Memory` com credencial placeholder (`PLACEHOLDER_SEM_CREDENCIAL`),
+`OpenAI Chat Model` com a credencial real e compartilhada já usada em
+produção (`29vMIDah5DTIhUYJ`, "GPT").
+
+## Fora de escopo (adiado)
+
+- Resolver `SLOT_MAPPING_UNAVAILABLE` do Klingo de verdade — lacuna de
+  contrato da API, não desta implementação.
+- Verificar empiricamente o verbo `PUT` de `/agendamento` do ClinicAll
+  — pendência já registrada no MVP de agendamento, continua em aberto.
+- Conectar as tools de confirmação de agenda nesses mesmos agentes —
+  decisão explícita do usuário de manter só agendamento por enquanto;
+  pode ser revisitado depois.
+- Ativação dos três workflows — ficam **inativos de propósito**, mesma
+  disciplina de todos os workflows de exemplo já construídos (sem
+  clínica real, sem credencial Postgres real).
+
+## Testes
+
+Sem clínica real disponível para nenhum dos três providers: validação
+estrutural apenas (`n8n_validate_workflow`, 0 erros esperados, exceto
+warnings já aceitos de credencial placeholder). Nenhuma chamada HTTP
+real. Quando houver clínica real de qualquer um dos três: preencher
+`baseUrl`/credenciais reais, provisionar Postgres, ativar o workflow
+correspondente — mesmo checklist já seguido nos exemplos de
+confirmação.