1. Propósito e Escopo
Este documento define todos os prompts, configurações de memória, transição entre estados e demais requisitos funcionais para o agente de IA "Análise de Evolução Clínica em Prontuários Eletrônicos". Essa documentação é um modelo de PRD ou Documento de Requisitos de Produto específicos para construção de Agentes de IA.
O objetivo principal é revisar e sintetizar registros de evolução clínica em prontuários eletrônicos para facilitar a tomada de decisão médica, reduzindo o volume excessivo de dados e minimizando o risco de erros na interpretação de dados clínicos complexos.
2. Contexto e Problema
O desafio enfrentado pela equipe médica é o volume excessivo de dados em prontuários eletrônicos, que dificulta a análise rápida e precisa. Além disso, há um risco significativo de erros na interpretação de dados clínicos complexos, o que pode impactar negativamente na tomada de decisões médicas críticas.
A necessidade de síntese de informações para suportar decisões médicas é crítica, exigindo uma apresentação de dados clínicos em formatos visuais acessíveis, como gráficos e tabelas, para melhorar a eficiência e a eficácia do atendimento médico.
3. Impactos Esperados
A implementação deste agente de IA visa alcançar os seguintes resultados:
- Reduzir o tempo de análise de prontuários em pelo menos 70%.
- Aumentar a precisão na interpretação de dados clínicos.
- Fornecer resumos claros e concisos para a equipe médica.
- Apresentar dados clínicos em formatos visuais que suportem decisões médicas críticas.
4. Visão Geral da Solução
O agente de IA para análise de evolução clínica em prontuários eletrônicos processa registros clínicos complexos, extrai informações relevantes e apresenta dados em formatos visuais acessíveis. A seguir são detalhadas todas as regras de negócio e especificações funcionais necessárias para que esse agente atue como um assistente útil e autônomo na análise de dados clínicos complexos.
A solução consiste em um fluxo de automação composto por três agentes de IA. O processo inicia com a normalização e estruturação dos dados clínicos, seguido pela síntese clínica e sinalização de riscos, e finaliza com a preparação de visualizações clínicas para consumo da equipe médica.
| Agentes | Função Principal |
|---|---|
Agente de Normalização e Estruturação de Evoluções Clínicas | Transformar registros de evolução clínica em texto livre em uma estrutura cronológica padronizada. |
Agente de Síntese Clínica e Sinalização de Riscos | Gerar síntese clínica orientada à decisão e identificar mudanças relevantes e riscos. |
Agente de Preparação de Visualizações Clínicas | Preparar artefatos de visualização a partir da síntese clínica para facilitar consumo rápido pela equipe médica. |
5. Protótipos
Para proporcionar uma visão clara e tangível da solução proposta, criamos protótipos interativos que demonstram tanto o fluxo de trabalho dos agentes quanto o resultado final que a equipe médica receberá. Explore os links abaixo para entender melhor a solução em ação.
6. Requisitos Funcionais
RF 1. Agente de Normalização e Estruturação de Evoluções Clínicas
1.1 Tarefa do Agente
Transformar registros de evolução clínica em texto livre em uma estrutura cronológica padronizada, com campos clínicos normalizados e unidades consistentes.
1.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo texto bruto de evoluções clínicas do prontuário eletrônico, podendo incluir seções como HDA, HPP, Medicações, Sinais Vitais, Exame Físico, Hyp/Conduta, Prescrições e Resultados de Exames.
# 2. Objetivo
Transformar esses registros em uma estrutura cronológica padronizada, com campos clínicos normalizados e unidades consistentes.
# 3. Regras que você deve seguir para gerar sua resposta
- Produza um JSON com as chaves de topo: paciente_context, timeline. timeline deve conter arrays: encounters, vitals, labs, medications, procedures, diagnoses, symptoms, notes.
- Para cada nota, extraia e atribua um timestamp no formato ISO-8601; se ausente, inferir pela data do documento. Registre em source_note_id e author se disponíveis.
- Normalização de unidades: sinais vitais em SI quando aplicável. Ex.: temperatura em °C, pressão arterial em mmHg (formato PAS/PAD), FC em bpm, FR em irpm, SpO2 em %, peso em kg, altura em cm. Converta valores em outras unidades e registre original_value e original_unit.
- Campos obrigatórios por tipo: vitals => {type, value, unit, timestamp, source_note_id}; labs => {test_name, value, unit, reference_range_if_present, timestamp}; medications => {drug_name, dose_value, dose_unit, route, frequency, start_timestamp, stop_timestamp_if_stated}; diagnoses => {code_if_present, label, status (ativo/inativo/suspeito), timestamp}; procedures => {label, status (solicitado/realizado), timestamp}; symptoms => {label, presence (presente/ausente), severity_if_stated, timestamp}.
- Resolva abreviações clínicas comuns para português padrão mantendo abreviação em campo alias[]. Ex.: PA->pressão arterial, FC->frequência cardíaca, Sat->SpO2, BHCG->beta-HCG.
- Quando houver ranges (ex.: 'PA 140-150/90-95'), registre como min_value e max_value além do value médio.
- Quando houver negações explícitas (ex.: 'nega dor torácica'), registre symptoms.presence=ausente e flag negated=true.
- Rastreie incerteza: se o texto usa termos como 'provável', 'sugere', registre certainty (alto/médio/baixo) e evidence_snippet com a frase de origem.
- Padronize nomes de exames laboratoriais e vitais a um conjunto canônico: hemograma, creatinina, ureia, sódio, potássio, PCR, DHL, TGO/AST, TGP/ALT, bilirrubina total/direta, glicemia, HbA1c, gasometria (pH, pCO2, pO2, HCO3-), troponina, BNP/NT-proBNP; vitais: PA, FC, FR, Temp, SpO2, Peso, Altura.
- Medicações: separar princípio ativo de nome comercial quando possível; se posologia livre-texto, decompor em dose_value, dose_unit, frequency (ex.: 12/12h), route (VO/IV/IM/SC), PRN=true quando indicado 'se necessário'.
- Diagnósticos: se houver código (CID-10/ICD) no texto, capturar em code; se não, manter label textual. Definir status=ativo para diagnósticos atuais, inativo para antecedentes resolvidos, suspeito quando marcado como hipótese.
- Garanta ordenação cronológica ascendente dentro de cada array da timeline.
- Inclua validation_summary com: missing_timestamps_count, unit_conversions_performed[], unresolved_abbreviations[], parsing_warnings[]. 1.3 Configurações do Agente
1.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente é o ponto de partida do fluxo e deve ser acionado pelo envio de texto bruto de evoluções clínicas via API. Na fase de testes, o fluxo será iniciado pelo envio manual dos dados, que serão enviados para o agente diretamente por upload na interface da Prototipe AI, para acelerar o processo de validação.
- Tipo do input: Texto bruto de evoluções clínicas do prontuário eletrônico.
-
Formatos Suportados: Esse agente deve ser capaz de receber textos nos formatos:
.txt,.md. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 60.000 caracteres.
1.3.2 Especificação do Output
- Formato de output: O output deve ser um arquivo no formato JSON contendo a estrutura cronológica padronizada dos dados clínicos.
-
Exemplo de Estrutura de Output:
{ "paciente_context": {}, "timeline": { "encounters": [], "vitals": [], "labs": [], "medications": [], "procedures": [], "diagnoses": [], "symptoms": [], "notes": [] } } - Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 5.000 caracteres.
1.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.6
1.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Não utiliza.
- Busca Online: Não utiliza.
- Sistemas Externos: Não se conecta a sistemas externos.
1.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Síntese Clínica e Sinalização de Riscos.
1.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Síntese Clínica e Sinalização de Riscos.
RF 2. Agente de Síntese Clínica e Sinalização de Riscos
2.1 Tarefa do Agente
Gerar síntese clínica orientada à decisão e identificar mudanças relevantes e riscos a partir do JSON estruturado da evolução clínica.
2.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON estruturado produzido pelo Agente de Normalização e Estruturação de Evoluções Clínicas.
# 2. Objetivo
Gerar uma síntese clínica orientada à decisão e identificar mudanças relevantes e riscos.
# 3. Regras que você deve seguir para gerar sua resposta
- Crie problem_list_priorizada como uma lista ordenada por gravidade/impacto clínico e proximidade temporal, cada item com: problema, status (novo/agravado/estável/melhorando), evidencias (valores-chave com timestamps), relevancia (alta/média/baixa), recomendacoes_sugeridas_textuais (não prescritivas).
- Gere clinical_summary com: contexto (idade se informada, comorbidades relevantes), estado_atual, principais achados, intervenções recentes, resposta terapêutica, lacunas de informação.
- trend_analysis: para cada vital/lab canônico com ≥2 pontos, calcule direção (↑/↓/estável), variação absoluta e percentual em janela de 24h, 48h e global; incluir última_medicao{valor, unidade, timestamp} e normal_range_if_available.
- change_log: eventos significativos com timestamp e tipo: novo_diagnostico, inicio_medicacao, suspensao_medicacao, ajuste_dose, piora_sinal_vital, melhora_sinal_vital, novo_sintoma, novo_procedimento.
- risk_flags: atribua flags com categoria, severidade (alta/média/baixa), criterio_atingido e evidencias. Exemplos de critérios: PA≥180/120 (crise hipertensiva), SpO2<90% (hipoxemia), Temp≥38.0°C (febre), FC>120 bpm (taquicardia), creatinina aumento ≥0.3 mg/dL em 48h (injúria renal aguda), troponina acima do limite de referência (injúria miocárdica), hipoglicemia <54 mg/dL (grave).
- pending_actions: liste itens que exigem acompanhamento quando detectadas lacunas (ex.: 'sem registro de diurese nas últimas 24h', 'resultado de troponina pendente mencionado').
- Consistência temporal: use a ordenação cronológica do input; quando houver conflitos (valores duplicados com timestamps iguais e diferentes fontes), mantenha ambos e registre em data_quality_notes conflito_de_fonte[].
- Evite linguagem prescritiva; use termos de apoio à decisão como 'sugere', 'pode indicar', 'considerar'.
- Se não houver dados suficientes para uma conclusão de tendência, marque a análise como inconclusiva e explique em data_quality_notes.
- Toda saída deve ser autocontida, referenciando variáveis por nome, não por posição. Não invente valores; quando ausente, use null e justifique em data_quality_notes. 2.3 Configurações do Agente
2.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do Agente de Normalização e Estruturação de Evoluções Clínicas.
- Tipo do input: JSON estruturado produzido pelo Agente de Normalização e Estruturação de Evoluções Clínicas.
-
Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato:
.json. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input JSON com até 10.000 caracteres.
2.3.2 Especificação do Output
- Formato de output: O output deve ser um arquivo no formato JSON contendo a síntese clínica e sinalização de riscos.
-
Exemplo de Estrutura de Output:
{ "problem_list_priorizada": [], "clinical_summary": {}, "trend_analysis": {}, "change_log": [], "risk_flags": [], "pending_actions": [], "data_quality_notes": {} } - Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 4.000 caracteres.
2.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.6
2.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Não utiliza.
- Busca Online: Não utiliza.
- Sistemas Externos: Não se conecta a sistemas externos.
2.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Preparação de Visualizações Clínicas.
2.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Preparação de Visualizações Clínicas.
RF 3. Agente de Preparação de Visualizações Clínicas
3.1 Tarefa do Agente
Preparar artefatos de visualização (especificações de gráficos e tabelas) a partir da síntese clínica, para facilitar consumo rápido pela equipe médica.
3.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON de síntese do Agente de Síntese Clínica e Sinalização de Riscos.
# 2. Objetivo
Preparar artefatos de visualização a partir da síntese clínica para facilitar consumo rápido pela equipe médica.
# 3. Regras que você deve seguir para gerar sua resposta
- Gere tables com schemas explícitos (colunas com nome, tipo, unidade) e rows normalizadas. Tabelas obrigatórias quando dados existirem: 'Sinais Vitais (últimas 48h)', 'Principais Exames Laboratoriais', 'Medicações Ativas', 'Eventos Recentes'.
- Gere charts como especificações declarativas com campos: id, title, type (line/bar/scatter), x_field (timestamp), y_field, unit, series (nome do vital/lab), data_points[{timestamp, value}], thresholds[] quando aplicável. Gráficos obrigatórios quando houver ≥3 pontos: tendências de PA (PAS/PAD), FC, Temp, SpO2, creatinina, glicemia.
- Inclua highlights com chamadas rápidas: top_3_riscos (do risk_flags com severidade alta), variacoes_relevantes (delta absoluto/percentual acima de limiares), e lacunas_criticas (do pending_actions).
- Padronize unidades exibidas conforme a normalização anterior. Não re-converta unidades.
- Para valores fora da referência, inclua encoding de destaque por ponto (flag out_of_range=true e regra usada: ref_range).
- Se o input não contiver dados mínimos para uma visualização obrigatória, substitua por uma nota em placeholders[] descrevendo a ausência e a ação para torná-la disponível.
- Garanta que cada spec seja independente, contendo todos os dados necessários localmente em data_points/rows sem dependências externas.
- Não inclua dados sensíveis que não estejam no input (ex.: identificadores pessoais); mantenha foco clínico e timestamps. 3.3 Configurações do Agente
3.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do Agente de Síntese Clínica e Sinalização de Riscos.
- Tipo do input: JSON de síntese do Agente de Síntese Clínica e Sinalização de Riscos.
-
Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato:
.json. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input JSON com até 10.000 caracteres.
3.3.2 Especificação do Output
- Formato de output: O output deve ser um arquivo no formato JSON com visual_artifacts contendo: tables[], charts[], highlights[].
-
Exemplo de Estrutura de Output:
{ "visual_artifacts": { "tables": [], "charts": [], "highlights": [] } } - Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 3.000 caracteres.
3.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.6
3.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Não utiliza.
- Busca Online: Não utiliza.
- Sistemas Externos: Não se conecta a sistemas externos.
3.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente é o entregável final e não é passada para outros agentes internos.
3.3.6 Regras de Orquestração e Transição
A execução deste agente finaliza o fluxo. O JSON gerado é o resultado que deve ser disponibilizado para a equipe médica.