Especificação do Agente

Agente de consulta a dataset de saúde via linguagem natural. O usuário faz uma pergunta em português, espanhol ou inglês — o agente interpreta, gera SQL SELECT, executa no banco conectado e devolve a resposta em texto com o raciocínio exposto.

Opera sobre 5 tabelas: pacientes, consultas, diagnosticos, medicamentos, exames. Limite de 30 queries por sessão. Nenhum dado é modificado.

O que o agente faz

1. Aceita perguntas em linguagem natural em PT, ES e EN
2. Classifica a intenção via modelo Haiku antes de qualquer outra chamada
3. Gera SQL SELECT compatível com o banco conectado (SQLite em prep, Teradata no evento)
4. Executa a query e trata o resultado — linhas retornadas, resultado vazio, erro de SQL
5. Devolve resposta em 3 partes: resposta direta + SQL gerado (sempre exposto) + raciocínio
6. Suporta perguntas multi-step: decompõe em sub-queries, informa quantas vai usar antes de executar
7. Gerencia contador de queries: avisa quando restam 5, encerra quando chega a 30
8. Loga cada interação com intenção classificada, SQL, tempo de execução, tokens
9. Memória conversacional com sliding window de 30 mensagens — suporta refinamentos anafóricos
10. Sugestões de próxima pergunta pós-resposta, no idioma do usuário
11. Modo relatório — sintetiza histórico da sessão sem incrementar o contador

O que o agente não faz

1. Nenhuma escrita — sem INSERT, UPDATE, DELETE, DROP, CREATE, ALTER (bloqueio programático)
2. Não responde perguntas fora do domínio do dataset
3. Não formula diagnósticos médicos nem dá conselhos clínicos
4. Não executa SQL passado diretamente pelo usuário
5. Não referencia tabelas fora das 5 definidas no schema (bloqueio programático)
6. Não continua após o limite de 30 queries
7. Não inventa dados — se não encontrou no banco, diz que não encontrou

Guard rails são validações programáticas no código, não no prompt. O modelo não decide o que é permitido — o código decide antes.

pacientes

consultas

diagnosticos

medicamentos

exames

Cada interação é logada em logs/session_<id>.jsonl. Um registro por linha.

{
  "session_id": "uuid",
  "query_number": 3,
  "timestamp": "ISO8601",
  "user_input": "...",
  "intent_classified": "data_query",
  "sql_generated": "SELECT ...",
  "execution_time_ms": 120,
  "rows_returned": 47,
  "error": null,
  "model_used": "claude-sonnet-4-6",
  "input_tokens": 340,
  "output_tokens": 85
}