From e5f3d2723071f028f274ec0bcbe5d3ac5d8f20b2 Mon Sep 17 00:00:00 2001 From: Gustavo Date: Tue, 11 Aug 2026 16:35:00 -0300 Subject: [PATCH] Spec: workflows de exemplo de AI Agent para agendamento (Klingo, ClinicAll, SysLife) Co-Authored-By: Claude Sonnet 5 --- ...flows-exemplo-agente-agendamento-design.md | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-11-workflows-exemplo-agente-agendamento-design.md diff --git a/docs/superpowers/specs/2026-08-11-workflows-exemplo-agente-agendamento-design.md b/docs/superpowers/specs/2026-08-11-workflows-exemplo-agente-agendamento-design.md new file mode 100644 index 0000000..6b5eb35 --- /dev/null +++ b/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.