Del 'Hello World' a la Orquestación Profesional: Tres Niveles para Dominar la IA Agéntica con SQL

El Desafío: ¿Cómo Enseñar IA Agéntica Sin Abrumar?

Como profesor universitario, me enfrento cada semestre al mismo dilema: ¿cómo enseño a mis estudiantes a construir sistemas de IA agéntica sin que abandonen en la primera clase?

La mayoría de los tutoriales de IA caen en dos extremos:

• 🎓 Los “Hello World” excesivamente simplificados que funcionan en demos pero se desmoronan en producción
• 🏢 Las arquitecturas enterprise tan complejas que solo sirven para ahuyentar principiantes

Después de meses iterando con mis estudiantes (y con la ayuda invaluable de Gemini y GitHub Copilot), encontré la respuesta: aprendizaje progresivo en tres niveles.

El resultado es DBV-AgenticEduSQL, un proyecto educativo que lleva a los estudiantes desde su primer “hola mundo” con IA hasta sistemas profesionales de orquestación multi-agente.

🎯 La Misión: De Lenguaje Natural a SQL con IA

El concepto es engañosamente simple:

1. Un usuario escribe una pregunta en español: “¿Cuántos clientes tenemos en Madrid?”
2. Un agente de IA traduce eso a SQL válido
3. Se ejecuta contra una base de datos Oracle
4. Otro agente interpreta los resultados en lenguaje natural

Pero la magia está en CÓMO lo construyes.

🚀 Los Tres Niveles: De Novato a Arquitecto

📘 Nivel 1: El “Hello World” Honesto (oracle_agentic_gemini_apikey.ipynb)

Para quién: Tu primer contacto con IA generativa
Tecnología: Google Gemini con API Key directa
Arquitectura: 2 agentes secuenciales

# Así de simple:
1. pregunta_usuario → agente_generador_sql → SQL
2. SQL → base_datos → resultados → agente_intérprete → respuesta_natural

¿Por qué empezar aquí?

• ✅ Solo necesitas una API Key de Google (gratis)
• ✅ ~200 líneas de código comprensibles
• ✅ Ves resultados en 10 minutos
• ✅ Entiendes el flujo básico sin distracciones

La lección: Antes de orquestar 4 agentes, domina la coordinación de 2.

📗 Nivel 2: La Flexibilidad Profesional (oracle_agentic_hello_world.ipynb)

Para quién: Ya entiendes lo básico, ahora quieres flexibilidad
Tecnología: AISuite (multi-proveedor)
Arquitectura: Lineal mejorada con funciones modulares

# Una línea para cambiar de modelo:
client = aisuite.Client()
model = "openai:gpt-4o"           # Hoy
model = "google:gemini-2.0-flash" # Mañana
model = "anthropic:claude-3-5-sonnet" # Pasado mañana

¿Por qué este nivel importa?

• ✅ Evitas el vendor lock-in (dependencia de un solo proveedor)
• ✅ Comparas calidad de GPT-4 vs Gemini vs Claude en TU caso de uso
• ✅ Código reutilizable con funciones tipo Result[T] (éxito/error)
• ✅ Aprendes patrones de diseño profesionales

La lección: El código que funciona con UN modelo es un experimento. El código que funciona con CUALQUIER modelo es ingeniería.

📕 Nivel 3: La Orquestación Completa (orquestador_base_datos.ipynb)

Para quién: Construir sistemas que funcionen en el mundo real
Tecnología: LangGraph + AISuite
Arquitectura: Máquina de Estados Finitos (FSM) con 4 agentes orquestados

# Una orquestación real con bucles de corrección:
START
  ↓
[Agente Contextualización] → ¿Pregunta clara? → NO → Bucle: pide aclaración
  ↓ SÍ
[Agente Generación SQL] → Genera SQL
  ↓
[Agente Ejecución DB] → ¿SQL correcto? → NO → Bucle: regenera SQL
  ↓ SÍ
[Agente Interpretación] → ¿Hay resultados? → NO → Bucle: revisa pregunta
  ↓ SÍ
END (respuesta final)

¿Por qué LangGraph?

• ✅ Manejo de errores automático: Si el SQL falla, lo regenera solo
• ✅ Bucles de clarificación: Si la pregunta es ambigua, pregunta antes de ejecutar
• ✅ Estado compartido (Blackboard Pattern): Todos los agentes colaboran sobre el mismo contexto
• ✅ Flujo adaptativo: El camino cambia según los resultados intermedios

La diferencia brutal:

La lección: La diferencia entre un demo y un sistema de producción está en cómo manejas los errores.

🎓 La Ruta de Aprendizaje (No Te Saltes Pasos)

Errores que veo cada semestre:

• ❌ Estudiante salta directo al Nivel 3 → se ahoga en complejidad → abandona
• ❌ Estudiante se queda en Nivel 1 → entrega un sistema frágil → se rompe en la demo

La ruta correcta:

1. Semana 1-2: Nivel 1 → Entiende el concepto de agentes (pregunta → SQL → respuesta)
2. Semana 3-4: Nivel 2 → Domina flexibilidad y patrones de diseño
3. Semana 5-6: Nivel 3 → Implementa orquestación profesional

Cada nivel construye sobre el anterior. No hay atajos.

💻 El Secreto Sauce: Código Limpio para IA

Aquí está el plot twist que nadie te cuenta: el código sucio es veneno para la IA.

Mientras desarrollaba este proyecto, descubrí que:

• Funciones con 7 returns → Gemini no puede seguir la lógica
• Tipos Any por todas partes → Copilot sugiere código incorrecto
• Nombres ambiguos → Los agentes generan SQL erróneo

Así que creé una guía de buenas prácticas específica para código que trabaja con IA:

🔗 Si Tu Código Python Tiene 7 return, Tu IA Te Odia

Y la integré en el proyecto como buenaspracticas.ipynb, un notebook completo con:

• ✅ Type hints modernos de Python 3.10+ (str | None vs Optional[str])
• ✅ Guard clauses vs estructuras if-else anidadas
• ✅ Result Type Pattern para manejo de errores explícito
• ✅ Docstrings completos (Args, Returns, Raises)
• ✅ Ejemplos ❌ MAL / ✅ BIEN para cada principio

Todos los notebooks del proyecto referencian esta guía. Porque código profesional requiere fundamentos profesionales.

🎭 La Lección del Mundo Real: Cuando la Documentación Miente

Mientras pulía el proyecto, ocurrió algo muy instructivo (y un poco vergonzoso):

El README decía: Python 3.8+
El código usaba: str | None (Python 3.10+), TypeAlias (Python 3.10+), Literal en TypedDict (Python 3.10+)

Si un estudiante con Python 3.8 hubiera intentado ejecutarlo:

nombre: str | None = None  # ❌ SyntaxError: invalid syntax

¿La moraleja? La documentación desactualizada es tan grave como un bug en el código.

Añadí esta anécdota al notebook buenaspracticas.ipynb como un “easter egg” pedagógico: a veces nuestros propios errores son las mejores herramientas de enseñanza. 😄

🛠️ Tecnologías: Por Qué Esta Stack

📊 Comparación de Arquitecturas (Tabla Visual)

🎯 Para Quién Es Este Proyecto

✅ Perfecto para ti si:

• 👨‍🎓 Estudiantes de informática que quieren entender IA agéntica desde cero
• 👨‍🏫 Profesores buscando material educativo progresivo y práctico
• 💼 Desarrolladores que necesitan implementar sistemas de IA + bases de datos
• 🔄 Ingenieros de datos explorando cómo integrar LLMs con SQL

❌ Probablemente NO es para ti si:

• Buscas un sistema listo para producción sin modificaciones (esto es educativo)
• No tienes acceso a Oracle (aunque puedes adaptarlo a PostgreSQL/MySQL)
• Esperas que la IA resuelva todo sin entender los fundamentos

🚀 Empieza Ahora

Repositorio completo: github.com/davidbuenov/dbv-agentic-edu-SQL

Instalación en 3 pasos:

git clone https://github.com/davidbuenov/dbv-agentic-edu-SQL.git
cd dbv-agentic-edu-SQL
pip install -r requirements.txt

Empieza con:

1. oracle_agentic_gemini_apikey.ipynb (Nivel 1 - tu primer agente)
2. Lee buenaspracticas.ipynb (código limpio para IA)
3. Avanza progresivamente por los niveles

🙏 Agradecimientos

Este proyecto no habría sido posible sin la colaboración activa de:

• Gemini de Google: Por ser mi sparring partner en diseño de arquitecturas
• GitHub Copilot: Por acelerar la escritura de código boilerplate y documentación
• Mis estudiantes: Por hacer preguntas incómodas que mejoraron el proyecto

💬 Tu Turno

¿Has construido sistemas agénticos? ¿Qué nivel de complejidad usas en tus proyectos?

Déjame un comentario o conéctate conmigo en LinkedIn.

Y si encuentras útil este proyecto, ⭐ dale una estrella en GitHub para que más estudiantes lo descubran.

📚 Recursos Relacionados

• 🔗 Si Tu Código Python Tiene 7 return, Tu IA Te Odia - Guía de código limpio para IA
• 📂 Repositorio del Proyecto - Código completo con 3 niveles
• 📓 buenaspracticas.ipynb - Guía de Python 3.10+ moderno (incluida en el repo)

¿Te ha gustado este artículo? Compártelo con otros desarrolladores que estén explorando IA agéntica. ¡La educación en IA es un deporte de equipo! 🚀