KLINGO-CLINICAL-SYSLIFE-GCHAT/docs/superpowers/specs/2026-08-11-workflows-exemplo-agente-agendamento-design.md

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.