ChatClient de Spring AI: prompts, opciones, salida estructurada y streaming
Cómo usar ChatClient en Spring AI 2.0: system y user con plantillas, opciones por petición, entity() a un record con validación y streaming con Flux.
Escrito contra Spring AI 2.0.2, Spring Boot 4.1.2 y Java 21. Los ejemplos se compilaron y se ejecutaron contra un modelo local (Ollama,
gpt-oss), sin claves de pago.
Llamar a un modelo con el cliente de bajo nivel (ChatModel) funciona, pero te obliga a montar a mano la lista de mensajes, sustituir variables, pedir JSON y parsearlo. ChatClient es la capa de Spring AI que resuelve eso con una API fluida: construyes la petición por partes, eliges si quieres texto, un objeto Java o un flujo, y el resto (plantillas, formato, conversión) lo hace el framework.
Este artículo recorre las piezas con un único ejemplo: un servicio que revisa fragmentos de código Java. Si además quieres que el asistente recuerde la conversación, eso va en memoria de chat con advisors.
Vídeo explicativo
Dependencias y construcción del cliente
Con el starter de un modelo, Spring Boot registra un ChatClient.Builder (con ámbito prototype). Tú lo inyectas y construyes el cliente una vez, con los valores por defecto que no cambian entre peticiones:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
spring.ai.ollama.chat.options.model=gpt-oss
spring.ai.ollama.chat.options.temperature=0.2
@Configuration
class ChatConfig {
@Bean
ChatClient chatClient(ChatClient.Builder builder) {
return builder
.defaultSystem("Eres un revisor de código Java. Respondes siempre en español y con brevedad.")
.build();
}
}
defaultSystem, defaultUser, defaultOptions, defaultTools y defaultAdvisors fijan valores para todas las llamadas; cada uno tiene su gemelo sin default para cambiarlo en una sola petición.
Prompts: system, user y parámetros
prompt() abre la petición. El texto de user y de system son plantillas: las variables se escriben entre llaves y se rellenan con param.
String explain(String code) {
return chatClient.prompt()
.user(u -> u.text("Explica qué hace este código en dos frases:\n{code}")
.param("code", code))
.call()
.content();
}
call() solo indica que la llamada será síncrona; el modelo se invoca cuando pides el resultado (content(), chatResponse(), entity()…). Si en una petición defines system(...), sustituye al defaultSystem solo en esa petición. Lo comprobamos con un modelo falso en un test: el mensaje de sistema que llegó al modelo era el de la petición, no el del cliente.
Trampa habitual: el motor de plantillas por defecto (StringTemplate) trata { y } como delimitadores. Si metes JSON en el prompt, la plantilla se rompe. Cambia los delimitadores con .templateRenderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build()).
Opciones por petición
Las opciones del modelo (temperatura, tokens máximos…) salen de application.properties, pero puedes pisarlas en una llamada concreta con las del proveedor:
String explainStrict(String code) {
return chatClient.prompt()
.options(OllamaChatOptions.builder().temperature(0.0).numPredict(200))
.user(u -> u.text("Explica qué hace este código en una frase:\n{code}").param("code", code))
.call()
.content();
}
En el test comprobamos que la temperatura que recibe el modelo es 0.0. Usar la clase de opciones del proveedor te ata a ese proveedor; las opciones portables de ChatOptions sirven si cambias de modelo con frecuencia.
Salida estructurada con entity()
Aquí está el mayor ahorro de código. Defines un record y entity() hace tres cosas: añade al prompt las instrucciones de formato (el esquema JSON), llama al modelo y convierte la respuesta.
record Review(String resumen, int nota, List<String> problemas) {}
Review review(String code) {
return chatClient.prompt()
.system(s -> s.text("{base} Nota: de 0 a 10.").param("base", "Evalúa el código."))
.user(u -> u.text("Revisa este código:\n{code}").param("code", code))
.call()
.entity(Review.class);
}
List<Review> reviewAll(List<String> snippets) {
return chatClient.prompt()
.user("Revisa cada uno de estos fragmentos:\n" + String.join("\n---\n", snippets))
.call()
.entity(new ParameterizedTypeReference<List<Review>>() {});
}
Contra gpt-oss en local, enviando String s = null; if (s.equals("a")) {...}, devolvió:
{"resumen":"El código provoca una NullPointerException al intentar llamar a equals sobre una referencia nula.","nota":2,"problemas":["NullPointerException al llamar a equals sobre una referencia nula","No se verifica si s es nulo antes de usarlo","..."]}
Qué falla y cómo saberlo
entity() no garantiza que el modelo obedezca. Con un modelo falso que responde en prosa ("Claro, aquí tienes mi revisión…") la llamada lanza una StreamReadException de Jackson 3 (tools.jackson.core.exc): Unrecognized token 'Claro'. Si ves ese error en producción, el modelo ha ignorado el formato; mira el texto real con un SimpleLoggerAdvisor.
Lo que sí tolera: si el modelo envuelve el JSON en una valla ```json, la conversión funciona (lo probamos).
La documentación ofrece dos interruptores de fiabilidad:
.entity(Review.class, spec -> spec.validateSchema())
validateSchema() valida el JSON contra el esquema del record y reintenta con el error como feedback. En nuestro test, la primera respuesta no traía nota ni problemas: la segunda llamada sí, y el resultado fue correcto tras 2 llamadas al modelo. Cada reintento cuesta tokens y latencia, así que no lo actives por sistema. useProviderStructuredOutput() envía el esquema al proveedor como restricción de la API en lugar de como texto; no lo ejecutamos contra ningún proveedor, así que consulta en la referencia de salida estructurada cuáles lo soportan.
Streaming
Con stream() obtienes un Flux:
Flux<String> explainStreaming(String code) {
return chatClient.prompt()
.user(u -> u.text("Explica paso a paso:\n{code}").param("code", code))
.stream()
.content();
}
@PostMapping(value = "/explain", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
Flux<String> explain(@RequestBody String code) {
return service.explainStreaming(code);
}
Según la documentación, el streaming solo funciona sobre el stack reactivo: una app imperativa debe incluir spring-boot-starter-webflux además del starter web. Nosotros pusimos ambos. Ejecutándolo con curl -N los fragmentos llegan como eventos SSE (data:Paso, data: a, data: paso…), a nivel de token, incluidos los espacios y los saltos de línea; si los pintas en un front, concatena sin añadir separadores.
Dos límites que conviene conocer:
stream()no tiene todavía unentity()equivalente. Para obtener un objeto, acumula el texto y conviértelo conBeanOutputConverter, como indica la referencia.- Tienes que decidir cuándo parsear: un JSON a medias no se puede convertir, así que espera a que termine el flujo.
Metadatos de uso y respuesta completa
content() descarta todo salvo el texto. Cuando necesites saber cuántos tokens consumió una llamada (los modelos alojados cobran por token) o qué generaciones devolvió, pide chatResponse() en lugar de content(). Y si quieres a la vez el objeto Java y la respuesta completa, existe responseEntity(Review.class). Es un cambio de una línea, pero conviene decidirlo al diseñar el servicio: registrar el uso de tokens por petición es lo primero que se echa de menos cuando llega la factura.
Cómo probarlo sin pagar ni esperar
Nada de lo anterior necesita un modelo real para tener tests. ChatClient.builder(...) acepta cualquier ChatModel, y ChatModel solo exige implementar call(Prompt). Con una clase de diez líneas que guarda los prompts recibidos y devuelve un texto fijo, puedes comprobar qué mensaje de sistema llega, que las variables de plantilla se sustituyeron, que las opciones por petición llegan al modelo y que el JSON se convierte al record:
static class StubModel implements ChatModel {
final List<Prompt> prompts = new ArrayList<>();
String reply = "ok";
@Override
public ChatResponse call(Prompt prompt) {
prompts.add(prompt);
return new ChatResponse(List.of(new Generation(new AssistantMessage(reply))));
}
}
Es el mismo modelo falso con el que comprobamos todas las afirmaciones de este artículo sobre el comportamiento de entity(). Lo que no prueba es la calidad de la respuesta del modelo: eso solo se ve con llamadas reales, aunque sean contra un modelo local.
Lo que ocurre por debajo
ChatClient envuelve la llamada en una cadena de advisors, y por eso la memoria, el RAG o el logging se enganchan sin tocar tu código. En 2.0 el cliente registra siempre un ToolCallingAdvisor para ejecutar herramientas; se puede desactivar con spring.ai.chat.client.tool-calling.enabled=false. El orden en que añades los advisors importa. Si necesitas varios modelos, la documentación advierte de que construir clientes con ChatClient.create(chatModel) se salta el builder autoconfigurado y, con él, observabilidad y customizers: usa ChatClientBuilderConfigurer.
Siguientes pasos
El patrón para quedarte: un cliente por rol (con su system por defecto), los valores variables como parámetros de plantilla y un record por cada salida que necesites. Si quieres llevarlo a una aplicación completa, el curso de Spring AI con Spring Boot construye estos mismos bloques paso a paso, y el máster AI Engineer con Java y Spring AI los lleva a producción con RAG, agentes y evaluación.
Artículos relacionados
Newsletter Semanal de Java
Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.
Sin spam. Cancela cuando quieras.