Tool Calling (Function Calling)

public class DateTimeTools {

    @Tool(description = "Get the current date and time in the user's time zone")
    public String currentDateTime() {
        return ZonedDateTime.now(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }
}

String answer = chatClient.prompt()
    .user("What day of the week is it tomorrow?")
    .tools(new DateTimeTools())
    .call()
    .content();

@Component
public class OrderTools {

    private final OrderRepository orders;

    public OrderTools(OrderRepository orders) {
        this.orders = orders;
    }

    @Tool(description = "Look up the status and delivery date of one of the current customer's orders by order number")
    public OrderStatusView orderStatus(
            @ToolParam(description = "Order number, for example WN-10231") String orderNumber,
            ToolContext context) {
        String customer = (String) context.getContext().get("customerEmail");
        return orders.findByNumberAndCustomerEmail(orderNumber, customer)
            .map(o -> new OrderStatusView(o.getNumber(), o.getStatus().name(), o.getExpectedDelivery()))
            .orElseThrow(() -> new IllegalArgumentException("No such order for this customer"));
    }

    @Tool(description = "List the current customer's five most recent orders")
    public List<OrderStatusView> recentOrders(ToolContext context) {
        String customer = (String) context.getContext().get("customerEmail");
        return orders.findTop5ByCustomerEmailOrderByCreatedAtDesc(customer).stream()
            .map(o -> new OrderStatusView(o.getNumber(), o.getStatus().name(), o.getExpectedDelivery()))
            .toList();
    }
}

public record OrderStatusView(String number, String status, LocalDate expectedDelivery) {}

@PostMapping("/api/support/chat")
public String chat(@RequestBody String message, Principal principal) {
    return supportClient.prompt()
        .user(message)
        .tools(orderTools)
        .toolContext(Map.of("customerEmail", principal.getName()))  // the model never sees or sets this
        .call()
        .content();
}

public record WeatherRequest(@ToolParam(description = "City name, e.g. Pune") String city) {}
public record WeatherResponse(String city, double temperatureC, String conditions) {}

@Configuration(proxyBeanMethods = false)
public class WeatherToolConfig {

    @Bean
    ToolCallback currentWeather(WeatherService weatherService) {
        return FunctionToolCallback.builder("currentWeather", weatherService::lookup)
            .description("Get the current weather for a city")
            .inputType(WeatherRequest.class)
            .build();
    }
}

@RestController
public class TravelController {

    private final ChatClient chatClient;
    private final ToolCallback currentWeather;

    public TravelController(ChatClient.Builder builder, ToolCallback currentWeather) {
        this.chatClient = builder.build();
        this.currentWeather = currentWeather;
    }

    @GetMapping("/travel-tip")
    public String tip(@RequestParam String city) {
        return chatClient.prompt()
            .user("Should I carry an umbrella in " + city + " today?")
            .tools(currentWeather)
            .call()
            .content();
    }
}

public class RefundTools {

    private final RefundService refunds;

    public RefundTools(RefundService refunds) {
        this.refunds = refunds;
    }

    // The model may only PROPOSE a refund; a human must approve it in the admin UI
    @Tool(description = "Create a refund request for review by staff. Does not refund money directly.",
          returnDirect = true)
    public String requestRefund(@ToolParam(description = "Order number") String orderNumber,
                                @ToolParam(description = "Reason given by the customer") String reason,
                                ToolContext context) {
        String customer = (String) context.getContext().get("customerEmail");
        RefundRequest req = refunds.createPendingRequest(customer, orderNumber, reason);
        return "Refund request " + req.id() + " created. Our team will review it within 2 working days.";
    }
}