Visão Geral do Assistente Virtual
O Assistente Virtual faz uma entrevista clínica por texto antes do atendimento: gera um plano de perguntas a partir da queixa e dos sinais vitais, avalia cada resposta do paciente (podendo fazer perguntas de aprofundamento) e, ao final, produz um resumo clínico para o médico. Toda a lógica — perguntas, avaliação e resumo — vem de prompts cadastrados por conta, sem mudança de código.
O módulo tem três partes:
| Parte | Para quê | Permissão |
|---|---|---|
Sessões (/assistant/session) | A entrevista em si, com um paciente | manage_assistant para escrever; leitura só exige autenticação |
Configurações (/assistant-config) | Os prompts e parâmetros do modelo | manage_assistant_config |
Tipos de agente (/assistant-agent-type) | Protocolos especializados por queixa | manage_assistant_config |
Base
https://api-dev.imagemais.com.br/api/assistant
https://api-dev.imagemais.com.br/api/assistant-config
https://api-dev.imagemais.com.br/api/assistant-agent-type
Todas as rotas exigem autenticação e são isoladas pela conta (accountId) do token.
Fluxo da sessão
- Criar a sessão com
patientIdeconsultationReason(e os sinais vitais disponíveis). O backend gera o plano de perguntas com IA e, se algum tipo de agente combinar com a queixa, acrescenta as perguntas especializadas. - Buscar a sessão para exibir as perguntas.
- Para cada pergunta, Responder Pergunta com o
questionIde o texto digitado. A resposta indica o próximo passo:follow_up— pergunta de aprofundamento emfollowUp;next_question— próxima pergunta do plano emnextQuestion;end— todas as perguntas foram respondidas.
- Ao terminar (ou ao concluir manualmente), o resumo clínico é gerado em segundo plano. Buscar Resumo da Sessão responde
400 "Resumo clínico ainda não disponível"até ficar pronto. - Vincular a sessão a uma consulta para que o médico a encontre em Buscar Sessão por Consulta.
Sessões que não serão usadas podem ser descartadas. A triagem e a pré-consulta também abrem sessões do assistente a partir dos dados já coletados.
Estados da sessão
| Valor | Quando |
|---|---|
ASKING_QUESTION | Sessão criada com o plano pronto, aguardando resposta |
PROCESSING_RESPONSE | Avaliando a resposta recebida |
FINAL_SUMMARY | Todas as perguntas respondidas; gerando o resumo |
COMPLETED | Resumo gerado |
FAILED | Erro na geração |
CREATED, WAITING_ASSISTANT, INTRODUCTION e LISTENING_RESPONSE existem no enum por causa de um fluxo antigo por voz e só aparecem em sessões antigas.
Configurações
Uma configuração reúne os três prompts do assistente e os parâmetros do modelo:
| Prompt | Quando roda | Variáveis |
|---|---|---|
interviewPlanPrompt | Na criação da sessão, gera as perguntas | {{reason}}, {{vitals}}, {{questionCount}} |
evaluateAnswerPrompt | A cada resposta, decide entre follow-up e próxima pergunta | {{consultationReason}}, {{vitals}}, {{question}}, {{goal}}, {{answer}}, {{followUpCount}}, {{maxFollowUps}}, {{history}} |
clinicalSummaryPrompt | No fim, gera o resumo clínico | respostas da entrevista |
Uma configuração nasce inativa. Ativar uma configuração desativa as demais do mesmo agentType; sem agentType, ela vale para a entrevista básica.
Tipos de agente
Um tipo de agente é um protocolo especializado (por exemplo, dor torácica). Os triggers são exemplos de queixas que o ativam: na criação da sessão, a IA compara a queixa do paciente com os tipos ativos e escolhe o mais adequado — ou nenhum. O tipo escolhido usa a configuração ativa com o mesmo agentType.
Diferente das configurações, um tipo de agente é criado com isActive: true e passa a ser considerado nas sessões seguintes. Envie isActive: false para cadastrar sem ativar.
Rotas
| Método | Rota | Permissão | Descrição |
|---|---|---|---|
POST | /assistant/session | manage_assistant | Cria a sessão |
GET | /assistant/session/{id} | — | Busca a sessão |
GET | /assistant/session/by-consultation/{consultationId} | — | Sessão da consulta |
POST | /assistant/session/{id}/answer | manage_assistant | Responde uma pergunta |
PATCH | /assistant/session/{id}/complete | manage_assistant | Conclui a sessão |
GET | /assistant/session/{id}/summary | — | Resumo clínico |
PATCH | /assistant/session/{id}/link | manage_assistant | Vincula a uma consulta |
DELETE | /assistant/session/{id} | manage_assistant | Descarta a sessão |
GET | /assistant-config | manage_assistant_config | Lista configurações |
GET | /assistant-config/{id} | manage_assistant_config | Busca configuração |
POST | /assistant-config | manage_assistant_config | Cria configuração |
PATCH | /assistant-config/{id} | manage_assistant_config | Atualiza configuração |
PATCH | /assistant-config/{id}/activate | manage_assistant_config | Ativa configuração |
PATCH | /assistant-config/{id}/deactivate | manage_assistant_config | Desativa configuração |
DELETE | /assistant-config/{id} | manage_assistant_config | Remove configuração |
GET | /assistant-agent-type | manage_assistant_config | Lista tipos de agente |
GET | /assistant-agent-type/{id} | manage_assistant_config | Busca tipo de agente |
POST | /assistant-agent-type | manage_assistant_config | Cria tipo de agente |
PATCH | /assistant-agent-type/{id} | manage_assistant_config | Atualiza tipo de agente |
DELETE | /assistant-agent-type/{id} | manage_assistant_config | Remove tipo de agente |