Spring AI con Spring Boot: integra modelos de IA en tu backend Java sin perder el control

Tarde o temprano llega el ticket: "queremos que el soporte responda solo las preguntas sobre pedidos", "clasifiquemos los correos entrantes con IA", "un asistente que consulte el estado de un envío". La primera tentación es abrir un RestClient contra la API del proveedor, pegar un prompt en un String y parsear el JSON de vuelta. Funciona en la demo. Luego llegan las preguntas de verdad: ¿cómo cambio de OpenAI a Claude sin reescribir nada?, ¿cómo convierto la respuesta en un objeto Java fiable?, ¿cómo dejo que el modelo consulte mi base de datos sin darle acceso a todo?, ¿cuánto me está costando cada petición? Spring AI con Spring Boot existe para responder a esas preguntas con las mismas reglas de siempre: autoconfiguración, beans, propiedades y observabilidad.

El problema es que casi todo lo que encuentras en español sobre Spring AI está escrito para versiones milestone de 2024 o 2025, con starters que ya no existen, APIs que cambiaron de nombre y cero palabras sobre tests, costes o seguridad. Spring AI 2.0 salió en junio de 2026 alineado con Spring Boot 4 y rompió bastantes cosas. En esta guía vemos qué es Spring AI hoy, cómo montar un proyecto con Spring AI 2.0, y cómo usar ChatClient, la salida estructurada, el tool calling, la memoria de conversación y el streaming, terminando con lo que separa una demo de un servicio en producción: tests, observabilidad de tokens, resiliencia y riesgos.

¿Qué es Spring AI?

Spring AI es el proyecto oficial de Spring para integrar modelos de lenguaje (LLM) y otros modelos de IA en aplicaciones Java. Ofrece una API portable (ChatClient) sobre distintos proveedores (Anthropic, OpenAI, Google, Mistral, Ollama, Amazon Bedrock…), con autoconfiguración de Spring Boot, salida estructurada a objetos Java, tool calling, memoria de conversación, RAG y métricas con Micrometer.

Dicho de otra forma: Spring AI es a los LLM lo que Spring Data es a las bases de datos. No es un modelo ni un servicio en la nube; es una capa de abstracción que te permite cambiar de proveedor tocando dependencias y propiedades, y que trae resueltos los problemas repetitivos de hablar con un modelo.

Sus piezas principales son pocas:

  • ChatModel: la interfaz de bajo nivel que implementa cada proveedor (AnthropicChatModel, OpenAiChatModel, OllamaChatModel…). Recibe un Prompt y devuelve un ChatResponse.
  • ChatClient: la API fluida pensada para el día a día, al estilo de RestClient o WebClient. En Spring AI 2.0 es explícitamente la API principal; ChatModel queda como bloque de construcción.
  • Advisors: interceptores que envuelven cada llamada al modelo para añadir comportamiento transversal: memoria, RAG, ejecución de herramientas, logging, validación. Son el equivalente a los filtros de un servlet o a los aspectos de Spring AOP.
  • Tools: métodos Java anotados con @Tool que el modelo puede pedir que se ejecuten.

Arquitectura de Spring AI con Spring Boot: un controlador REST usa ChatClient, que pasa la petición por una cadena de advisors (memoria, ToolCallingAdvisor y SimpleLoggerAdvisor) hasta un ChatModel conectado a Anthropic, OpenAI u Ollama, con observabilidad de tokens y latencia en Micrometer

Qué cambió en Spring AI 2.0

Si vienes de la versión 1.x o de un tutorial antiguo, estos son los cambios que más te vas a encontrar, según el anuncio oficial de Spring AI 2.0:

  • Base Spring Boot 4.0/4.1 y Spring Framework 7. Spring AI 2.0.x no funciona con Spring Boot 3.
  • Jackson 3 en lugar de Jackson 2, y código anotado con JSpecify para la nulabilidad.
  • Opciones inmutables con builders, y el segmento .options desaparece de las propiedades (spring.ai.openai.embedding.model en vez de spring.ai.openai.embedding.options.model).
  • Un único cliente por proveedor: Anthropic, OpenAI y Google pasan a usar sus SDK oficiales de Java.
  • El bucle de herramientas sale de los ChatModel y pasa a un ToolCallingAdvisor que ChatClient registra automáticamente.
  • Adiós a APIs antiguas: FunctionCallback y .functions(...) se eliminan en favor de @Tool, ToolCallback y .tools(...).

Si un ejemplo usa spring-ai-openai-spring-boot-starter o FunctionCallback, es de otra época: no lo copies.

Cómo configurar Spring AI en un proyecto Spring Boot

Dependencias

Spring AI publica un BOM para alinear versiones. En el momento de escribir esto la última versión estable es la 2.0.2 (la 2.1 está en release candidate):

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>2.0.2</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webmvc</artifactId> </dependency> <!-- Un starter por proveedor: cambia este y las propiedades para cambiar de modelo --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-anthropic</artifactId> </dependency> </dependencies>

Los starters siguen el patrón spring-ai-starter-model-<proveedor>: spring-ai-starter-model-openai, spring-ai-starter-model-ollama, etc. Si añades dos, tendrás dos ChatModel en el contexto y tendrás que decir cuál usar (lo vemos más abajo).

Propiedades

spring: ai: anthropic: # Nunca en el repositorio: variable de entorno o gestor de secretos api-key: ${ANTHROPIC_API_KEY} chat: # Fija el modelo explícitamente; no dependas del valor por defecto model: ${AI_CHAT_MODEL:claude-haiku-4-5} max-tokens: 1024 temperature: 0.2

Dos consejos que ahorran sustos. Primero, fija siempre el modelo: los valores por defecto cambian entre versiones de Spring AI y hasta la propia documentación del starter de Anthropic muestra defaults distintos en dos tablas. Segundo, limita max-tokens: es tu primer freno de costes, porque la factura de un LLM se calcula por tokens de entrada y de salida. Una temperatura baja (0–0,3) hace las respuestas más deterministas, que es lo que quieres en casi cualquier caso de backend.

La API key sigue las mismas reglas que cualquier secreto de la aplicación de doce factores: fuera del código, inyectada por entorno y distinta en cada entorno.

ChatClient: tu primera llamada a un LLM desde Spring Boot

Spring AI autoconfigura un ChatClient.Builder con el modelo del starter. Lo habitual es construir un ChatClient por caso de uso, con su prompt de sistema:

@Configuration class IaConfig { @Bean ChatClient asistenteSoporte(ChatClient.Builder builder) { return builder // El prompt de sistema fija rol, tono y límites para TODAS las llamadas .defaultSystem(""" Eres el asistente de soporte de una tienda online. Respondes en español, de forma breve y amable. Solo hablas de pedidos, envíos y devoluciones. Si no sabes algo, dilo; nunca inventes datos. """) .defaultAdvisors(new SimpleLoggerAdvisor()) // logs en DEBUG de petición y respuesta .build(); } }

Y la llamada, con la misma API fluida que ya conoces de los clientes REST de Spring:

@RestController @RequestMapping("/api/soporte") class SoporteController { private final ChatClient chatClient; SoporteController(ChatClient asistenteSoporte) { this.chatClient = asistenteSoporte; } @PostMapping("/preguntas") RespuestaDto preguntar(@Valid @RequestBody PreguntaDto pregunta) { String respuesta = chatClient.prompt() .user(pregunta.texto()) // el mensaje del usuario .call() // llamada síncrona .content(); // solo el texto de la respuesta return new RespuestaDto(respuesta); } } record PreguntaDto(@NotBlank @Size(max = 2000) String texto) {} record RespuestaDto(String texto) {}

Fíjate en el @Size(max = 2000): validar la longitud de la entrada con Bean Validation no es un detalle estético. Cada carácter que dejas pasar son tokens que pagas, y un usuario malicioso puede enviarte un texto de cien páginas.

Un detalle de la API que confunde al principio: call() no ejecuta nada por sí solo. La petición al modelo ocurre cuando pides el resultado con content(), entity(), chatResponse() o responseEntity(). Si necesitas metadatos como el uso de tokens o el motivo de fin, usa chatResponse() en lugar de content().

Salida estructurada: del texto libre a objetos Java

Un texto libre está bien para un chat, pero la mayoría de casos de backend necesitan datos: clasificar un ticket, extraer campos de un correo, puntuar una reseña. Para eso existe entity(), que convierte la respuesta del modelo en un objeto Java:

enum Categoria { PEDIDO, ENVIO, DEVOLUCION, FACTURACION, OTRO } enum Prioridad { BAJA, MEDIA, ALTA } // Un record con nombres claros es, en la práctica, parte del prompt record ClasificacionTicket( Categoria categoria, Prioridad prioridad, String resumen, // una frase boolean requiereHumano) {} @Service class ClasificadorTickets { private final ChatClient chatClient; ClasificadorTickets(ChatClient.Builder builder) { this.chatClient = builder .defaultSystem("Clasificas tickets de soporte de una tienda online.") .build(); } ClasificacionTicket clasificar(String textoTicket) { return chatClient.prompt() .user(u -> u.text("Clasifica este ticket:\n{ticket}") .param("ticket", textoTicket)) .call() .entity(ClasificacionTicket.class, spec -> spec .useProviderStructuredOutput() // usa el modo JSON nativo del proveedor si existe .validateSchema()); // valida la respuesta contra el esquema } }

Por debajo, Spring AI genera un JSON Schema a partir del record, lo añade a las instrucciones (o se lo pasa al proveedor si soporta salida estructurada nativa) y deserializa la respuesta. Con validateSchema() comprueba además que el JSON cumple el esquema antes de devolvértelo; y Spring AI 2.0 incluye un StructuredOutputValidationAdvisor capaz de reintentar pidiendo al modelo que corrija una respuesta inválida.

Aun así, trata el resultado como entrada no confiable. Que el JSON sea válido no significa que el contenido sea correcto: el modelo puede elegir la categoría equivocada. Si una decisión tiene consecuencias (reembolsar, bloquear una cuenta), la IA propone y tu código decide con reglas explícitas.

Para listas, usa ParameterizedTypeReference igual que con RestClient:

List<ClasificacionTicket> lote = chatClient.prompt() .user("Clasifica cada uno de estos tickets: ...") .call() .entity(new ParameterizedTypeReference<List<ClasificacionTicket>>() {});

Tool calling en Spring AI: que el modelo use tu código

Un modelo no sabe en qué estado está el pedido 42 de tu tienda. El tool calling (antes llamado function calling) le permite pedirle a tu aplicación que ejecute un método y le devuelva el resultado. Importante: el modelo nunca ejecuta nada. Solo responde "quiero llamar a consultarPedido con id=42"; es Spring AI, en tu proceso, quien ejecuta el método y le devuelve la respuesta.

Flujo de tool calling en Spring AI: el usuario pregunta por su pedido, ChatClient envía el prompt con las definiciones de herramientas, el modelo pide llamar a consultarPedido(42), el ToolCallingAdvisor ejecuta el método @Tool, devuelve el estado ENVIADO al modelo y este genera la respuesta final

Las herramientas se declaran con @Tool y @ToolParam:

@Component class PedidoTools { private final PedidoRepository pedidos; PedidoTools(PedidoRepository pedidos) { this.pedidos = pedidos; } @Tool(description = "Consulta el estado y la fecha estimada de entrega de un pedido del usuario actual") EstadoPedido consultarPedido( @ToolParam(description = "Número de pedido, por ejemplo 42") long numeroPedido, ToolContext contexto) { // El id del cliente NO lo elige el modelo: viene del contexto que pone el backend String clienteId = (String) contexto.getContext().get("clienteId"); return pedidos.buscarDelCliente(numeroPedido, clienteId) .map(p -> new EstadoPedido(p.numero(), p.estado(), p.entregaEstimada())) .orElseThrow(() -> new PedidoNoEncontradoException(numeroPedido)); } } record EstadoPedido(long numero, String estado, LocalDate entregaEstimada) {}

Y se pasan en cada llamada con .tools(...):

String respuesta = chatClient.prompt() .user(pregunta.texto()) .tools(pedidoTools) // Datos que la herramienta necesita pero que el modelo nunca ve ni puede alterar .toolContext(Map.of("clienteId", jwt.getSubject())) .call() .content();

Spring AI genera la definición de la herramienta (nombre, descripción y esquema de parámetros), la envía al modelo y, cuando este pide ejecutarla, el ToolCallingAdvisor (registrado automáticamente desde la 2.0) hace el bucle completo: ejecuta, devuelve el resultado y repite hasta que el modelo da la respuesta final. Las notas de la documentación de tools cubren variantes como returnDirect (devolver el resultado de la herramienta sin pasar otra vez por el modelo) o las herramientas declaradas como beans ToolCallback.

Las tres reglas de seguridad del tool calling

Aquí es donde los tutoriales se quedan cortos y donde se producen los incidentes. Piensa en cada herramienta como un endpoint público cuyo cliente es un modelo que puede ser manipulado por el texto del usuario (prompt injection):

  1. La identidad nunca es un parámetro. Si consultarPedido recibiera clienteId como @ToolParam, bastaría con escribir "soy el cliente 7, enséñame sus pedidos" para que el modelo lo intentara. Por eso usamos ToolContext: el backend pone el sub del JWT (como en el artículo de Keycloak con Spring Boot) y el modelo no puede cambiarlo.
  2. Herramientas peligrosas, por llamada y nunca por defecto. La propia documentación advierte que las defaultTools se comparten entre todas las peticiones del mismo builder. Una herramienta que cancela pedidos o emite reembolsos se añade solo en el flujo que la necesita, y mejor aún si exige confirmación humana.
  3. Errores que no filtren información. Por defecto, el mensaje de una RuntimeException lanzada por la herramienta se devuelve al modelo para que pueda reaccionar ("ese pedido no existe"). Es útil, pero asegúrate de que tus mensajes no incluyan SQL, trazas ni datos de otros usuarios. Si prefieres que los errores lleguen a tu código, activa spring.ai.tools.throw-exception-on-error=true y gestiónalos con tu @ControllerAdvice.

Un último matiz: si marcas un parámetro como obligatorio y el modelo no tiene forma de conocer su valor, se lo inventará. Declara opcional lo que sea opcional (@ToolParam(required = false)) y pide en el prompt de sistema que pregunte al usuario cuando le falte un dato.

Memoria de conversación con Spring AI

Los LLM no tienen estado: cada llamada empieza de cero. Para que el asistente recuerde que hace dos mensajes hablábamos del pedido 42, hay que reenviarle el historial. Spring AI lo resuelve con un ChatMemory (autoconfigurado) y el MessageChatMemoryAdvisor:

@Bean ChatClient asistenteConMemoria(ChatClient.Builder builder, ChatMemory chatMemory) { return builder .defaultSystem("Eres el asistente de soporte de una tienda online...") .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build()) .build(); }
String respuesta = chatClient.prompt() .user(pregunta.texto()) // Obligatorio en Spring AI 2.0: sin conversationId lanza IllegalArgumentException .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversacionId)) .call() .content();

El ChatMemory por defecto es un MessageWindowChatMemory: guarda una ventana deslizante de 20 mensajes por conversación, descarta los más antiguos y conserva siempre el mensaje de sistema. Por defecto vive en memoria, lo que significa que se pierde al reiniciar y no se comparte entre réplicas. En producción, con varios pods en Kubernetes, necesitas persistirlo.

Memoria de conversación en Spring AI: cada usuario envía su conversationId, el MessageChatMemoryAdvisor recupera el historial de MessageWindowChatMemory, que mantiene una ventana de 20 mensajes conservando el mensaje de sistema y persiste en JdbcChatMemoryRepository sobre PostgreSQL, y envía historial más nueva pregunta al modelo

Para persistirlo en una base relacional basta con añadir spring-ai-starter-model-chat-memory-repository-jdbc: Spring AI usará el JdbcChatMemoryRepository en lugar del repositorio en memoria.

spring: ai: chat: memory: repository: jdbc: # Con PostgreSQL y Flyway, crea la tabla en tus migraciones initialize-schema: never

Tres cosas a vigilar con la memoria:

  • El conversationId es un dato de seguridad. Si lo recibes del cliente sin más, un usuario podría leer la conversación de otro adivinando el id. Compón el id con la identidad autenticada (por ejemplo, sub del JWT + id de sesión de chat) o valida que le pertenece. Si usas Flyway, versiona también el esquema de la tabla.
  • Más memoria es más coste. Cada mensaje del historial se reenvía en cada petición y se paga como tokens de entrada. Una ventana de 20 mensajes largos puede multiplicar el coste por diez frente a una pregunta suelta. Ajusta maxMessages a lo que tu caso necesita.
  • El repositorio JDBC no guarda las llamadas a herramientas. Según la documentación de chat memory, los mensajes de tool calling se filtran al guardar. Para historiales completos y compactación con resumen, Spring AI 2.0 presenta el proyecto spring-ai-session como reemplazo, y en la 2.1 el MessageChatMemoryAdvisor ya aparece marcado como deprecado en su favor. Ten en el radar esa migración.

Streaming de respuestas

Una respuesta larga puede tardar varios segundos. Con stream() recibes los fragmentos a medida que el modelo los genera, como en ChatGPT:

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) Flux<String> preguntarEnStreaming(@RequestParam @NotBlank @Size(max = 2000) String texto) { return chatClient.prompt() .user(texto) .stream() .content(); // Flux<String> con cada fragmento }

No necesitas pasarte a WebFlux: Spring MVC sabe devolver un Flux como Server-Sent Events. Si tu aplicación ya es reactiva, encaja de forma natural con lo que vimos en Spring WebFlux. Ten en cuenta dos limitaciones: entity() no tiene sentido en streaming (necesitas el JSON completo para deserializar) y, si el cliente corta la conexión, la petición al proveedor puede seguir consumiendo tokens hasta que se cancele la suscripción.

Varios modelos en la misma aplicación

Un patrón cada vez más habitual: un modelo pequeño y barato para clasificar, uno grande para razonar, y uno local con Ollama para datos que no pueden salir de tu red. Con varios starters tendrás varios ChatModel, y aquí hay una trampa: la documentación de ChatClient avisa de que construirlos con ChatClient.create(chatModel) o ChatClient.builder(chatModel) se salta la observabilidad y los ChatClientBuilderCustomizer que aplica la autoconfiguración. La forma recomendada es pasar al builder el registro de observaciones y el builder del ToolCallingAdvisor, y terminar con el ChatClientBuilderConfigurer:

@Configuration class ModelosConfig { @Bean @Primary ChatClient clienteNube(AnthropicChatModel modelo, ChatClientBuilderConfigurer configurer, ObjectProvider<ObservationRegistry> registry, ObjectProvider<ChatClientObservationConvention> chatConvention, ObjectProvider<AdvisorObservationConvention> advisorConvention, ObjectProvider<ToolCallingAdvisor.Builder<?>> toolCalling) { return crear(modelo, configurer, registry, chatConvention, advisorConvention, toolCalling); } @Bean ChatClient clienteLocal(OllamaChatModel modelo, ChatClientBuilderConfigurer configurer, ObjectProvider<ObservationRegistry> registry, ObjectProvider<ChatClientObservationConvention> chatConvention, ObjectProvider<AdvisorObservationConvention> advisorConvention, ObjectProvider<ToolCallingAdvisor.Builder<?>> toolCalling) { // Para datos sensibles: el modelo corre en tu infraestructura return crear(modelo, configurer, registry, chatConvention, advisorConvention, toolCalling); } private ChatClient crear(ChatModel modelo, ChatClientBuilderConfigurer configurer, ObjectProvider<ObservationRegistry> registry, ObjectProvider<ChatClientObservationConvention> chatConvention, ObjectProvider<AdvisorObservationConvention> advisorConvention, ObjectProvider<ToolCallingAdvisor.Builder<?>> toolCalling) { ChatClient.Builder builder = ChatClient.builder(modelo, registry.getIfUnique(() -> ObservationRegistry.NOOP), // métricas y trazas chatConvention.getIfUnique(), advisorConvention.getIfUnique(), toolCalling.getIfAvailable()); // bucle de herramientas // Aplica los ChatClientBuilderCustomizer registrados, como haría la autoconfiguración return configurer.configure(builder).build(); } }

Es más verboso de lo que debería, pero si usas el atajo ChatClient.builder(modelo) perderás justo las métricas de tokens que necesitas para controlar costes.

También puedes cambiar opciones por llamada sin tocar la configuración global, pasando un builder de opciones: en la 2.0, .options() recibe un ChatOptions.Builder y solo sobrescribe los campos que indiques.

chatClient.prompt("Resume este texto en una frase: ...") .options(AnthropicChatOptions.builder().maxTokens(100).temperature(0.0)) .call() .content();

Tests de una aplicación con Spring AI

Probar código que llama a un LLM tiene dos problemas: las respuestas no son deterministas y cada test cuesta dinero. La estrategia que mejor me funciona tiene tres niveles.

1. Aísla la IA detrás de un puerto. Igual que en la arquitectura hexagonal, tu dominio no debería conocer ChatClient. Define una interfaz y testea la lógica de negocio con un mock:

// Puerto: lo que el dominio necesita, sin saber que hay un LLM detrás interface ClasificadorPort { ClasificacionTicket clasificar(String texto); } @Test void escalaAHumanoLosTicketsDeAltaPrioridad() { ClasificadorPort clasificador = texto -> new ClasificacionTicket( Categoria.DEVOLUCION, Prioridad.ALTA, "Producto roto", true); var servicio = new GestionTicketsService(clasificador, colaHumanos); servicio.procesar("Me llegó la pantalla rota y nadie me responde"); verify(colaHumanos).encolar(any()); }

2. Prueba la integración con un modelo local. Para verificar que el prompt, el esquema y las herramientas encajan, ejecuta un modelo pequeño con Ollama en Testcontainers. Es gratis, reproducible y no envía datos a terceros. No esperes las mismas respuestas que el modelo de producción: aquí compruebas el cableado (que la herramienta se invoca, que el JSON se deserializa), no la calidad.

3. Evalúa la calidad aparte. La calidad de las respuestas se mide con un conjunto fijo de casos (preguntas y respuestas esperadas) que se ejecuta contra el modelo real de forma periódica o antes de cambiar de modelo o de prompt, no en cada mvn test. Spring AI incluye evaluadores (por ejemplo, de relevancia) que usan un LLM como juez, útiles para automatizar parte de esa revisión.

Observabilidad y control de costes

Un servicio con IA tiene una métrica que ningún otro tiene: el coste por petición. Spring AI instrumenta ChatClient y ChatModel con Micrometer, así que con Spring Boot Actuator tienes de serie:

  • gen_ai.client.token.usage: tokens consumidos, etiquetados por tipo (input, output, total) y modelo. En Prometheus aparece como gen_ai_client_token_usage_total.
  • Duración y peticiones activas de las operaciones de ChatClient.
  • Spans de cada llamada al modelo y a cada herramienta, que se integran con las trazas distribuidas que montamos en OpenTelemetry con Spring Boot.

Con esa métrica puedes construir un panel de coste por endpoint y una alerta cuando el consumo se dispara. Según la documentación de observabilidad de Spring AI, el contenido de prompts y respuestas no se registra por defecto (spring.ai.chat.client.observations.log-prompt y log-completion valen false), y conviene dejarlo así en producción: los prompts suelen contener datos personales.

Para mantener el coste bajo control, combina varias palancas:

  • max-tokens y validación de longitud de la entrada, como vimos.
  • Rate limiting por usuario en los endpoints de IA; las técnicas de rate limiting para APIs aplican tal cual, pero cuenta tokens además de peticiones.
  • Caché de respuestas para preguntas repetidas y deterministas (clasificación de textos idénticos, por ejemplo).
  • El modelo adecuado para cada tarea: clasificar o extraer campos rara vez necesita el modelo más caro.

Errores, timeouts y resiliencia

Los proveedores de LLM fallan más que una base de datos: límites de tasa (HTTP 429), sobrecarga, latencias de decenas de segundos. Trata la llamada al modelo como cualquier dependencia remota:

  • Timeouts explícitos. Una petición colgada 60 segundos bloquea un hilo (o una conexión con Virtual Threads, que al menos es barata). Revisa la configuración de timeouts y reintentos del cliente de tu proveedor.
  • Circuit breaker y fallback. Envuelve el servicio que llama al modelo con Resilience4J: si el proveedor está caído, devuelve una respuesta degradada ("ahora mismo no puedo responder, te paso con una persona") en lugar de un 500.
  • Reintentos con cuidado. Reintentar un 429 sin backoff empeora el problema, y reintentar una llamada que ejecutó herramientas con efectos puede duplicarlos. Las herramientas que modifican estado deben ser idempotentes.

¿Cuándo usar Spring AI y cuándo no?

Usa Spring AI si tu backend ya es Spring Boot y quieres integrar LLM con las mismas convenciones que el resto: inyección de dependencias, propiedades por entorno, Actuator, Micrometer, tests con Spring. También si quieres poder cambiar de proveedor sin reescribir el código, o mezclar modelos en la nube y locales.

Quizá no lo necesites si solo haces una llamada puntual a un proveedor y no prevés cambiarlo: el SDK oficial del proveedor puede bastar. Y si tu caso es un agente complejo con muchas herramientas, planificación y estado largo, evalúa también LangChain4j, la otra gran librería del ecosistema Java, que tiene integración con Spring Boot y una API más orientada a "servicios de IA" declarativos. No son excluyentes, pero mezclar las dos en el mismo servicio rara vez compensa.

Y sobre todo, no uses un LLM donde basta una regla. Si puedes resolver la clasificación con una expresión regular o una consulta SQL, será más rápida, más barata, determinista y testeable.

Buenas prácticas

  1. Fija versión de Spring AI, modelo y max-tokens en la configuración; nada de valores por defecto en producción.
  2. Un ChatClient por caso de uso, con su prompt de sistema versionado como código (o en un fichero de recursos), no prompts sueltos por el código.
  3. Salida estructurada para datos, con validación de esquema, y la decisión final en tu código.
  4. Herramientas como endpoints públicos: identidad por ToolContext, permisos mínimos, idempotencia y nada peligroso en defaultTools.
  5. Memoria persistida y aislada por usuario, con una ventana ajustada al coste que puedes asumir.
  6. Mide tokens por endpoint y alerta sobre el coste igual que alertas sobre la latencia.
  7. Protege la llamada al modelo con timeouts, circuit breaker y un fallback útil.
  8. No registres prompts en producción salvo con anonimización y una razón concreta.

Preguntas frecuentes

¿Qué es Spring AI y para qué sirve?

Spring AI es el proyecto oficial de Spring para integrar modelos de IA en aplicaciones Java. Ofrece una API común, ChatClient, sobre proveedores como Anthropic, OpenAI, Google u Ollama, y añade salida estructurada, tool calling, memoria de conversación, RAG y métricas, todo con la autoconfiguración de Spring Boot.

¿Qué versión de Spring Boot necesita Spring AI 2.0?

Spring AI 2.0.x está diseñado para Spring Boot 4.0 y 4.1 con Spring Framework 7. Si tu proyecto sigue en Spring Boot 3, tendrás que quedarte en Spring AI 1.x o migrar primero a Spring Boot 4.

¿Cuál es la diferencia entre ChatClient y ChatModel?

ChatModel es la interfaz de bajo nivel que implementa cada proveedor: recibe un Prompt y devuelve un ChatResponse. ChatClient es la API fluida construida encima, con soporte para advisors, herramientas, memoria y salida estructurada. En Spring AI 2.0, ChatClient es la API recomendada para el código de aplicación.

¿Spring AI funciona con Claude, OpenAI y modelos locales?

Sí. Cada proveedor tiene su starter (spring-ai-starter-model-anthropic, spring-ai-starter-model-openai, spring-ai-starter-model-ollama, entre otros). Cambiar de proveedor consiste en cambiar la dependencia y las propiedades; el código que usa ChatClient no cambia, salvo opciones específicas de cada modelo.

¿Cómo evito que el modelo acceda a datos de otros usuarios con tool calling?

No dejes que el modelo elija la identidad: pasa el id del usuario autenticado con toolContext(...), que llega a la herramienta sin que el modelo lo vea ni lo pueda modificar, y aplica en la herramienta los mismos controles de autorización que en cualquier endpoint.

¿Spring AI o LangChain4j?

Ambas son buenas opciones en Java. Spring AI encaja de forma natural si ya usas Spring Boot y quieres sus convenciones (beans, propiedades, Actuator, Micrometer). LangChain4j tiene una API más declarativa para servicios de IA y agentes, y también se integra con Spring Boot. Elige una por servicio y evita mezclarlas.

Conclusión

Integrar Spring AI con Spring Boot es, sobre todo, tratar a un modelo de lenguaje como lo que es: una dependencia remota, cara, lenta a veces y no determinista. Spring AI te da las herramientas para domarla con las convenciones de siempre: un ChatClient por caso de uso, salida estructurada en lugar de texto que parsear, herramientas declaradas con @Tool, memoria persistida por conversación y métricas de tokens en Micrometer. La versión 2.0, alineada con Spring Boot 4, consolida esas piezas y elimina mucha de la API experimental que todavía aparece en los tutoriales antiguos.

Si te quedas con lo esencial: fija versión, modelo y max-tokens; convierte las respuestas en records validados; diseña cada herramienta como un endpoint público, con la identidad en el ToolContext; aísla la conversación de cada usuario; y mide lo que cuesta cada petición desde el primer día. Con eso, añadir IA a tu backend deja de ser un experimento y pasa a ser una funcionalidad más, con sus tests, sus alertas y sus límites.