[Spring AI 2025 Renewal #7] Tool Calling

안녕하세요 dev_writer입니다. 

 

이번 시간에는 Spring AI 공식 문서 중 Tool Calling에 대해 번역한 내용을 전달해 드리겠습니다.

 

Tool Calling

Tool calling(툴 호출, 혹은 함수 호출이라고도 함)은 AI 애플리케이션에서 모델이 API나 도구 집합과 상호작용할 수 있도록 하는 일반적인 패턴으로, 모델의 기능을 확장할 수 있도록 합니다. 도구는 주로 다음과 같은 목적에 사용됩니다:

 

1. 정보 검색(Information Retrieval) 

이 범주의 도구는 데이터베이스, 웹 서비스, 파일 시스템 또는 웹 검색 엔진과 같은 외부 소스에서 정보를 검색하는 데 사용됩니다. 목표는 모델의 지식을 증강하여, 그렇지 않으면 답할 수 없는 질문에 답할 수 있도록 하는 것입니다. 예를 들어, 주어진 위치의 현재 날씨를 조회하거나, 최신 뉴스 기사를 검색하거나, 데이터베이스에서 특정 레코드를 조회하는 데 사용할 수 있습니다. 이러한 활용은 RAG (Retrieval Augmented Generation) 시나리오에서 활용될 수 있습니다.

 

2. 작업 수행(Taking Action) 

이 범주의 도구는 이메일 전송, 데이터베이스에 새 레코드 생성, 양식 제출, 워크플로우 트리거 등과 같이 소프트웨어 시스템에서 작업을 수행하는 데 사용됩니다. 목표는 사람이 직접 수행하거나 명시적으로 프로그래밍해야 하는 작업을 자동화하는 것입니다. 예를 들어, 챗봇과 상호작용하는 고객을 위해 항공편을 예약하거나, 웹페이지의 양식을 자동으로 작성하거나, 테스트 주도 개발(TDD) 시나리오에서 자동화된 테스트 기반으로 Java 클래스를 구현할 수 있습니다.

 

툴 호출은 일반적으로 모델의 기능으로 간주되지만, 실제로는 클라이언트 애플리케이션이 도구 호출 로직을 제공해야 합니다. 모델은 단지 도구 호출 요청과 입력 인자(arguments)를 제공할 수 있을 뿐이며, 도구 호출을 실행하고 결과를 반환하는 역할은 애플리케이션이 수행합니다. 모델은 도구로 제공된 API에 접근할 수 없습니다. 이는 보안 측면에서 매우 중요한 고려 사항입니다.

 

Spring AI는 도구를 정의하고, 모델의 도구 호출 요청을 해결하고, 도구 호출을 실행하는 데 유용한 API들을 제공합니다. 다음 섹션에서는 Spring AI의 도구 호출 기능에 대한 개요를 제공합니다.

 

참고
어떤 AI 모델이 도구 호출을 지원하는지 확인하려면 [Chat Model Comparisons]를 참조하세요.

 

팁
더 이상 사용되지 않는 FunctionCallback에서 ToolCallback API로의 마이그레이드 가이드를 따르세요.

 

빠른 시작

Spring AI에서 tool calling을 사용하는 방법을 알아보겠습니다. 여기서는 두 가지 간단한 도구를 구현해 봅니다: 하나는 정보 검색용, 다른 하나는 작업 수행용입니다. 정보 검색 도구는 사용자의 시간대에 맞는 현재 날짜와 시간을 가져오는 기능이고, 작업 수행 도구는 지정된 시간에 알람을 설정하는 기능입니다.

 

정보 검색 도구 (Information Retrieval)

AI 모델은 실시간 정보에 접근할 수 없습니다. 따라서 “현재 날짜”나 “날씨 예보”처럼 실시간 정보에 대한 질문은 모델이 직접 답할 수 없습니다. 하지만 우리는 이런 정보를 검색해 주는 도구(tool)를 제공함으로써, 모델이 필요할 때 해당 도구를 호출하게 할 수 있습니다.

 

아래는 사용자의 시간대에 맞는 현재 날짜와 시간을 가져오는 도구를 DateTimeTools 클래스에 구현한 예시입니다. 이 도구는 입력 인자를 받지 않습니다. Spring Framework의 LocaleContextHolder를 사용하면 사용자의 시간대를 얻을 수 있습니다. 도구는 @Tool 어노테이션을 통해 정의되며, 모델이 이 도구를 이해하고 적절히 사용할 수 있도록 설명을 포함해야 합니다.

 

import java.time.LocalDateTime;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.i18n.LocaleContextHolder;

class DateTimeTools {

    @Tool(description = "Get the current date and time in the user's timezone")
    String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }

}

 

이제 위에서 만든 도구를 모델이 사용할 수 있도록 합니다. 이 예시에서는 ChatClient를 사용하여 모델과 상호작용합니다. tools() 메서드를 통해 DateTimeTools 인스턴스를 모델에게 제공합니다. 모델이 현재 날짜와 시간을 알아야 하는 경우, 도구 호출을 요청하게 되며, ChatClient는 내부적으로 해당 도구를 실행하고 결과를 모델에 반환합니다. 모델은 이 결과를 사용해 최종 응답을 생성합니다.

 

ChatModel chatModel = ...

String response = ChatClient.create(chatModel)
        .prompt("What day is tomorrow?")
        .tools(new DateTimeTools())
        .call()
        .content();

System.out.println(response);

 

출력 예시는 다음과 비슷할 수 있습니다:

Tomorrow is 2015-10-21.

 

이번에는 도구를 제공하지 않고 같은 질문을 해보면 다음과 같은 응답이 나옵니다:

I am an AI and do not have access to real-time information. Please provide the current date so I can accurately determine what day tomorrow will be.

 

즉, 도구 없이 모델은 현재 날짜와 시간을 알 수 없기 때문에 질문에 정확히 답변할 수 없습니다.

 

작업 수행 (Taking Actions)

AI 모델은 특정 목표를 달성하기 위한 계획을 생성할 수 있습니다. 예를 들어, 덴마크 여행을 예약하는 계획을 세울 수는 있지만, 그 계획을 실제로 실행하는 능력은 없습니다. 이때 도구(tool)가 사용됩니다. 도구는 모델이 생성한 계획을 실행하는 데 활용됩니다. 앞서 예제에서는 현재 날짜와 시간을 구하는 정보를 제공하는 도구를 사용했습니다. 이번 예제에서는 특정 시간에 알람을 설정하는 도구를 정의합니다. 목표는 “지금부터 10분 후에 알람을 설정하는 것”이며, 이를 위해 두 가지 도구(현재 시간 조회 + 알람 설정)를 모두 모델에 제공해야 합니다.

 

기존과 마찬가지로 DateTimeTools 클래스에 새로운 도구 메서드를 추가합니다. 이 도구는 ISO-8601 형식의 시간 문자열을 인자로 받아 콘솔에 알람 설정 메시지를 출력합니다. 역시 @Tool 어노테이션을 사용하여 도구로 정의하고, 모델이 이해할 수 있도록 상세 설명도 포함합니다.

 

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.i18n.LocaleContextHolder;

class DateTimeTools {

    @Tool(description = "Get the current date and time in the user's timezone")
    String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }

    @Tool(description = "Set a user alarm for the given time, provided in ISO-8601 format")
    void setAlarm(String time) {
        LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
        System.out.println("Alarm set for " + alarmTime);
    }

}

 

다음으로 두 개의 도구를 모델에서 사용할 수 있도록 합니다. 모델과 상호작용하기 위해 ChatClient를 사용합니다. tools() 메서드를 통해 DateTimeTools 인스턴스를 모델에 전달합니다. “10분 후에 알람 설정해 줘”라고 요청하면, 모델은 먼저 현재 날짜와 시간을 알아야 합니다. 그런 다음 현재 날짜와 시간을 사용해 알람 시간을 계산합니다. 마지막으로 알람 도구를 사용해 알람을 설정합니다. 내부적으로 ChatClient는 모델로부터의 모든 도구 호출 요청을 처리하고 도구 호출 실행 결과를 모델에 다시 전달하여, 모델이 최종 응답을 생성할 수 있도록 합니다.

 

ChatModel chatModel = ...

String response = ChatClient.create(chatModel)
        .prompt("Can you set an alarm 10 minutes from now?")
        .tools(new DateTimeTools())
        .call()
        .content();

System.out.println(response);

 

애플리케이션 로그를 확인하면, 알람이 정확한 시각에 설정되었는지 확인할 수 있습니다.

 

개요

Spring AI는 도구를 정의하고, 해석하고, 실행할 수 있는 유연한 추상화 집합을 통해 tool calling을 지원합니다. 이 섹션에서는 Spring AI에서 tool calling과 관련된 주요 개념과 구성 요소에 대한 개요를 제공합니다.

출처: Spring AI 공식 문서

1. 모델이 도구를 사용할 수 있도록 하려면, 해당 도구의 정의를 채팅 요청에 포함시켜야 합니다. 각 도구 정의는 이름, 설명, 입력 파라미터의 스키마로 구성됩니다.
2. 모델이 도구를 호출하기로 결정하면, 도구 이름과 정의된 스키마에 따른 입력 파라미터를 포함한 응답을 보냅니다.
3. 애플리케이션은 도구 이름을 사용해 어떤 도구인지 식별하고, 제공된 입력 파라미터로 도구를 실행하는 책임을 집니다.
4. 도구 호출의 결과는 애플리케이션에서 처리됩니다.
5. 애플리케이션은 도구 호출 결과를 모델에게 다시 전달합니다.
6. 모델은 도구 호출 결과를 추가적인 문맥으로 활용하여 최종 응답을 생성합니다.

도구(Tools)는 tool calling의 구성단위이며, ToolCallback 인터페이스로 모델링 됩니다. Spring AI는 메서드나 함수로부터 ToolCallback을 지정할 수 있는 기본 지원을 제공하지만, 더 다양한 사용 사례를 위해 직접 ToolCallback 구현체를 정의할 수도 있습니다. 

 

ChatModel 구현체는 도구 호출 요청을 해당 ToolCallback 구현체로 자동으로 전달하며, 도구 호출 결과를 다시 모델에 전달합니다. 최종 응답은 이 결과를 바탕으로 모델이 생성합니다. 이러한 과정은 도구 실행 생명주기를 관리하는 ToolCallingManager 인터페이스를 통해 이루어집니다. 

 

ChatClient와 ChatModel 모두 모델이 사용할 수 있도록 도구를 지정하기 위해 ToolCallback 객체 리스트와, 이를 실제로 실행할 ToolCallingManager를 전달받습니다. 

 

ToolCallback 객체를 직접 전달하는 것 외에도, 도구 이름 목록을 전달할 수도 있으며, 이 경우에는 ToolCallbackResolver 인터페이스를 통해 동적으로 해당 도구가 해석됩니다. 

 

다음 섹션에서는 이러한 개념들과 API에 대해 더 자세히 설명하며, 사용자 정의 및 확장 방법도 함께 다룰 예정입니다.

 

메서드를 도구로 사용하기

Spring AI는 메서드를 기반으로 도구(ToolCallback)를 지정하는 두 가지 방법을 기본적으로 지원합니다:

• 선언적으로 사용하는 방법: @Tool 어노테이션 사용
• 프로그래밍 방식으로 사용하는 방법: 저수준의 MethodToolCallback 구현 사용

선언적 지정: @Tool

메서드에 @Tool 어노테이션을 붙이면, 해당 메서드를 도구로 사용할 수 있습니다.

class DateTimeTools {

    @Tool(description = "Get the current date and time in the user's timezone")
    String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }

}

 

@Tool 어노테이션을 사용하면 도구에 대한 핵심 정보를 제공할 수 있습니다: 

• name: 도구의 이름입니다. 지정하지 않으면 메서드 이름이 사용됩니다. AI 모델은 이 이름을 기반으로 도구를 식별하여 호출하기 때문에, 같은 클래스 내에서 중복된 이름의 도구는 허용되지 않습니다. 하나의 채팅 요청에 대해 모델이 사용할 수 있는 도구 전체에서 이름은 고유해야 합니다. 
• description: 도구에 대한 설명으로, 모델이 도구를 언제, 어떻게 호출할지를 이해하는 데 사용됩니다. 지정하지 않으면 메서드 이름이 설명으로 사용됩니다. 하지만 모델이 도구의 목적과 사용 방법을 정확히 이해하려면 자세한 설명을 반드시 제공하는 것이 권장됩니다. 설명이 부족할 경우, 모델이 도구를 사용하지 않거나 잘못 사용하는 문제가 발생할 수 있습니다. 
• returnDirect: 도구의 실행 결과를 모델이 아닌 클라이언트에 직접 반환할지 여부입니다. 자세한 내용은 Return Direct 항목을 참조하세요. 
• resultConverter: 도구 실행 결과를 문자열(String)로 변환하여 AI 모델에 전달할 때 사용하는 ToolCallResultConverter 구현체입니다. 자세한 내용은 Result Conversion 항목을 참조하세요.

해당 메서드는 static이거나 인스턴스 메서드일 수 있으며, 접근 제한자도 public, protected, 패키지 프라이빗(package-private), private 모두 사용할 수 있습니다. 메서드를 포함하는 클래스는 최상위 클래스이거나 중첩 클래스(nested class) 일 수 있으며, 인스턴스를 생성하려는 위치에서 접근 가능하기만 하면 클래스의 가시성도 제한되지 않습니다.

 

참고
@Tool 어노테이션이 붙은 메서드를 AOT 컴파일하려면, 해당 메서드가 포함된 클래스가 Spring Bean(예: @Component)이어야 합니다. 그렇지 않으면 GraalVM 컴파일러에 필요한 구성을 직접 제공해야 하며, 예를 들어 클래스에 @RegisterReflection(memberCategories = MemberCategory.INVOKE_DECLARED_METHODS) 어노테이션을 붙이는 방식이 있습니다.

 

메서드는 인자를 0개 또는 여러 개 가질 수 있으며, 대부분의 타입(기본형, POJO, enum, 리스트, 배열, 맵 등)을 사용할 수 있습니다. 마찬가지로, 메서드의 반환 타입도 대부분의 타입을 사용할 수 있으며 void도 허용됩니다. 단, 반환값이 있는 경우에는 직렬화 가능한 타입이어야 하며, 이 값은 직렬화되어 모델에 전달됩니다.

 

참고
일부 타입은 지원되지 않습니다. 자세한 내용은 Method Tool Limitations를 참고하세요.

 

Spring AI는 @Tool이 붙은 메서드의 입력 파라미터에 대해 자동으로 JSON 스키마를 생성합니다. 이 스키마는 모델이 도구를 어떻게 호출할지 이해하고 도구 요청을 준비하는 데 사용됩니다. 입력 파라미터에 대해 더 많은 정보를 제공하려면 @ToolParam 어노테이션을 사용할 수 있으며, 설명 또는 필수 여부 등을 지정할 수 있습니다. 기본적으로 모든 입력 파라미터는 필수(required)로 간주됩니다.

 

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

class DateTimeTools {

    @Tool(description = "Set a user alarm for the given time")
    void setAlarm(@ToolParam(description = "Time in ISO-8601 format") String time) {
        LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
        System.out.println("Alarm set for " + alarmTime);
    }

}

 

@ToolParam 어노테이션은 도구의 파라미터에 대해 다음과 같은 핵심 정보를 제공할 수 있습니다: 

• description: 해당 파라미터에 대한 설명입니다. 모델이 이 파라미터를 어떻게 사용할지, 예를 들어 어떤 형식인지, 허용되는 값은 무엇인지 등을 이해하는 데 사용됩니다. 
• required: 이 파라미터가 필수인지 선택인지를 지정합니다. 기본값은 true이며, 즉 모든 파라미터는 기본적으로 필수로 간주됩니다. 

 

파라미터에 @Nullable 어노테이션이 지정되어 있다면, @ToolParam에서 명시적으로 required = true로 지정하지 않은 한, 선택적(optional)으로 처리됩니다. 

 

또한 @ToolParam 외에도 Swagger의 @Schema 또는 Jackson의 @JsonProperty 어노테이션도 함께 사용할 수 있습니다. 자세한 내용은 JSON Schema 항목을 참조하세요.

 

ChatClient에 도구 추가하기

MethodToolCallback 인스턴스를 ChatClient의 tools() 메서드에 전달하면 됩니다. 이 도구는 해당 채팅 요청에만 유효합니다.

ToolCallback toolCallback = ...
ChatClient.create(chatModel)
    .prompt("What day is tomorrow?")
    .tools(toolCallback)
    .call()
    .content();

 

내부적으로 ChatClient는 도구 클래스 인스턴스에 있는 @Tool 어노테이션이 붙은 각 메서드로부터 자동으로 ToolCallback을 생성하고, 이를 모델에 전달합니다. 직접 ToolCallback을 생성하고 싶다면, ToolCallbacks 유틸리티 클래스를 사용할 수 있습니다.

 

ToolCallback[] dateTimeTools = ToolCallbacks.from(new DateTimeTools());

 

ChatClient에 기본 도구(Default Tools) 추가하기

선언적 방식(declarative specification approach)을 사용할 때는, 도구 클래스 인스턴스를 defaultTools() 메서드에 전달하여 ChatClient.Builder에 기본 도구를 추가할 수 있습니다. 기본 도구와 런타임 도구가 모두 제공되는 경우, 런타임 도구가 기본 도구를 완전히 덮어씁니다.

 

주의
기본 도구는 동일한 ChatClient.Builder로 생성된 모든 ChatClient 인스턴스의 모든 요청에 공유됩니다. 여러 요청에서 공통으로 사용하는 도구에 유용하지만, 의도치 않게 도구가 노출될 수 있으므로 주의가 필요합니다.

 

ChatModel chatModel = ...
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultTools(new DateTimeTools())
    .build();

 

ChatModel에 도구 추가하기 

선언적 방식(declarative specification approach)을 사용할 때는, 도구 클래스 인스턴스를 ToolCallingChatOptions의 toolCallbacks() 메서드에 전달하여 ChatModel 호출 시 사용할 수 있습니다. 이렇게 추가된 도구는 해당 채팅 요청에만 유효합니다.

ChatModel chatModel = ...
ToolCallback[] dateTimeTools = ToolCallbacks.from(new DateTimeTools());
ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(dateTimeTools)
    .build();
Prompt prompt = new Prompt("What day is tomorrow?", chatOptions);
chatModel.call(prompt);

 

ChatModel에 기본 도구(Default Tools) 추가하기

선언적 방식(declarative specification approach)을 사용할 때는, ChatModel을 생성할 때 사용하는 ToolCallingChatOptions의 toolCallbacks() 메서드에 도구 클래스 인스턴스를 전달하여 기본 도구를 추가할 수 있습니다.

기본 도구와 런타임 도구가 모두 제공되는 경우, 런타임 도구가 기본 도구를 완전히 덮어씁니다.

 

주의
기본 도구는 해당 ChatModel 인스턴스에서 수행되는 모든 채팅 요청에 공유됩니다.
여러 요청에서 반복적으로 사용하는 도구에는 유용하지만, 원치 않는 요청에 노출될 수 있으므로 신중히 사용해야 합니다.

 

ToolCallback[] dateTimeTools = ToolCallbacks.from(new DateTimeTools());
ChatModel chatModel = OllamaChatModel.builder()
    .ollamaApi(OllamaApi.builder().build())
    .defaultOptions(ToolCallingChatOptions.builder()
            .toolCallbacks(dateTimeTools)
            .build())
    .build();

 

프로그래밍 방식 지정: MethodToolCallback

메서드를 도구로 사용하려면, MethodToolCallback을 프로그래밍 방식으로 생성하여 도구로 만들 수 있습니다.

class DateTimeTools {

    String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }

}

 

MethodToolCallback.Builder는 MethodToolCallback 인스턴스를 생성할 수 있도록 해주며, 도구에 대한 주요 정보를 설정할 수 있습니다: 

• toolDefinition: 도구의 이름, 설명, 입력 스키마를 정의하는 ToolDefinition 인스턴스입니다. ToolDefinition.Builder 클래스를 사용해 생성할 수 있으며, 필수 항목입니다. 
• toolMetadata: 결과를 클라이언트에 직접 반환할지 여부, 결과 변환 방식 등을 정의하는 ToolMetadata 인스턴스입니다. ToolMetadata.Builder 클래스로 생성할 수 있습니다. 
• toolMethod: 도구로 사용할 메서드를 나타내는 java.lang.reflect.Method 인스턴스입니다. 필수 항목입니다. 
• toolObject: 도구 메서드를 포함하고 있는 객체 인스턴스입니다. 메서드가 static일 경우에는 이 파라미터를 생략할 수 있습니다. 
• toolCallResultConverter: 도구 호출 결과를 문자열로 변환해 AI 모델에 전달하는 데 사용할 ToolCallResultConverter 인스턴스입니다. 지정하지 않으면 기본 변환기인 DefaultToolCallResultConverter가 사용됩니다.

ToolDefinition.Builder를 사용하면 도구 이름, 설명, 입력 스키마를 정의할 수 있습니다:

• name: 도구의 이름. 생략 시 메서드 이름이 사용됨. 하나의 채팅 요청 내에서 이름은 고유해야 합니다.
• description: 도구 설명. 생략 시 메서드 이름이 사용되지만, 모델의 정확한 이해를 위해 상세한 설명 제공이 권장됩니다.
• inputSchema: 도구의 입력 파라미터에 대한 JSON 스키마. 생략 시 메서드 시그니처를 기반으로 자동 생성됩니다. @ToolParam 어노테이션을 통해 파라미터에 대한 추가 정보 제공이 가능합니다. 기본적으로 모든 파라미터는 필수로 간주됩니다.

ToolMetadata.Builder를 사용하면 다음과 같은 도구 설정을 지정할 수 있습니다:

• returnDirect: 결과를 클라이언트에 직접 반환할지, 모델에 전달할지 여부를 의미합니다. 자세한 내용은 Return Direct를 참고하세요.

Method method = ReflectionUtils.findMethod(DateTimeTools.class, "getCurrentDateTime");
ToolCallback toolCallback = MethodToolCallback.builder()
    .toolDefinition(ToolDefinition.builder(method)
            .description("Get the current date and time in the user's timezone")
            .build())
    .toolMethod(method)
    .toolObject(new DateTimeTools())
    .build();

 

메서드는 static 또는 인스턴스 모두 가능하며, public, protected, package-private, private 등 가시성에 제한이 없습니다.

클래스는 최상위 또는 중첩 클래스 모두 가능하며, 인스턴스 생성 가능한 범위 내에서 접근 가능해야 합니다.

 

참고
Spring AI는 도구 메서드를 포함한 클래스가 Spring 빈(@Component 등) 일 경우, 해당 메서드에 대해 AOT 컴파일을 기본적으로 지원합니다. 그렇지 않은 경우에는 GraalVM 컴파일러에 필요한 설정을 직접 제공해야 합니다.
예를 들어, 클래스에 @RegisterReflection(memberCategories = MemberCategory.INVOKE_DECLARED_METHODS) 어노테이션을 추가해야 합니다.

 

메서드는 인자를 0개 이상 정의하실 수 있으며, 대부분의 타입(기본형, POJO, enum, 리스트, 배열, 맵 등)을 사용할 수 있습니다. 마찬가지로 반환 타입도 대부분의 타입을 사용할 수 있고, void 반환도 가능합니다. 단, 반환값이 있을 경우 해당 타입은 직렬화가 가능해야 하며, 결과는 직렬화되어 모델로 전달됩니다.

 

참고
일부 타입은 지원되지 않습니다. 자세한 내용은 Method Tool Limitations 항목을 참고해 주시기 바랍니다.

 

메서드가 static인 경우에는 toolObject() 메서드를 생략하셔도 됩니다. 해당 객체 인스턴스가 필요하지 않기 때문입니다.

 

class DateTimeTools {

    static String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }

}

Method method = ReflectionUtils.findMethod(DateTimeTools.class, "getCurrentDateTime");
ToolCallback toolCallback = MethodToolCallback.builder()
    .toolDefinition(ToolDefinition.builder(method)
            .description("Get the current date and time in the user's timezone")
            .build())
    .toolMethod(method)
    .build();

 

Spring AI는 메서드의 입력 파라미터에 대한 JSON 스키마를 자동으로 생성합니다. 이 스키마는 모델이 도구를 어떻게 호출할지 이해하고 도구 요청을 준비하는 데 사용됩니다. @ToolParam 어노테이션을 사용하면 파라미터에 대한 설명이나 필수 여부 등의 추가 정보를 제공할 수 있습니다. 기본적으로 모든 입력 파라미터는 필수(required)로 간주됩니다.

 

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.ai.tool.annotation.ToolParam;

class DateTimeTools {

    void setAlarm(@ToolParam(description = "Time in ISO-8601 format") String time) {
        LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
        System.out.println("Alarm set for " + alarmTime);
    }

}

 

@ToolParam 어노테이션은 도구 파라미터에 대한 핵심 정보를 제공할 수 있도록 해줍니다:

• description: 파라미터에 대한 설명입니다. 모델이 해당 파라미터를 어떻게 사용할지 더 잘 이해할 수 있도록 도와줍니다. 예를 들어, 파라미터의 형식이나 허용되는 값 등이 여기에 포함될 수 있습니다.
• required: 해당 파라미터가 필수인지 선택인지 여부를 나타냅니다. 기본값은 필수입니다.

파라미터에 @Nullable 어노테이션이 함께 지정되어 있다면, @ToolParam에서 명시적으로 required = true로 설정하지 않는 한 선택적으로 처리됩니다.

 

@ToolParam 외에도 Swagger의 @Schema나 Jackson의 @JsonProperty 어노테이션을 사용할 수 있습니다. 자세한 내용은 JSON 스키마 관련 문서를 참고하시기 바랍니다.

 

ChatClient 및 ChatModel에 도구 추가하기

프로그래밍 방식 지정 방법을 사용할 때는 MethodToolCallback 인스턴스를 ChatClient의 tools() 메서드에 전달할 수 있습니다. 이 도구는 추가된 해당 채팅 요청에만 사용 가능합니다.

ToolCallback toolCallback = ...
ChatClient.create(chatModel)
    .prompt("What day is tomorrow?")
    .tools(toolCallback)
    .call()
    .content();

 

ChatClient에 기본 도구 추가하기

프로그래밍 방식 지정 방법을 사용할 때는 MethodToolCallback 인스턴스를 defaultTools() 메서드에 전달하여 ChatClient.Builder에 기본 도구를 추가할 수 있습니다. 기본 도구와 런타임 도구가 모두 제공되는 경우, 런타임 도구가 기본 도구를 완전히 덮어씁니다.

 

주의
기본 도구는 동일한 ChatClient.Builder로 생성된 모든 ChatClient 인스턴스의 모든 채팅 요청에 공유됩니다. 여러 채팅 요청에서 공통으로 사용하는 도구에는 유용하지만, 주의하지 않으면 원하지 않는 요청에도 도구가 노출될 수 있는 위험이 있습니다.

 

ChatModel chatModel = ...
ToolCallback toolCallback = ...
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultTools(toolCallback)
    .build();

 

ChatModel에 도구 추가하기

프로그래밍 방식 지정 방법을 사용할 때는 MethodToolCallback 인스턴스를 ToolCallingChatOptions의 toolCallbacks() 메서드에 전달하여 ChatModel 호출 시 사용할 수 있습니다. 이 도구는 추가된 해당 채팅 요청에만 유효합니다.

ChatModel chatModel = ...
ToolCallback toolCallback = ...
ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(toolCallback)
    .build();
Prompt prompt = new Prompt("What day is tomorrow?", chatOptions);
chatModel.call(prompt);

 

ChatModel에 기본 도구 추가하기

프로그래밍 방식 지정 방법을 사용할 때는 ChatModel 생성 시 사용하는 ToolCallingChatOptions의 toolCallbacks() 메서드에 MethodToolCallback 인스턴스를 전달하여 기본 도구를 추가할 수 있습니다. 기본 도구와 런타임 도구가 모두 제공되는 경우, 런타임 도구가 기본 도구를 완전히 덮어씁니다.

주의
기본 도구는 해당 ChatModel 인스턴스에서 수행되는 모든 채팅 요청에 공유됩니다. 여러 요청에서 공통으로 사용하는 도구에는 유용하지만, 주의하지 않으면 원하지 않는 요청에도 도구가 노출될 수 있는 위험이 있습니다.

 

ToolCallback toolCallback = ...
ChatModel chatModel = OllamaChatModel.builder()
    .ollamaApi(OllamaApi.builder().build())
    .defaultOptions(ToolCallingChatOptions.builder()
            .toolCallbacks(toolCallback)
            .build())
    .build();

 

메서드 도구의 제한 사항

메서드를 도구로 사용할 때, 다음과 같은 타입들은 현재 파라미터나 반환 타입으로 지원되지 않습니다:

• Optional
• 비동기 타입 (예: CompletableFuture, Future)
• 리액티브 타입 (예: Flow, Mono, Flux)
• 함수형 타입 (예: Function, Supplier, Consumer)

함수형 타입은 함수 기반 도구 지정 방식(function-based tool specification approach)을 통해 지원됩니다. 자세한 내용은 Functions as Tools 항목을 참고하시기 바랍니다.

함수로서의 도구

Spring AI는 함수로 도구를 지정하는 기능을 기본적으로 지원하며, 이는 저수준 FunctionToolCallback 구현을 사용한 프로그래밍 방식이나 런타임에 @Bean으로 정의된 도구를 동적으로 해석하는 방식으로 사용할 수 있습니다.

프로그래밍 방식 지정: FunctionToolCallback

Function, Supplier, Consumer 또는 BiFunction과 같은 함수형 타입을 FunctionToolCallback을 프로그래밍 방식으로 구성하여 도구로 변환할 수 있습니다.

public class WeatherService implements Function<WeatherRequest, WeatherResponse> {
    public WeatherResponse apply(WeatherRequest request) {
        return new WeatherResponse(30.0, Unit.C);
    }
}

public enum Unit { C, F }
public record WeatherRequest(String location, Unit unit) {}
public record WeatherResponse(double temp, Unit unit) {}

 

FunctionToolCallback.Builder는 FunctionToolCallback 인스턴스를 생성하고 도구에 대한 주요 정보를 설정할 수 있도록 합니다.

• name: 도구의 이름. AI 모델은 도구를 호출할 때 이 이름을 사용하여 도구를 식별합니다. 따라서 동일한 컨텍스트 내에서 같은 이름을 가진 도구가 두 개 이상 존재해서는 안 됩니다. 모델이 처리하는 특정 채팅 요청 내에서 이 이름은 고유해야 하며, 필수 항목입니다.
• toolFunction: 도구 메서드를 나타내는 함수형 객체(Function, Supplier, Consumer, 또는 BiFunction). 필수 항목입니다.
• description: 도구에 대한 설명. 모델이 도구를 언제 어떻게 호출할지 이해하는 데 사용됩니다. 이 설명을 제공하지 않으면 메서드 이름이 설명으로 사용됩니다. 하지만 도구의 목적과 사용 방법을 모델이 올바르게 이해할 수 있도록 상세한 설명을 제공하는 것이 강력히 권장됩니다. 설명이 부실할 경우, 모델이 도구를 사용해야 할 상황에서도 사용하지 않거나 잘못 사용할 수 있습니다.
• inputType: 함수 입력값의 타입. 필수 항목입니다.
• inputSchema: 도구의 입력 매개변수에 대한 JSON 스키마. 제공하지 않으면 inputType을 기반으로 자동 생성됩니다. @ToolParam 애노테이션을 사용하여 매개변수에 대한 설명이나 필수 여부 등 추가 정보를 지정할 수 있습니다. 기본적으로 모든 매개변수는 필수로 간주됩니다. 자세한 내용은 JSON Schema 섹션을 참조하면 됩니다.
• toolMetadata: 결과를 클라이언트에 직접 반환할지 여부, 결과 변환기 등의 추가 설정을 정의하는 ToolMetadata 인스턴스입니다. ToolMetadata.Builder 클래스를 사용하여 생성할 수 있습니다.
• toolCallResultConverter: 도구 호출 결과를 문자열로 변환하여 AI 모델에 반환할 때 사용할 ToolCallResultConverter 인스턴스. 제공하지 않으면 기본 변환기(DefaultToolCallResultConverter)가 사용됩니다.

ToolMetadata.Builder는 ToolMetadata 인스턴스를 생성하고 도구에 대한 추가 설정을 정의할 수 있게 합니다.

• returnDirect: 도구 실행 결과를 모델이 아니라 클라이언트(호출자)에게 직접 반환할지 여부를 설정합니다. 예를 들어, 검색 도구에서 결과를 바로 사용자에게 반환하고 싶은 경우 returnDirect(true)로 설정할 수 있습니다.

ToolCallback toolCallback = FunctionToolCallback
    .builder("currentWeather", new WeatherService())
    .description("Get the weather in location")
    .inputType(WeatherRequest.class)
    .build();

 

함수의 입력과 출력은 Void 또는 POJO일 수 있습니다. 입력 및 출력으로 사용되는 POJO는 직렬화 가능해야 하며, 이는 결과가 직렬화되어 모델로 반환되기 때문입니다. 함수 자체와 입력 및 출력 타입 모두 public이어야 합니다.

참고
일부 타입은 지원되지 않습니다. 자세한 내용은 Function Tool Limitations 항목을 참조하세요.

 

ChatClient에 도구 추가하기

프로그래밍 방식 지정 방법을 사용할 경우, FunctionToolCallback 인스턴스를 ChatClient의 tools() 메서드에 전달하실 수 있습니다. 이렇게 추가된 도구는 해당 채팅 요청에만 사용 가능합니다.

ToolCallback toolCallback = ...
ChatClient.create(chatModel)
    .prompt("What's the weather like in Copenhagen?")
    .tools(toolCallback)
    .call()
    .content();

 

ChatClient에 기본 도구 추가하기

프로그래밍 방식 지정 방법을 사용할 경우, FunctionToolCallback 인스턴스를 ChatClient.Builder의 defaultTools() 메서드에 전달하여 기본 도구로 추가하실 수 있습니다. 기본 도구와 런타임 도구가 모두 제공되는 경우, 런타임 도구가 기본 도구를 완전히 덮어씁니다.

주의
본 도구는 동일한 ChatClient.Builder로 생성된 모든 ChatClient 인스턴스에서 수행되는 모든 채팅 요청에 공유됩니다. 이러한 도구는 여러 채팅 요청에서 공통적으로 사용되는 도구를 정의할 때 유용하지만, 주의해서 사용하지 않으면 원치 않는 상황에서 도구가 노출될 위험이 있으므로 주의하셔야 합니다.

ChatModel chatModel = ...
ToolCallback toolCallback = ...
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultTools(toolCallback)
    .build();

 

ChatModel에 도구 추가하기

프로그래밍 방식 지정 방법을 사용할 경우, FunctionToolCallback 인스턴스를 ToolCallingChatOptions의 toolCallbacks() 메서드에 전달하실 수 있습니다. 이렇게 추가된 도구는 해당 채팅 요청에만 사용됩니다.

ChatModel chatModel = ...
ToolCallback toolCallback = ...
ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(toolCallback)
    .build():
Prompt prompt = new Prompt("What's the weather like in Copenhagen?", chatOptions);
chatModel.call(prompt);

 

ChatModel에 기본 도구 추가하기

프로그래밍 방식 지정 방법을 사용할 경우, ChatModel을 생성할 때 사용되는 ToolCallingChatOptions 인스턴스의 toolCallbacks() 메서드에 FunctionToolCallback 인스턴스를 전달하여 기본 도구로 추가하실 수 있습니다. 기본 도구와 런타임 도구가 모두 제공되는 경우, 런타임 도구가 기본 도구를 완전히 덮어씁니다.

주의
기본 도구는 해당 ChatModel 인스턴스에서 수행되는 모든 채팅 요청에 걸쳐 공유됩니다. 여러 요청에서 공통적으로 사용되는 도구를 정의할 때 유용하지만, 주의하지 않으면 원치 않는 상황에서도 도구가 노출될 수 있으므로 신중하게 사용하셔야 합니다.

ToolCallback toolCallback = ...
ChatModel chatModel = OllamaChatModel.builder()
    .ollamaApi(OllamaApi.builder().build())
    .defaultOptions(ToolCallingChatOptions.builder()
            .toolCallbacks(toolCallback)
            .build())
    .build();

동적 지정 방식: @Bean

도구를 프로그래밍 방식으로 지정하는 대신, Spring 빈으로 정의하고 ToolCallbackResolver 인터페이스(구현체: SpringBeanToolCallbackResolver)를 통해 Spring AI가 런타임에 이를 동적으로 해석하도록 하실 수 있습니다. 이 방식은 Function, Supplier, Consumer, BiFunction 타입의 빈을 도구로 사용할 수 있는 유연함을 제공합니다. 빈 이름은 도구 이름으로 사용되며, Spring Framework의 @Description 애노테이션을 통해 도구에 대한 설명을 제공하실 수 있습니다. 이 설명은 모델이 해당 도구를 언제, 어떻게 호출해야 하는지를 이해하는 데 사용됩니다. 설명을 제공하지 않으면 메서드 이름이 도구 설명으로 사용되지만, 모델이 도구의 목적과 사용 방법을 명확히 이해할 수 있도록 자세한 설명을 제공하는 것이 강력히 권장됩니다. 설명이 부실할 경우, 모델이 도구를 적절히 사용하지 않거나 오용할 수 있습니다.

@Configuration(proxyBeanMethods = false)
class WeatherTools {

    WeatherService weatherService = new WeatherService();

	@Bean
	@Description("Get the weather in location")
	Function<WeatherRequest, WeatherResponse> currentWeather() {
		return weatherService;
	}

}

참고
일부 타입은 지원되지 않습니다. 자세한 내용은 Function Tool Limitations 항목을 참조하세요.

 

도구의 입력 매개변수에 대한 JSON 스키마는 자동으로 생성됩니다. 입력 매개변수에 대한 추가 정보를 제공하려면 @ToolParam 애노테이션을 사용하실 수 있으며, 이를 통해 설명을 추가하거나 해당 매개변수가 필수인지 선택사항인지 지정하실 수 있습니다. 기본적으로 모든 입력 매개변수는 필수로 간주됩니다. 자세한 내용은 JSON Schema 항목을 참조하시기 바랍니다.

record WeatherRequest(@ToolParam(description = "The name of a city or a country") String location, Unit unit) {}

 

이 도구 지정 방식은 도구가 런타임에 해석되기 때문에 타입 안정성이 보장되지 않는다는 단점이 있습니다. 이를 완화하기 위해, @Bean 애노테이션을 사용할 때 도구 이름을 명시적으로 지정하고 해당 값을 상수로 저장함으로써, 채팅 요청 시 하드코딩된 문자열 대신 해당 상수를 사용할 수 있습니다.

@Configuration(proxyBeanMethods = false)
class WeatherTools {

    public static final String CURRENT_WEATHER_TOOL = "currentWeather";

	@Bean(CURRENT_WEATHER_TOOL)
	@Description("Get the weather in location")
	Function<WeatherRequest, WeatherResponse> currentWeather() {
		...
	}

}

 

ChatClient에 도구 추가하기

동적 지정 방식을 사용할 경우, 도구 이름(즉, 함수형 빈의 이름)을 ChatClient의 tools() 메서드에 전달하실 수 있습니다. 이렇게 추가된 도구는 해당 채팅 요청에만 사용됩니다.

ChatClient.create(chatModel)
    .prompt("What's the weather like in Copenhagen?")
    .tools("currentWeather")
    .call()
    .content();

 

ChatClient에 기본 도구 추가하기

동적 지정 방식을 사용할 경우, 도구 이름을 ChatClient.Builder의 defaultTools() 메서드에 전달하여 기본 도구로 추가하실 수 있습니다. 기본 도구와 런타임 도구가 모두 제공되는 경우, 런타임 도구가 기본 도구를 완전히 덮어씁니다.

주의
기본 도구는 동일한 ChatClient.Builder로 생성된 모든 ChatClient 인스턴스에서 수행되는 모든 채팅 요청에 걸쳐 공유됩니다. 이러한 도구는 여러 채팅 요청에서 공통적으로 사용되는 도구를 정의할 때 유용하지만, 주의하지 않으면 원치 않는 상황에서도 도구가 노출될 수 있으므로 신중하게 사용하셔야 합니다.

ChatModel chatModel = ...
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultTools("currentWeather")
    .build();

 

ChatModel에 도구 추가하기

동적 지정 방식을 사용할 경우, ChatModel을 호출할 때 사용하는 ToolCallingChatOptions의 toolNames() 메서드에 도구 이름을 전달하실 수 있습니다. 이렇게 추가된 도구는 해당 채팅 요청에만 사용됩니다.

ChatModel chatModel = ...
ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolNames("currentWeather")
    .build():
Prompt prompt = new Prompt("What's the weather like in Copenhagen?", chatOptions);
chatModel.call(prompt);

 

ChatModel에 기본 도구 추가하기

동적 지정 방식을 사용할 경우, ChatModel을 생성할 때 사용되는 ToolCallingChatOptions 인스턴스의 toolNames() 메서드에 도구 이름을 전달하여 기본 도구로 추가하실 수 있습니다. 기본 도구와 런타임 도구가 모두 제공되는 경우, 런타임 도구가 기본 도구를 완전히 덮어씁니다.

주의
기본 도구는 해당 ChatModel 인스턴스에서 수행되는 모든 채팅 요청에 걸쳐 공유됩니다. 이러한 도구는 여러 요청에서 공통적으로 사용되는 도구를 정의할 때 유용하지만, 주의해서 사용하지 않으면 의도하지 않은 상황에서도 도구가 노출될 수 있으므로 신중하게 사용하셔야 합니다.

ChatModel chatModel = OllamaChatModel.builder()
    .ollamaApi(OllamaApi.builder().build())
    .defaultOptions(ToolCallingChatOptions.builder()
            .toolNames("currentWeather")
            .build())
    .build();

함수형 도구(Function Tool) 제한 사항

도구로 사용되는 함수의 입력 또는 출력 타입으로 현재 지원되지 않는 타입은 다음과 같습니다:

• 기본형(Primitive types)
• Optional
• 컬렉션 타입 (List, Map, Array, Set 등)
• 비동기 타입 (CompletableFuture, Future 등)
• 리액티브 타입 (Flow, Mono, Flux 등)

기본형과 컬렉션 타입은 메서드 기반 도구 지정 방식(Method-based tool specification approach)을 통해 지원됩니다. 자세한 내용은 Methods as Tools 항목을 참고하시기 바랍니다.

 

도구 명세

Spring AI에서는 도구가 ToolCallback 인터페이스를 통해 모델링 됩니다. 앞서 설명한 섹션들에서는 Spring AI에서 제공하는 기본 기능을 사용해 메서드나 함수로 도구를 정의하는 방법을 살펴보았습니다 (자세한 내용은 Methods as Tools 및 Functions as Tools 참고). 이 섹션에서는 도구 명세에 대해 더 깊이 다루고, 더 다양한 사용 사례를 지원하기 위한 사용자 정의 및 확장 방법을 설명합니다.

 

도구 콜백

ToolCallback 인터페이스는 AI 모델이 호출할 수 있는 도구를 정의하는 방법을 제공합니다. 여기에는 도구의 정의와 실행 로직이 모두 포함됩니다. 도구를 처음부터 직접 정의하고자 할 때 구현해야 하는 핵심 인터페이스입니다. 예를 들어, MCP 클라이언트(Model Context Protocol 사용)나 ChatClient를 기반으로 한 모듈형 에이전트 애플리케이션을 구축할 때 ToolCallback을 구현하여 도구를 정의할 수 있습니다.

 

이 인터페이스는 다음과 같은 메서드들을 제공합니다:

public interface ToolCallback {

    /**
     * AI 모델이 도구를 언제, 어떻게 호출할지를 판단하는 데 사용하는 도구 정의를 반환합니다.
     */
    ToolDefinition getToolDefinition();

    /**
     * 도구를 처리하는 방법에 대한 추가 정보를 제공하는 메타데이터를 반환합니다.
     */
    ToolMetadata getToolMetadata();

    /**
     * 주어진 입력을 사용해 도구를 실행하고, AI 모델에 전달할 결과를 반환합니다.
     */
    String call(String toolInput);

    /**
     * 주어진 입력과 컨텍스트를 사용해 도구를 실행하고, AI 모델에 전달할 결과를 반환합니다.
     */
    String call(String toolInput, ToolContext toolContext);
}

 

Spring AI는 도구 메서드에 대한 MethodToolCallback과 도구 함수에 대한 FunctionToolCallback을 기본적으로 구현하여 제공합니다.

도구 정의

ToolDefinition 인터페이스는 도구의 이름, 설명, 입력 스키마 등 AI 모델이 해당 도구의 사용 가능 여부를 인식하는 데 필요한 정보를 제공합니다. 각 ToolCallback 구현체는 도구를 정의하기 위해 반드시 ToolDefinition 인스턴스를 제공해야 합니다.

 

이 인터페이스는 다음과 같은 메서드를 제공합니다:

public interface ToolDefinition {

    /**
     * 도구의 이름. 모델에 제공되는 도구 집합 내에서 고유해야 합니다.
     */
    String name();

    /**
     * 도구의 설명. AI 모델이 도구의 기능을 파악하는 데 사용됩니다.
     */
    String description();

    /**
     * 도구 호출에 사용되는 매개변수들의 스키마.
     */
    String inputSchema();
}

참고
입력 스키마에 대한 자세한 내용은 JSON Schema 항목을 참고하십시오.

 

ToolDefinition.Builder를 사용하면 기본 구현체인 DefaultToolDefinition을 이용하여 ToolDefinition 인스턴스를 생성하실 수 있습니다.

ToolDefinition toolDefinition = ToolDefinition.builder()
    .name("currentWeather")
    .description("Get the weather in location")
    .inputSchema("""
        {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string"
                },
                "unit": {
                    "type": "string",
                    "enum": ["C", "F"]
                }
            },
            "required": ["location", "unit"]
        }
    """)
    .build();

 

메서드 기반 도구 정의

메서드로 도구를 구성할 때는 ToolDefinition이 자동으로 생성됩니다. 직접 ToolDefinition을 생성하고 싶다면, 편리한 빌더(ToolDefinition.Builder)를 사용할 수 있습니다.

Method method = ReflectionUtils.findMethod(DateTimeTools.class, "getCurrentDateTime");
ToolDefinition toolDefinition = ToolDefinition.from(method);

 

메서드로부터 생성된 ToolDefinition에는 메서드 이름이 도구 이름과 설명으로 사용되며, 메서드의 입력 파라미터에 대한 JSON 스키마가 포함됩니다.

메서드에 @Tool 어노테이션이 지정되어 있고 이름이나 설명이 설정되어 있는 경우, 해당 어노테이션의 값을 우선적으로 사용합니다.

 

참고
자세한 내용은 Methods as Tools 항목을 참고하시기 바랍니다.

 

일부 또는 모든 속성을 명시적으로 지정하고자 하는 경우, ToolDefinition.Builder를 사용하여 사용자 정의 ToolDefinition 인스턴스를 생성할 수 있습니다.

Method method = ReflectionUtils.findMethod(DateTimeTools.class, "getCurrentDateTime");
ToolDefinition toolDefinition = ToolDefinition.builder(method)
    .name("currentDateTime")
    .description("Get the current date and time in the user's timezone")
    .inputSchema(JsonSchemaGenerator.generateForMethodInput(method))
    .build();

 

함수 도구 정의

함수로 도구를 구성할 때는 ToolDefinition이 자동으로 생성됩니다.

FunctionToolCallback.Builder를 사용하여 FunctionToolCallback 인스턴스를 생성할 때, 도구 이름, 설명, 입력 스키마를 직접 지정할 수 있으며, 이 값들을 기반으로 ToolDefinition이 생성됩니다.

자세한 내용은 Functions as Tools 항목을 참고하시기 바랍니다.

 

JSON 스키마

AI 모델에 도구를 제공할 때, 해당 도구를 호출하기 위한 입력 타입의 스키마를 모델이 알아야 합니다. 이 스키마는 도구를 어떻게 호출할지 이해하고 요청을 준비하는 데 사용됩니다. Spring AI는 JsonSchemaGenerator 클래스를 통해 도구의 입력 타입에 대한 JSON 스키마를 자동으로 생성하는 기능을 기본적으로 제공합니다. 생성된 스키마는 ToolDefinition의 일부로 포함됩니다.

참고
ToolDefinition 및 입력 스키마를 전달하는 방법에 대한 자세한 내용은 Tool Definition 항목을 참고하시기 바랍니다.

 

JsonSchemaGenerator 클래스는 내부적으로 메서드나 함수의 입력 매개변수에 대한 JSON 스키마를 생성하는 데 사용되며, 이는 “Methods as Tools” 및 “Functions as Tools”에서 설명된 전략들을 따릅니다. JSON 스키마 생성 로직은 메서드 및 함수의 입력 매개변수에 다양한 애노테이션을 사용하여 생성 결과를 사용자 정의할 수 있도록 지원합니다.

 

이 섹션에서는 도구의 입력 매개변수에 대한 JSON 스키마를 생성할 때 사용자 정의할 수 있는 두 가지 주요 옵션인 설명(description)과 필수 여부(required status)에 대해 설명합니다.

 

설명

도구 자체에 대한 설명 외에도, 도구의 입력 매개변수에 대해서도 설명을 제공하실 수 있습니다. 이 설명은 매개변수가 어떤 형식이어야 하는지, 허용되는 값은 무엇인지 등 핵심 정보를 제공하는 데 사용됩니다. 이는 모델이 입력 스키마를 이해하고 올바르게 사용하는 데 매우 유용합니다. Spring AI는 다음 애노테이션 중 하나를 사용하여 입력 매개변수에 대한 설명을 생성하는 기능을 기본적으로 지원합니다:

• @ToolParam(description = "...") — Spring AI 제공
• @JsonClassDescription(description = "...") — Jackson 제공
• @JsonPropertyDescription(description = "...") — Jackson 제공
• @Schema(description = "...") — Swagger(OpenAPI) 제공

이 방식은 메서드와 함수 모두에 적용되며, 중첩된 타입(nested types)에 대해서도 재귀적으로 사용할 수 있습니다.

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.context.i18n.LocaleContextHolder;

class DateTimeTools {

    @Tool(description = "Set a user alarm for the given time")
    void setAlarm(@ToolParam(description = "Time in ISO-8601 format") String time) {
        LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
        System.out.println("Alarm set for " + alarmTime);
    }

}

 

필수 여부

기본적으로 모든 입력 매개변수는 필수(required)로 간주되며, 이로 인해 AI 모델은 도구를 호출할 때 해당 매개변수에 값을 반드시 제공해야 합니다. 그러나 다음의 애노테이션 중 하나를 사용하면 입력 매개변수를 선택(optional)으로 지정하실 수 있습니다. 적용 우선순위는 다음과 같습니다:

• @ToolParam(required = false) — Spring AI에서 제공
• @JsonProperty(required = false) — Jackson에서 제공
• @Schema(required = false) — Swagger에서 제공
• @Nullable — Spring Framework에서 제공

이 방식은 메서드와 함수 모두에 적용되며, 중첩 타입(nested types)에도 재귀적으로 사용할 수 있습니다.

class CustomerTools {

    @Tool(description = "Update customer information")
    void updateCustomerInfo(Long id, String name, @ToolParam(required = false) String email) {
        System.out.println("Updated info for customer with id: " + id);
    }

}

주의
입력 매개변수에 대해 올바른 필수 여부(required status)를 정의하는 것은 환각(hallucination) 현상을 방지하고, 모델이 도구를 호출할 때 정확한 입력값을 제공하도록 하기 위해 매우 중요합니다.
앞선 예제에서 email 매개변수는 선택 항목이므로, 모델은 해당 값 없이도 도구를 호출할 수 있습니다. 반면, 이 매개변수가 필수였다면 모델은 반드시 값을 제공해야 하며, 값이 존재하지 않는 경우에는 임의의 값을 만들어내어 잘못된 호출로 이어질 수 있습니다.

 

결과 변환 (Result Conversion)

도구 호출의 결과는 ToolCallResultConverter를 사용하여 문자열로 직렬화된 후 AI 모델에 전달됩니다. ToolCallResultConverter 인터페이스는 도구 호출 결과를 문자열(String) 객체로 변환하는 방법을 제공합니다.

 

이 인터페이스는 다음과 같은 메서드를 포함합니다:

@FunctionalInterface
public interface ToolCallResultConverter {

    /**
     * 도구에서 반환된 객체를 주어진 클래스 타입에 맞는 문자열로 변환합니다.
     */
    String convert(@Nullable Object result, @Nullable Type returnType);

}

 

결과는 반드시 직렬화 가능한 타입이어야 합니다. 기본적으로 결과는 Jackson을 사용하여 JSON 형식으로 직렬화되며, 이는 DefaultToolCallResultConverter가 처리합니다. 하지만 필요에 따라 사용자 정의 ToolCallResultConverter 구현체를 제공하여 직렬화 방식을 직접 커스터마이징하실 수 있습니다.

 

Spring AI는 메서드 기반 도구와 함수 기반 도구 모두에서 ToolCallResultConverter를 사용합니다.

 

메서드 기반 도구 호출 결과 변환

선언형 방식으로 메서드를 도구로 구성할 때, @Tool 애노테이션의 resultConverter() 속성을 설정하여 해당 도구에 사용할 사용자 정의 ToolCallResultConverter를 지정하실 수 있습니다.

class CustomerTools {

    @Tool(description = "Retrieve customer information", resultConverter = CustomToolCallResultConverter.class)
    Customer getCustomerInfo(Long id) {
        return customerRepository.findById(id);
    }

}

 

프로그래밍 방식으로 도구를 구성하는 경우, MethodToolCallback.Builder의 resultConverter() 속성을 설정하여 해당 도구에 사용할 사용자 정의 ToolCallResultConverter를 지정하실 수 있습니다. 

 

자세한 내용은 Methods as Tools 항목을 참고하시기 바랍니다.

 

함수 기반 도구 호출 결과 변환

프로그래밍 방식으로 함수를 도구로 구성할 때는 FunctionToolCallback.Builder의 resultConverter() 속성을 설정하여 해당 도구에 사용할 사용자 정의 ToolCallResultConverter를 지정하실 수 있습니다.

 

자세한 내용은 Functions as Tools 항목을 참고하시기 바랍니다.

 

도구 컨텍스트 (Tool Context)

Spring AI는 ToolContext API를 통해 도구에 추가적인 컨텍스트 정보를 전달하는 기능을 지원합니다. 이 기능을 활용하면, AI 모델이 전달하는 도구 인자 외에도 사용자 정의 데이터를 함께 제공하여 도구 실행 시 사용할 수 있습니다.

출처: Spring AI 공식 문서

 

class CustomerTools {

    @Tool(description = "Retrieve customer information")
    Customer getCustomerInfo(Long id, ToolContext toolContext) {
        return customerRepository.findById(id, toolContext.get("tenantId"));
    }

}

 

ToolContext는 사용자가 ChatClient를 호출할 때 제공한 데이터로 채워집니다.

ChatModel chatModel = ...

String response = ChatClient.create(chatModel)
        .prompt("Tell me more about the customer with ID 42")
        .tools(new CustomerTools())
        .toolContext(Map.of("tenantId", "acme"))
        .call()
        .content();

System.out.println(response);

참고
ToolContext에 제공된 데이터는 AI 모델에 전달되지 않습니다.

 

마찬가지로, ChatModel을 직접 호출할 때에도 도구 컨텍스트 데이터를 정의하실 수 있습니다.

ChatModel chatModel = ...
ToolCallback[] customerTools = ToolCallbacks.from(new CustomerTools());
ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(customerTools)
    .toolContext(Map.of("tenantId", "acme"))
    .build();
Prompt prompt = new Prompt("Tell me more about the customer with ID 42", chatOptions);
chatModel.call(prompt);

 

toolContext 옵션이 기본 옵션과 런타임 옵션 모두에 설정된 경우, 최종적으로 생성되는 ToolContext는 두 옵션을 병합한 값이 되며, 이때 런타임 옵션이 기본 옵션보다 우선합니다.

 

직접 반환(Return Direct)

기본적으로 도구 호출의 결과는 모델에 응답으로 전달되며, 이후 모델은 그 결과를 이용해 대화를 이어갑니다.

 

그러나 경우에 따라, 결과를 모델로 보내는 대신 호출자에게 직접 반환하는 것이 더 적절할 수 있습니다. 예를 들어, RAG 도구에 의존하는 에이전트를 구성하는 경우에는 모델이 후처리를 하지 않고 결과를 그대로 호출자에게 전달하는 것이 바람직할 수 있습니다. 또는 일부 도구는 에이전트의 추론 루프를 종료하는 역할을 하도록 설계될 수도 있습니다.

 

각 ToolCallback 구현체는 해당 도구 호출 결과를 모델로 전달할지, 또는 호출자에게 직접 반환할지를 정의할 수 있습니다. 기본 동작은 모델로의 전달이지만, 도구 단위로 이 동작을 변경할 수 있습니다.

 

도구 실행 생명주기를 관리하는 ToolCallingManager는 도구에 설정된 returnDirect 속성을 처리합니다. 이 속성이 true로 설정되어 있으면, 도구 호출 결과는 모델을 거치지 않고 호출자에게 직접 반환됩니다. 그렇지 않은 경우에는 결과가 모델로 전달됩니다.

참고
여러 개의 도구 호출이 한 번에 요청되는 경우, 모든 도구의 returnDirect 속성이 true로 설정되어 있어야만 결과가 호출자에게 직접 반환됩니다. 그렇지 않으면, 모든 결과는 모델로 전달됩니다.

출처: Spring AI 공식 문서

1. 도구를 모델이 사용할 수 있도록 하려면, 해당 도구의 정의를 채팅 요청에 포함시켜야 합니다. 도구 실행 결과를 모델이 아닌 호출자에게 직접 반환하고자 할 경우에는 returnDirect 속성을 true로 설정합니다.
2. 모델이 도구 호출을 결정하면, 도구 이름과 정의된 스키마에 따라 구성된 입력 매개변수를 포함한 응답을 전송합니다.
3. 애플리케이션은 도구 이름을 사용하여 도구를 식별하고, 제공된 입력값을 기반으로 해당 도구를 실행합니다.
4. 도구 호출 결과는 애플리케이션에 의해 처리됩니다.
5. 그리고 애플리케이션은 그 결과를 모델로 보내지 않고, 호출자에게 직접 반환합니다.

메서드 직접 반환(Method Return Direct)

선언형 방식으로 메서드를 도구로 구성할 때, @Tool 애노테이션의 returnDirect 속성을 true로 설정하면 해당 도구의 실행 결과를 호출자에게 직접 반환하도록 지정할 수 있습니다.

class CustomerTools {

    @Tool(description = "Retrieve customer information", returnDirect = true)
    Customer getCustomerInfo(Long id) {
        return customerRepository.findById(id);
    }

}

 

프로그래밍 방식을 사용할 경우, ToolMetadata 인터페이스를 통해 returnDirect 속성을 설정한 뒤, 이를 MethodToolCallback.Builder에 전달하여 도구 호출 결과를 호출자에게 직접 반환하도록 지정하실 수 있습니다.

ToolMetadata toolMetadata = ToolMetadata.builder()
    .returnDirect(true)
    .build();

 

자세한 내용은 Methods as Tools 항목을 참고하시기 바랍니다.

 

함수 직접 반환(Function Return Direct)

프로그래밍 방식으로 함수를 도구로 구성할 때, ToolMetadata 인터페이스를 통해 returnDirect 속성을 설정하고 이를 FunctionToolCallback.Builder에 전달하여 도구 결과를 호출자에게 직접 반환하도록 지정하실 수 있습니다.

ToolMetadata toolMetadata = ToolMetadata.builder()
    .returnDirect(true)
    .build();

 

자세한 내용은 Methods as Tools 항목을 참고하시기 바랍니다.

 

도구 실행

도구 실행 (Tool Execution)은 모델이 요청한 도구에 입력 인자를 전달하여 호출하고, 그 결과를 반환하는 과정입니다.

이 실행 과정은 ToolCallingManager 인터페이스가 담당하며, 도구 실행 생명주기를 관리합니다.

public interface ToolCallingManager {

    /**
     * 모델의 도구 호출 옵션에서 도구 정의 목록을 해석합니다.
     */
    List<ToolDefinition> resolveToolDefinitions(ToolCallingChatOptions chatOptions);

    /**
     * 모델이 요청한 도구 호출을 실행합니다.
     */
    ToolExecutionResult executeToolCalls(Prompt prompt, ChatResponse chatResponse);

}

 

Spring AI의 Spring Boot Starter를 사용하는 경우, ToolCallingManager 인터페이스의 기본 구현체는 DefaultToolCallingManager이며 자동 구성됩니다. 도구 실행 동작을 사용자 정의하고 싶다면, 사용자 정의 ToolCallingManager 빈을 등록하여 동작을 변경할 수 있습니다.

@Bean
ToolCallingManager toolCallingManager() {
    return ToolCallingManager.builder().build();
}

 

기본적으로 Spring AI는 각 ChatModel 구현체 내부에서 도구 실행 생명주기를 자동으로 처리합니다. 그러나 원할 경우 이 동작을 비활성화하고 직접 도구 실행을 제어할 수도 있습니다.

이 섹션에서는 이러한 두 가지 방식(자동 처리 vs. 수동 제어)에 대해 설명합니다.

 

프레임워크 제어 도구 실행 (Framework-Controlled Tool Execution)

기본 동작을 사용하는 경우, Spring AI는 모델로부터 발생한 도구 호출 요청을 자동으로 가로채고, 해당 도구를 실행한 후 결과를 모델에 반환합니다.

이 모든 과정은 각 ChatModel 구현체 내부에서 ToolCallingManager를 통해 자동으로 처리되며, 사용자는 별도로 개입할 필요가 없습니다.

출처: Spring AI 공식 문서

 

1. 도구를 모델에서 사용할 수 있도록 하려면, 해당 도구의 정의를 채팅 요청(Prompt)에 포함시키고 ChatModel API를 호출하여 AI 모델로 요청을 전송합니다.
2. 모델이 도구를 호출하기로 결정하면, 정의된 스키마에 따라 도구 이름과 입력 파라미터를 포함한 응답(ChatResponse)을 전송합니다.
3. ChatModel은 이 도구 호출 요청을 ToolCallingManager API로 전달합니다.
4. ToolCallingManager는 어떤 도구를 호출할지 식별하고, 주어진 입력 파라미터로 도구를 실행합니다.
5. 도구 실행 결과는 ToolCallingManager로 반환됩니다.
6. ToolCallingManager는 도구 실행 결과를 ChatModel에 다시 전달합니다.
7. ChatModel은 도구 실행 결과를 ToolResponseMessage로 AI 모델에 전달합니다.
8. AI 모델은 도구 호출 결과를 추가 문맥으로 사용하여 최종 응답을 생성하고, 이 응답은 ChatClient를 통해 호출자에게 ChatResponse로 전달됩니다.

주의
현재 도구 실행과 관련하여 모델과 주고받는 내부 메시지는 사용자에게 노출되지 않습니다. 이러한 메시지에 접근할 필요가 있다면, 사용자 제어 도구 실행(user-controlled tool execution) 방식을 사용하셔야 합니다.

 

도구 호출이 실행 대상인지 여부를 판단하는 로직은 ToolExecutionEligibilityPredicate 인터페이스에 의해 처리됩니다.

기본적으로는 ToolCallingChatOptions의 internalToolExecutionEnabled 속성이 true(기본값)로 설정되어 있고, ChatResponse에 도구 호출이 포함되어 있는지를 확인하여 실행 여부를 결정합니다.

public class DefaultToolExecutionEligibilityPredicate implements ToolExecutionEligibilityPredicate {

	@Override
	public boolean test(ChatOptions promptOptions, ChatResponse chatResponse) {
		return ToolCallingChatOptions.isInternalToolExecutionEnabled(promptOptions) && chatResponse != null
				&& chatResponse.hasToolCalls();
	}

}

 

ChatModel 빈을 생성할 때, ToolExecutionEligibilityPredicate의 사용자 정의 구현을 제공할 수 있습니다.

 

사용자 제어 도구 실행 (User-Controlled Tool Execution)

도구 실행 생명주기를 직접 제어하고 싶은 경우가 있을 수 있습니다. 이럴 때는 ToolCallingChatOption의 internalToolExecutionEnabled 속성을 false로 설정하면 됩니다.

 

이 옵션을 설정한 상태에서 ChatModel을 호출하면, 도구 실행은 호출자에게 위임되며 전체 도구 실행 흐름을 직접 제어할 수 있게 됩니다. 이 경우, ChatResponse에 도구 호출이 포함되어 있는지를 직접 확인하고, 이를 ToolCallingManager를 통해 실행하는 책임은 사용자에게 있습니다. 

 

다음은 사용자 제어 방식(user-controlled tool execution approach)의 최소 구현 예시입니다:

ChatModel chatModel = ...
ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();

ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(new CustomerTools())
    .internalToolExecutionEnabled(false)
    .build();
Prompt prompt = new Prompt("Tell me more about the customer with ID 42", chatOptions);

ChatResponse chatResponse = chatModel.call(prompt);

while (chatResponse.hasToolCalls()) {
    ToolExecutionResult toolExecutionResult = toolCallingManager.executeToolCalls(prompt, chatResponse);

    prompt = new Prompt(toolExecutionResult.conversationHistory(), chatOptions);

    chatResponse = chatModel.call(prompt);
}

System.out.println(chatResponse.getResult().getOutput().getText());

참고
사용자 제어 도구 실행 방식을 선택할 경우, 도구 실행 작업을 관리하기 위해 ToolCallingManager를 사용하는 것을 권장합니다. 이렇게 하면 Spring AI에서 제공하는 내장 도구 실행 기능을 그대로 활용할 수 있습니다. 단, 필요하다면 도구 실행 로직을 직접 구현해 사용하는 것도 가능합니다.

 

다음 예시는 ChatMemory API를 함께 사용하는 사용자 제어 도구 실행 방식(user-controlled tool execution approach)의 최소 구현 예를 보여줍니다:

ToolCallingManager toolCallingManager = DefaultToolCallingManager.builder().build();
ChatMemory chatMemory = MessageWindowChatMemory.builder().build();
String conversationId = UUID.randomUUID().toString();

ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(ToolCallbacks.from(new MathTools()))
    .internalToolExecutionEnabled(false)
    .build();
Prompt prompt = new Prompt(
        List.of(new SystemMessage("You are a helpful assistant."), new UserMessage("What is 6 * 8?")),
        chatOptions);
chatMemory.add(conversationId, prompt.getInstructions());

Prompt promptWithMemory = new Prompt(chatMemory.get(conversationId), chatOptions);
ChatResponse chatResponse = chatModel.call(promptWithMemory);
chatMemory.add(conversationId, chatResponse.getResult().getOutput());

while (chatResponse.hasToolCalls()) {
    ToolExecutionResult toolExecutionResult = toolCallingManager.executeToolCalls(promptWithMemory,
            chatResponse);
    chatMemory.add(conversationId, toolExecutionResult.conversationHistory()
        .get(toolExecutionResult.conversationHistory().size() - 1));
    promptWithMemory = new Prompt(chatMemory.get(conversationId), chatOptions);
    chatResponse = chatModel.call(promptWithMemory);
    chatMemory.add(conversationId, chatResponse.getResult().getOutput());
}

UserMessage newUserMessage = new UserMessage("What did I ask you earlier?");
chatMemory.add(conversationId, newUserMessage);

ChatResponse newResponse = chatModel.call(new Prompt(chatMemory.get(conversationId)));

예외 처리

도구 호출이 실패하면 예외는 ToolExecutionException으로 전달되며, 이를 잡아서 오류를 처리할 수 있습니다. ToolExecutionExceptionProcessor를 사용하면 ToolExecutionException을 처리할 수 있으며, 처리 결과는 AI 모델에 전달할 오류 메시지를 생성하거나, 호출자가 처리할 수 있도록 예외를 다시 던지는 두 가지 방식 중 하나가 될 수 있습니다.

@FunctionalInterface
public interface ToolExecutionExceptionProcessor {

    /**
     * 도구에서 발생한 예외를 AI 모델에 전달할 수 있는 문자열로 변환하거나,
     * 호출자가 처리할 수 있도록 예외를 다시 던집니다.
     */
    String process(ToolExecutionException exception);

}

 

Spring AI Spring Boot Starter를 사용하는 경우, ToolExecutionExceptionProcessor 인터페이스의 기본 구현체는 DefaultToolExecutionExceptionProcessor입니다. 기본적으로는 오류 메시지가 모델로 전달됩니다.

DefaultToolExecutionExceptionProcessor의 생성자를 통해 alwaysThrow 속성을 true 또는 false로 설정할 수 있으며, true로 설정하면 오류 메시지를 모델에 전달하는 대신 예외가 호출자에게 다시 던져집니다.

@Bean
ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
    return new DefaultToolExecutionExceptionProcessor(true);
}

참고
사용자 정의 ToolCallback 구현을 작성한 경우, call() 메서드 내에서 도구 실행 중 오류가 발생하면 반드시 ToolExecutionException을 던지도록 해야 합니다.

 

ToolExecutionExceptionProcessor는 도구 실행 중 발생한 예외를 처리하기 위해 기본 ToolCallingManager (DefaultToolCallingManager) 내부에서 사용됩니다. 도구 실행 생명주기에 대한 자세한 내용은 Tool Execution 항목을 참고하시기 바랍니다.

 

도구 해석

모델에 도구를 전달하는 기본 방식은 ChatClient나 ChatModel을 호출할 때 ToolCallback(들)을 제공하는 것입니다. 이 방식은 Methods as Tools 및 Functions as Tools에서 설명한 전략을 따릅니다.

 

그러나 Spring AI는 ToolCallbackResolver 인터페이스를 통해 런타임 시 도구를 동적으로 해석하는 기능도 지원합니다.

public interface ToolCallbackResolver {

    /**
     * 주어진 도구 이름에 해당하는 {@link ToolCallback}을 해석하여 반환합니다.
     */
    @Nullable
    ToolCallback resolve(String toolName);

}

 

이 방식을 사용할 경우:

• 클라이언트 측에서는, ToolCallback 인스턴스를 직접 전달하는 대신 도구 이름을 ChatClient 또는 ChatModel에 제공합니다.
• 서버 측에서는, ToolCallbackResolver 구현체가 도구 이름을 실제 ToolCallback 인스턴스로 해석하는 역할을 담당합니다.

기본적으로 Spring AI는 여러 ToolCallbackResolver 인스턴스에 위임하는 구조인 DelegatingToolCallbackResolver를 사용합니다:

• SpringBeanToolCallbackResolver는 Function, Supplier, Consumer, BiFunction 타입의 Spring 빈에서 도구를 해석합니다. 자세한 내용은 Dynamic Specification: @Bean 항목을 참고하십시오.
• StaticToolCallbackResolver는 정적인 ToolCallback 인스턴스 목록에서 도구를 해석합니다. Spring Boot 자동 구성(Spring Boot Autoconfiguration)을 사용하는 경우, 애플리케이션 컨텍스트에 정의된 모든 ToolCallback 빈이 자동으로 이 해석기에 등록됩니다.

Spring Boot 자동 구성을 사용하는 경우, 다음과 같이 사용자 정의 ToolCallbackResolver 빈을 정의하여 도구 해석 로직을 커스터마이징 할 수 있습니다:

@Bean
ToolCallbackResolver toolCallbackResolver(List<FunctionCallback> toolCallbacks) {
    StaticToolCallbackResolver staticToolCallbackResolver = new StaticToolCallbackResolver(toolCallbacks);
    return new DelegatingToolCallbackResolver(List.of(staticToolCallbackResolver));
}

 

ToolCallbackResolver는 ToolCallingManager 내부에서 사용되어 런타임에 도구를 동적으로 해석하는 역할을 하며, 프레임워크 주도 방식(Framework-Controlled Tool Execution)과 사용자 주도 방식(User-Controlled Tool Execution) 모두를 지원합니다.

 

통합가시성 (Observability)

도구 호출 기능은 spring.ai.tool 관측 항목(observation)을 통해 완료 시간 측정 및 트레이싱 정보 전파를 지원합니다. 자세한 내용은 Tool Calling Observability를 참고하시기 바랍니다.

 

옵션으로, Spring AI는 도구 호출의 인자 및 결과 데이터를 스팬(span) 속성으로 내보낼 수 있습니다. 이 기능은 민감한 정보 보호를 위해 기본적으로 비활성화되어 있습니다. 자세한 내용은 Tool Call Arguments and Result Data 항목을 참고하시기 바랍니다.

로깅(Logging)

도구 호출 기능의 주요 동작은 모두 DEBUG 레벨로 로깅됩니다. 관련 로그를 활성화하려면 org.springframework.ai 패키지의 로그 레벨을 DEBUG로 설정하시면 됩니다.

 

Reference

• Spring AI : Tool Calling