Tool calling en Spring AI: conecta tu LLM con Java usando @Tool
Cómo usar @Tool en Spring AI 2.0 para que un LLM llame a métodos Java: definir herramientas, registrarlas en ChatClient y resultado con un modelo real.
En resumen: con tool calling el modelo de lenguaje no ejecuta nada: recibe la lista de herramientas (nombre, descripción y parámetros), decide cuándo necesita una y le pide a tu aplicación que la ejecute. En Spring AI marcas métodos con
@Tooly@ToolParam, los registras con.tools(...)o.defaultTools(...)en elChatClient, y Spring se encarga del ida y vuelta. Probado con Spring AI 2.0.2, Spring Boot 4.1.2 y un modelo local (gpt-ossen Ollama).
Vídeo explicativo
Cómo funciona
1. Tu app envía la pregunta + el catálogo de herramientas al modelo
2. El modelo responde: "llama a estadoPedido(pedidoId=A-100)"
3. Spring AI ejecuta el método Java y devuelve el resultado al modelo
4. El modelo redacta la respuesta final con ese dato
El modelo solo ve nombres, descripciones y esquemas. Nunca accede a tu base de datos: lo hace tu código, con tus permisos y tus validaciones.
Dependencia y configuración
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
Con la versión gestionada por el BOM org.springframework.ai:spring-ai-bom:2.0.2. Para OpenAI, Anthropic u otro proveedor cambia el starter; el código de las herramientas es el mismo.
spring.ai.ollama.chat.options.model=gpt-oss
Definir las herramientas
record EstadoPedido(String id, String estado, LocalDate entregaEstimada) {}
@Component
class PedidoTools {
private final Map<String, EstadoPedido> pedidos = Map.of(
"A-100", new EstadoPedido("A-100", "ENVIADO", LocalDate.of(2026, 12, 2)),
"A-101", new EstadoPedido("A-101", "PREPARANDO", LocalDate.of(2026, 12, 9)));
@Tool(description = "Devuelve el estado y la fecha estimada de entrega de un pedido de la tienda")
EstadoPedido estadoPedido(@ToolParam(description = "Identificador del pedido, por ejemplo A-100") String pedidoId) {
System.out.println(" [tool] estadoPedido(" + pedidoId + ")");
EstadoPedido p = pedidos.get(pedidoId);
if (p == null) {
throw new IllegalArgumentException("No existe el pedido " + pedidoId);
}
return p;
}
@Tool(description = "Cancela un pedido que todavía no se ha enviado")
String cancelarPedido(@ToolParam(description = "Identificador del pedido") String pedidoId) {
System.out.println(" [tool] cancelarPedido(" + pedidoId + ")");
EstadoPedido p = pedidos.get(pedidoId);
if (p == null) {
return "No existe el pedido " + pedidoId;
}
if (p.estado().equals("ENVIADO")) {
return "El pedido " + pedidoId + " ya se envió y no puede cancelarse";
}
return "Pedido " + pedidoId + " cancelado";
}
}
Las descripciones son parte del prompt: es lo que lee el modelo para decidir qué herramienta usar y cómo rellenar los parámetros. Spring genera el esquema JSON a partir de la firma del método.
Registrarlas en el ChatClient
ChatClient chat = builder
.defaultSystem("Eres el asistente de una tienda. Responde en español, en una o dos frases. Usa las herramientas para consultar pedidos.")
.defaultTools(pedidoTools)
.build();
String respuesta = chat.prompt().user(pregunta).call().content();
defaultTools las deja disponibles en todas las peticiones; .tools(...) dentro de prompt() las añade solo a una. Si aún no conoces el cliente, empieza por el ChatClient de Spring AI.
Lo que pasó con el modelo real
PREGUNTA: ¿Cuándo llega el pedido A-100?
[tool] estadoPedido(A-100)
RESPUESTA: El pedido A‑100 ya está enviado y se estima que llegará el 2 de diciembre de 2026.
PREGUNTA: Cancela el pedido A-101, por favor
[tool] cancelarPedido(A-101)
RESPUESTA: El pedido A-101 ha sido cancelado con éxito.
PREGUNTA: ¿Qué pasa con el pedido ZZZ?
[tool] estadoPedido(ZZZ)
RESPUESTA: El pedido ZZZ no existe en nuestro sistema.
PREGUNTA: ¿Cuál es la capital de Francia?
RESPUESTA: La capital de Francia es París.
Cuatro comportamientos que conviene ver: eligió la herramienta correcta en cada caso, extrajo el identificador de la frase, convirtió la excepción de ZZZ en una respuesta amable y no llamó a ninguna herramienta cuando la pregunta no tenía que ver con pedidos. Las tres llamadas tardaron en total unos 50 segundos en un portátil, casi todo en el modelo local.
Seguridad y buenas prácticas
- Las herramientas de escritura son peligrosas.
cancelarPedidose ejecutó solo porque el usuario lo pidió en lenguaje natural. En producción, comprueba que el pedido pertenece al usuario autenticado dentro del método y pide confirmación para acciones irreversibles. - No confíes en los argumentos. El modelo puede inventar un identificador o recibir instrucciones maliciosas escondidas en el texto (prompt injection). Valida como validarías una petición HTTP.
- Pocas herramientas y bien descritas. Cada herramienta consume contexto en cada petición y aumenta la probabilidad de que el modelo elija mal.
- Mensajes de error útiles pero sin detalles internos: el modelo los lee y los repite.
- Modelos compatibles: no todos los modelos admiten herramientas; comprueba que el tuyo lo hace antes de depurar tu código.
Preguntas frecuentes
¿Es lo mismo que function calling?
Sí. «Function calling» era el nombre inicial de OpenAI; «tool calling» es el término general.
¿Y MCP?
MCP estandariza cómo publicar herramientas en un servidor para que cualquier cliente las use. Con @Tool, las herramientas viven dentro de tu propia aplicación.
¿Puedo devolver objetos?
Sí: Spring serializa el retorno a JSON para el modelo, como el EstadoPedido del ejemplo.
¿Cómo lo pruebo sin gastar tokens?
Prueba los métodos @Tool como métodos Java normales con JUnit, y deja una prueba con el modelo real para verificar que las descripciones funcionan.
Sigue aprendiendo
Tool calling, RAG, memoria y agentes se construyen paso a paso en el curso de Spring AI 2.0, y se llevan a producción con seguridad y evaluación en el máster AI Engineer con Java y Spring AI. Para recordar conversaciones, tienes memoria de chat en Spring AI.
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.