Especificación del Agente

Agente de consulta a un dataset de salud mediante lenguaje natural. El usuario hace una pregunta en portugués, español o inglés — el agente interpreta, genera SQL SELECT, ejecuta en la base de datos conectada y devuelve la respuesta en texto con el razonamiento expuesto.

Opera sobre 5 tablas: pacientes, consultas, diagnosticos, medicamentos, exames. Límite de 30 consultas por sesión. Ningún dato es modificado.

Qué hace el agente

1. Acepta preguntas en lenguaje natural en PT, ES e EN
2. Clasifica la intención mediante el modelo Haiku antes de cualquier otra llamada
3. Genera SQL SELECT compatible con la base de datos conectada (SQLite en preparación, Teradata en el evento)
4. Ejecuta la consulta y procesa el resultado — filas devueltas, resultado vacío, error de SQL
5. Devuelve respuesta en 3 partes: respuesta directa + SQL generado (siempre expuesto) + razonamiento
6. Soporta preguntas multi-paso: descompone en sub-consultas, informa cuántas usará antes de ejecutar
7. Gestiona contador de consultas: avisa cuando restan 5, finaliza cuando llega a 30
8. Registra cada interacción con intención clasificada, SQL, tiempo de ejecución, tokens
9. Memoria conversacional con ventana deslizante de 30 mensajes — soporta refinamientos anafóricos
10. Sugerencias de siguiente pregunta post-respuesta, en el idioma del usuario
11. Modo reporte — sintetiza historial de la sesión sin incrementar el contador

Qué no hace el agente

1. Sin escritura — sin INSERT, UPDATE, DELETE, DROP, CREATE, ALTER (bloqueo programático)
2. No responde preguntas fuera del dominio del dataset
3. No formula diagnósticos médicos ni da consejos clínicos
4. No ejecuta SQL enviado directamente por el usuario
5. No referencia tablas fuera de las 5 definidas en el schema (bloqueo programático)
6. No continúa después del límite de 30 consultas
7. No inventa datos — si no encontró en la base, lo dice

Los guard rails son validaciones programáticas en el código, no en el prompt. El modelo no decide qué está permitido — el código lo decide antes.

pacientes

consultas

diagnosticos

medicamentos

exames

Cada interacción es registrada en logs/session_<id>.jsonl. Un registro por línea.

{
  "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
}