Mejores prácticas para Agentes de IA

Reglas para construir sistemas y agentes RAG fundamentados, observables y controlables.

Cómo usar esta lista

• Las reglas A-B cubren la calidad de la recuperación y la generación.
• Las reglas C-D rigen la seguridad del agente y el uso de herramientas.
• Las reglas E-F cubren operaciones y evaluación.

A - Calidad de la Recuperación

• Divide en fragmentos con tamaño y solapamiento apropiados. 500-1000 caracteres para prosa; evalúa recall@k.
• Almacena metadatos con cada fragmento. Fuente, id_doc, página, sección para filtrar y citar.
• Usa búsqueda híbrida para producción. Combina BM25 y recuperación densa; reordena los principales candidatos.
• Fija el modelo de incrustación por índice. Nunca mezcles modelos o dimensiones en una colección.
• Devuelve "No lo sé" cuando la recuperación está vacía. No generes a partir de contexto irrelevante.

B - Calidad de la Generación

• Instruye al modelo para que use solo el contexto. Prompt del sistema con reglas explícitas de fundamentación.
• Cita las fuentes en las respuestas. Incluye referencias de fragmentos para la verificación del usuario.
• Valida las salidas estructuradas con Pydantic. Reintenta en caso de fallo de validación (máximo 3).
• Separa la evaluación de recuperación y generación. Una mala recuperación no se puede solucionar solo con ingeniería de prompts.
• Temperatura=0 para QA factual. Temperatura más alta solo para tareas creativas.

C - Seguridad del Agente

• Valida los argumentos de las herramientas antes de la ejecución. Esquemas Pydantic en cada herramienta.
• Limita los permisos de las herramientas al mínimo requerido. Solo lectura por defecto; aprobación para escrituras.
• Establece iteraciones máximas en los bucles del agente. 5-10 iteraciones evitan llamadas descontroladas a herramientas.
• Ejecuta herramientas de código en un entorno aislado (sandbox). Contenedores aislados con límites de recursos.
• Registra cada llamada a herramienta. Nombre, argumentos, resultado, latencia para auditoría y depuración.

D - Observabilidad

• Rastrea el pipeline RAG completo. Consulta, fragmentos recuperados, prompt, respuesta, latencia.
• Monitoriza el recall de recuperación en producción. Muestra consultas con documentos relevantes conocidos.
• Rastrea la retroalimentación del usuario. Pulgares arriba/abajo enlazados a la consulta y al contexto recuperado.
• Alerta sobre fallos de fidelidad. LLM-como-juez o comprobaciones heurísticas en CI.
• Versiona el índice y los prompts juntos. Registra la versión del índice con cada respuesta.

E - Arquitectura

• Empieza de forma simple: SDK crudo + base de datos vectorial. Añade LangChain/LlamaIndex cuando la complejidad lo justifique.
• Usa LangGraph para agentes multi-paso. No bucles while manuales en producción.
• Caché de consultas frecuentes. Hashea la consulta + versión del índice; devuelve respuestas cacheadas.
• Diseña para actualizaciones de índice. Upsert/elimina por id_doc sin reindexar completamente.
• Separa las rutas de ingesta de las de consulta. Ingesta por lotes offline; consulta en tiempo real online.

F - Evaluación

• Crea el conjunto de evaluación antes del lanzamiento. Mínimo 20+ pares de consulta-respuesta etiquetados.
• Ejecuta la evaluación en CI en cada cambio. Cambios en el prompt, modelo, fragmentación o índice.
• Prueba entradas adversarias. Inyección de prompts, consultas vacías, preguntas fuera de tema.
• Mide la latencia de extremo a extremo. Presupuestos p50/p99 de recuperación + generación.
• Revisión humana antes de producción. Comprueba 50 respuestas del conjunto de evaluación.

Preguntas Frecuentes

Relacionado

• Conceptos básicos de RAG
• Evaluación y Barreras de Seguridad
• Uso de Herramientas y Llamada a Funciones
• Mejores prácticas para LLMs
• Monitorización y Deriva

Versiones de la pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.