Artículo

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 @Tool y @ToolParam, los registras con .tools(...) o .defaultTools(...) en el ChatClient, 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-oss en 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. cancelarPedido se 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.

spring ai tool calling function calling llm java ollama

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.

Compartir artículo