# 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.