Este proyecto es una demostración de una aplicación construida con Spring Boot 4 y Spring AI 2.0, utilizando las últimas versiones disponibles a Enero de 2026.

Este proyecto utiliza el stack tecnológico más reciente del ecosistema Spring:

• Java: 21 (LTS)
• Spring Boot: 4.0.1
• Spring AI: 2.0.0-M1 (Milestone 1)

Nota: Al utilizar una versión Milestone (M1), es necesario configurar repositorios adicionales de Spring (spring-milestones) en el pom.xml, ya que estas versiones no están en Maven Central estándar.

Para recrear este proyecto desde cero, sigue estos pasos:

1. Generar el proyecto base: Puedes usar Spring Initializr o curl. Dado que Spring Boot 4 es muy reciente, generamos un proyecto web básico primero:

   curl -G https://start.spring.io/starter.zip \ -d dependencies=web \ -d type=maven-project \ -d javaVersion=21 \ -d bootVersion=3.4.1 \ -o project.zip unzip project.zip

   (Nota: Si Spring Boot 4 no se puede seleccionar directamente, edita el pom.xml tras generar).

2. Configurar pom.xml:

   • Actualizar versión padre: Cambiar spring-boot-starter-parent a 4.0.1.
   • Añadir Repositorio Milestone:

     <repositories> <repository> <id>spring-milestones</id> <name>Spring Milestones</name> <url>https://repo.spring.io/milestone</url> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories>

   • Configurar BOM (Bill of Materials) de Spring AI:

     <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>2.0.0-M1</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

   • Añadir Dependencias:

     <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency>

Spring AI ofrece una API portable y unificada para interactuar con diversos modelos de IA. Las capacidades actuales incluyen:

• Chat Models: Interfaz unificada para OpenAI, Azure OpenAI, Amazon Bedrock, Google Vertex AI, Ollama, Anthropic Claude, etc.
• Image Generation: Generación de imágenes (DALL-E, Stability AI).
• Audio: Transcripción (Speech-to-Text) y Texto a Voz (Text-to-Speech) usando modelos como Whisper.
• Embeddings: Conversión de texto a vectores para búsqueda semántica.

• Vector Stores: Abstracción para bases de datos vectoriales. Actualmente soporta:
  • PGVector (PostgreSQL)
  • Redis
  • Neo4j
  • MongoDB Atlas
  • Chroma, Weaviate, Milvus, Qdrant, etc.
• Document Readers: Utilidades para leer PDFs, JSON, Texto, Markdown.
• Document Transformers: División de documentos (TokenTextSplitter) para indexación.

• Function Calling: Permite a los modelos de IA invocar funciones Java propias (ej. consultar tu base de datos o API externa) de forma transparente.
• Chat Memory: Gestión del historial de conversación para mantener el contexto.
• Evaluation: Framework para evaluar la calidad de las respuestas de la IA.

Para ejecutar este proyecto, necesitas configurar tu API Key (en este caso para OpenAI) en src/main/resources/application.properties:

spring.ai.openai.api-key=${OPENAI_API_KEY}

O exportarla como variable de entorno:

export SPRING_AI_OPENAI_API_KEY=tu-clave-aqui

Este proyecto es una plantilla técnica diseñada para construir sistemas de producción robustos en Java desde el inicio. Es la opción recomendada cuando la integración empresarial, la escalabilidad y la mantenibilidad a largo plazo son requisitos críticos del caso de uso. A continuación, se resume la hoja de ruta para que desarrolladores se capaciten y comprendan las decisiones de diseño.

Este proyecto reconoce el valor inmenso de Python en ciencia de datos y entrenamiento de modelos (Heavy AI).

Aunque el ecosistema Java evoluciona rápidamente integrando capacidades avanzadas (como visión y multimodalidad), Python sigue siendo una herramienta excelente para exploración, entrenamiento y casos de uso "bleeding edge" donde las herramientas JVM aún puedan estar madurando.

Nuestro objetivo es ofrecer un estándar robusto para la IA empresarial, donde Java destaca por su integración con sistemas legacy, concurrencia masiva y tipado fuerte, complementando la agilidad creativa de otros ecosistemas.

Para dominar el stack tecnológico de este proyecto, se recomienda la siguiente progresión de recursos educativos:

1. Fundamentos de Spring AI:

   • Curso: "Spring AI: Beginner to Guru" (John Thompson en Udemy).
   • Objetivo: Asentar bases de ChatClient, inyección de dependencias y conexión básica con LLMs.

2. Ingeniería de Datos y RAG:

   • Curso: "Mastering Spring AI: Build AI with Java" (Pritesh Mistry en Udemy).
   • Objetivo: Profundizar en ingestión de documentos, bases de datos vectoriales y transformación de consultas.

3. Arquitectura Avanzada e Interoperabilidad:

   • Curso: "Build AI Apps with Spring AI... MCP, AI Testing" (Madan Reddy en Udemy).
   • Objetivo: Aprender Model Context Protocol (MCP) para conectar herramientas y Testing automatizado de IA.

4. Teoría de Agentes:

   • Curso: "AI Agents in Java..." (Vanderbilt University en Coursera).
   • Objetivo: Comprender la arquitectura cognitiva de los agentes (Planificación, Memoria) más allá del código.

Este repositorio incluye instrucciones especializadas para el agente, ubicadas en .github/instructions/springai.instructions.md.

Estas pautas aseguran que cualquier código generado por la IA respete la arquitectura de referencia:

• Enfoque Java-Nativo: Preferencia por tipado fuerte (Records, POJOs) y conversión estructurada (BeanOutputConverter) frente a JSON crudo.
• Arquitectura Spring AI: Uso de ChatClient fluente, Advisors recursivos y abstracciones oficiales en lugar de ports directos de librerías de Python.
• Calidad de Ingeniería: Integración obligatoria de Testcontainers y Evaluators para pruebas robustas.

Para más detalles, consulta la documentación oficial, que se actualiza constantemente con nuevas integraciones:

• Documentación de Referencia de Spring AI
• Repositorio de GitHub

Este proyecto implementa el patrón ReAct (Reason + Act) eliminando la complejidad accidental de librerías de grafos externas, demostrando cómo Java simplifica estos patrones.

En ecosistemas interpretados (Python/JS), se suelen usar frameworks complejos (como LangGraph) para manejar el estado. En Java, aprovechamos la robustez del lenguaje:

1. "The Code is the Graph": El flujo de control (while, if, llamadas a métodos) es el grafo. Es legible, depurable y familiar.
2. Estado Explícito: El estado es simplemente una List<Message> pasada entre métodos. Sin "cajas negras".
3. Tipado Fuerte: Usamos los tipos oficiales de Spring AI (AssistantMessage, ToolCall) asegurando corrección en compilación.

El núcleo del agente (ReActRunner.java) implementa este ciclo de vida:

flowchart TD Start([Inicio]) --> Init["Inicializar Conversación<br/>(User Message)"] Init --> LoopCheck{"¿Terminado o<br/>Max Pasos?"} LoopCheck -- No --> AgentStep["<b>Agent Node</b><br/>(Pensamiento/LLM)"] AgentStep --> ToolCheck{"¿El LLM pidió<br/>usar Tools?"} ToolCheck -- Sí --> ToolStep["<b>Tool Node</b><br/>(Ejecución/Acción)"] ToolStep --> Log[Loguear Resultado Tool] Log --> AddToHistory[Añadir a Historial] AddToHistory --> LoopCheck ToolCheck -- No --> FinalCheck["<b>Respuesta Final</b><br/>(Assistant Message)"] FinalCheck --> End([Fin]) LoopCheck -- Sí --> Error([Abortar: Límite Alcanzado]) 

1. AgentNode (Razonamiento):

   • Encapsula el ChatClient.
   • Configura las herramientas pero deshabilita su ejecución automática para permitir que el bucle controle el flujo.
   • Retorna la intención del modelo (Texto o Tool Call).

2. ToolNode (Acción):

   • Recibe la solicitud de ejecución.
   • Ejecuta la herramienta correspondiente (TavilySearchTool, TripleTool).
   • Devuelve el resultado formateado como ToolResponseMessage.

3. ReActRunner (Orquestación):

   • Gestiona el bucle while.
   • Coordina el paso de mensajes entre Nodos.
   • Controla los límites de iteración (Evita bucles infinitos).

El proyecto incluye un CommandLineRunner que se ejecuta al inicio:

1. Configura las claves:

   export SPRING_AI_OPENAI_API_KEY=sk-... export TAVILY_API_KEY=tvly-...

2. Ejecuta la aplicación:

   ./mvnw spring-boot:run

El log mostrará paso a paso cómo el agente:

1. Razona que necesita el clima (AgentNode).
2. Ejecuta la búsqueda en Tavily (ToolNode).
3. Observa el resultado y razona que necesita triplicar el valor (TripleTool).
4. Entrega la respuesta final.