Spring AI Function Calling & @Tool

package com.javaagentic.demo.tools;
 
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
 
@Component
public class OrderTools {
 
    private final OrderRepository orders;
 
    public OrderTools(OrderRepository orders) {
        this.orders = orders;
    }
 
    /**
     * The description is the API contract as far as the model is concerned.
     * Say when to use it and what it returns — the model cannot read this code.
     */
    @Tool(description = """
            Look up the delivery status of a customer order.
            Use this whenever a customer asks where their order is or when it
            will arrive. Returns the status and, when known, the expected
            delivery date. Returns NOT_FOUND if no such order exists.
            """)
    public String getOrderStatus(
            @ToolParam(description = "The order ID, in the format A-123") String orderId) {
 
        return orders.findById(orderId)
                .map(order -> "%s, expected %s".formatted(
                        order.status(), order.expectedDelivery()))
                // A returned error keeps the model in the loop and lets it ask
                // the customer for a correct ID. A thrown exception aborts the
                // whole request and produces a generic failure.
                .orElse("NOT_FOUND: no order with ID " + orderId);
    }
}

@Service
public class SupportAssistant {
 
    private final ChatClient chatClient;
 
    public SupportAssistant(ChatClient.Builder builder, OrderTools orderTools) {
        this.chatClient = builder
                .defaultSystem("""
                        You are a customer support assistant.
                        Use the available tools to look up real data.
                        Never invent an order status — if a lookup fails, say so
                        and ask the customer to check the ID.
                        """)
                .defaultTools(orderTools)
                .build();
    }
 
    public String handle(String message) {
        return chatClient.prompt().user(message).call().content();
    }
}

// Poor: describes the implementation
@Tool(description = "Queries the orders table")
 
// Poor: too terse to disambiguate
@Tool(description = "Get order")
 
// Good: when to use it, what it needs, what comes back
@Tool(description = """
        Look up the delivery status of a customer order by its ID.
        Use when a customer asks about the location, status or arrival
        date of an existing order. Requires the order ID (format A-123).
        Returns status and expected delivery date, or NOT_FOUND.
        """)

package com.javaagentic.demo.tools;
 
import java.time.LocalDate;
 
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
 
@Component
public class BookingTools {
 
    /**
     * An enum parameter is far more reliable than a free-text one: the schema
     * enumerates the permitted values, so the model cannot invent "ECONOMY_PLUS".
     */
    public enum CabinClass { ECONOMY, PREMIUM, BUSINESS }
 
    public record FlightSearch(
            @ToolParam(description = "Departure airport IATA code, e.g. LHR") String from,
            @ToolParam(description = "Arrival airport IATA code, e.g. JFK") String to,
            @ToolParam(description = "Departure date in ISO-8601 format") LocalDate date,
            @ToolParam(description = "Cabin class") CabinClass cabin) {}
 
    @Tool(description = """
            Search available flights between two airports on a given date.
            Use only when you have all of: origin, destination and date.
            If any is missing, ask the customer for it first.
            """)
    public String searchFlights(FlightSearch request) {
        // The model is not to be trusted with input validation. It fills
        // arguments plausibly, not correctly.
        if (request.date().isBefore(LocalDate.now())) {
            return "ERROR: date is in the past. Ask the customer for a future date.";
        }
        return findFlights(request);
    }
}

@Tool(description = "Issue a refund for an order. Returns the refund reference.")
public String issueRefund(String orderId, String reason) {
    try {
        Order order = orders.findById(orderId)
                .orElse(null);
 
        if (order == null) {
            return "ERROR: no order " + orderId + ". Ask the customer to verify the ID.";
        }
        if (order.isRefunded()) {
            return "ERROR: order " + orderId + " has already been refunded.";
        }
        if (order.total().compareTo(AUTO_REFUND_LIMIT) > 0) {
            // Not a failure — a boundary. Tell the model what happens next so
            // it can set the right expectation with the customer.
            return "ESCALATED: amount exceeds the automatic refund limit. "
                    + "A human agent will review it within one business day.";
        }
 
        return "REFUNDED: reference " + refunds.issue(order, reason).reference();
 
    } catch (PaymentProviderException e) {
        log.error("refund failed for order {}", orderId, e);
        // Never surface a stack trace or internal detail to the model — it may
        // repeat it verbatim to the customer.
        return "ERROR: the refund could not be processed right now. "
                + "Ask the customer to try again later.";
    }
}

@Tool(description = "Cancel the current user's subscription at the end of the billing period.")
public String cancelSubscription(String confirmation) {
 
    // 1. Identity comes from the security context, NEVER from a tool argument.
    //    If the model can supply the user ID, the model can supply someone else's.
    String userId = SecurityContextHolder.getContext().getAuthentication().getName();
 
    // 2. Authorisation is checked in code, not requested in the system prompt.
    if (!subscriptions.canCancel(userId)) {
        return "ERROR: this account is not eligible for self-service cancellation.";
    }
 
    // 3. Irreversible actions get an explicit confirmation step.
    if (!"CONFIRM".equals(confirmation)) {
        return "CONFIRMATION_REQUIRED: ask the customer to confirm, then call "
                + "this tool again with confirmation=CONFIRM.";
    }
 
    // 4. Rate limit, so a looping agent cannot hammer a downstream system.
    if (!rateLimiter.tryAcquire(userId)) {
        return "ERROR: too many attempts. Ask the customer to try again shortly.";
    }
 
    subscriptions.cancelAtPeriodEnd(userId);
    return "CANCELLED: the subscription ends on " + subscriptions.periodEnd(userId);
}

String answer = chatClient.prompt()
        .user(question)
        .tools(orderTools)     // this request only
        .call()
        .content();

@Around("@annotation(org.springframework.ai.tool.annotation.Tool)")
public Object auditToolCall(ProceedingJoinPoint joinPoint) throws Throwable {
    long start = System.currentTimeMillis();
    try {
        Object result = joinPoint.proceed();
        log.info("tool={} args={} durationMs={}",
                joinPoint.getSignature().getName(),
                Arrays.toString(joinPoint.getArgs()),
                System.currentTimeMillis() - start);
        return result;
    } catch (Throwable t) {
        log.error("tool={} failed", joinPoint.getSignature().getName(), t);
        throw t;
    }
}