Spec: workflows de exemplo de AI Agent para agendamento (Klingo, ClinicAll, SysLife)
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Gustavo
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
69b34ead9e
commit
e5f3d27230
@@ -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.
|
||||
Reference in New Issue
Block a user