✅ 도구 호출(Tool Calling)

도구 호출^{Tool Calling}은 함수 호출^{Function Call}이라고도 불립니다. 도구 호출은 LLM이 애플리케이션 내부 또는 외부의 API와 상호작용함으로써 기능을 확장할 수 있도록 해주는 기술입니다.

애플리케이션이 보유한 도구 목록을 LLM에게 노출하면, LLM은 필요에 따라 이 도구들을 호출할 수 있습니다. LLM이 도구를 호출하는 주요 목적은 모델이 사전에 학습하지 못한 정보를 실시간으로 조회하거나, 외부 조치를 자동으로 실행하기 위해서입니다.

• 정보 조회

도구 호출을 통해 LLM은 데이터베이스, 웹 검색 엔진, 파일 시스템 등에서 정보를 검색할 수 있습니다. 이를 통해 LLM은 사전 학습된 지식에 의존하지 않고도 최신 정보나 사용자 맞춤형 데이터를 실시간으로 확인할 수 있기 때문에 스스로 답할 수 없는 질문에 대해서도 적절한 응답을 생성할 수 있게 됩니다.

• 조치 취하기

도구 호출은 단순한 정보 조회를 넘어 문제를 해결하기 위해 LLM이 적절한 조치를 수행할 때에도 호출할 수 있습니다. 예를 들어, 이메일 전송, 데이터베이스 갱신, 웹 양식 자동 작성 및 제출, 하드웨어 장치 제어 등 사람이 직접 수행하던 다양한 작업을 LLM이 대신 처리할 수 있습니다.

일반적으로 도구 호출^{Tool Calling}은 LLM의 확장 기능으로 설명되지만, 실제로 도구를 호출하고 실행하는 주체는 애플리케이션입니다.

LLM은 특정 작업을 수행하기 위해 도구 호출을 요청하고, 필요한 매개변수만 제공합니다. 이 요청을 받은 애플리케이션은 해당 메소드를 직접 실행하고, 그 결과를 다시 LLM에게 전달합니다. 따라서 실행 제어와 보안 관리의 책임은 애플리케이션에 있게 됩니다.

Spring AI는 도구를 정의하고, LLM의 도구 호출 요청을 처리하는 데 유용한 API를 제공합니다. 도구 호출을 위한 인터페이스와 어노테이션을 제공하여, 개발자가 애플리케이션의 메소드를 손쉽게 도구로 등록할 수 있도록 지원합니다. LLM이 도구 호출을 요청하면 해당 요청을 메소드로 매핑하고 실행한 뒤, 결과를 다시 LLM에 전달하는 흐름도 자동으로 처리됩니다.

다음은 Spring AI에서 도구 호출이 이루어지는 전반적인 흐름을 도식화한 것입니다.

❶  Spring AI는 도구 정의를 프롬프트에 포함해서 LLM으로 전송합니다. 도구 정의는 이름, 설명, 입력 스키마(매개변수) 등으로 구성됩니다.

❷  LLM이 도구의 설명을 검토한 후, 호출하기로 결정하면, 도구 이름과 입력 매개값을 포함한 응답을 Spring AI로 보냅니다.

❸ Spring AI는 도구 이름과 입력 매개값을 받고, 도구를 호출해서 실행합니다.

❹ ❺ Spring AI는 도구 호출 결과를 다시 LLM으로 전송합니다.

❻ LLM은 도구 호출 결과를 받고, 최종 응답을 생성하고 Spring AI로 보냅니다.

✅ 도구 정의하기

도구의 코드 형태는 메소드입니다. 메소드가 도구로서 사용되려면 @Tool 어노테이션을 적용해야 합니다. 다음은 도구를 정의하는 코드입니다.

@Tool(description = “도구 설명...”)
public String toolName(...) { 
    ...
}

• @Tool을 적용할 수 있는 메소드는 정적이거나 인스턴스 메소드일 수 있으며, 접근 제한자는 public, protected, default, private 중 어느 것이든 가능합니다.
   
• 도구의 매개변수 타입은 기본 타입(예: int, boolean, double)과 참조 타입을 모두 사용할 수 있습니다. 참조 타입에는 클래스, 인터페이스, 열거 타입(enum), 배열, List, Map 등이 포함됩니다. 매개변수의 개수에는 제한이 없습니다. 반환 타입 역시 void를 포함하여 참조 타입을 사용할 수 있습니다.

도구의 매개변수와 반환 타입은 LLM에게 전달할 수 있도록 JSON으로 직렬화가 가능한 구조여야 합니다. 따라서 직렬화되지 않는 특수 타입은 사용할 수 없습니다. 다음은 매개변수 및 반환 타입으로 사용할 수 없는 예외적인 타입들입니다.

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

이러한 도구 메소드들을 제공하는 클래스는 최상위 클래스뿐만 아니라 중첩 클래스^{nested class}로도 정의할 수 있습니다. 또한, 해당 클래스는 단순한 POJO^{Plain Old Java Object} 형태로 생성할 수도 있고, Spring 빈으로 등록하여 의존성 주입 등 Spring의 기능을 활용할 수도 있습니다. 

public class Tools { ... }

또는

@Component
public class Tools { ... }

✔️@Tool 어노테이션

@Tool 어노테이션은 description 속성 외에도 다음과 같은 속성들이 있습니다. 

@Tool(name=" ", description=" ", resultConverter=" ", returnDirect=[true | false])

✔️@ToolParam 어노테이션

@Tool의 description 속성은 LLM이 언제, 어떻게 해당 도구를 호출해야 하는지 결정하는 데 사용됩니다. description에 매개변수에 대한 설명을 넣을 수 있지만, 매개변수에 직접 @ToolParam을 적용해서 설명이나 필수 여부 등의 추가 정보를 제공할 수도 있습니다. 

예를 들어 다음 setAlarm 도구는 time 매개변수를 가지고 있습니다. LLM이 setAlarm 도구를 호출할 때 어떤 형식으로 time 매개값을 제공해야 하는지 @ToolParam 어노테이션을 적용해서 알려주고 있습니다.

@Tool(description = "지정된 시간에 사용자 알람을 설정합니다.")
public void setAlarm(
    @ToolParam(description = "ISO-8601 형식의 시간", required = true)  String time) {
    ...
    }

다음 표는 @ToolParam 어노테이션에서 사용할 수 있는 속성들입니다.

매개변수에 @Nullable 어노테이션이 적용되면, 명시적으로 @ToolParam 어노테이션을 사용하여 필수로 표시하지 않는 한 선택적인 것으로 간주됩니다.

매개변수의 필수 여부를 지정하는 것은 LLM이 도구를 호출할 때 올바른 입력을 제공하도록 보장합니다. 매개변수가 선택일 경우, LLM은 값을 제공하지 않고 도구를 호출할 수 있다는 의미입니다.

도구 호출은 LLM이 단순히 답변을 생성하는 수준을 넘어, 실제 애플리케이션과 유기적으로 협력할 수 있게 하는 핵심 기술입니다. Spring AI는 도구 정의부터 실행, 결과 반환까지의 과정을 일관성 있게 처리하여 개발자가 손쉽게 이 기능을 구현할 수 있도록 지원합니다. 이를 통해 LLM 기반 애플리케이션은 더욱 높은 수준의 자동화와 실시간 대응 능력을 확보할 수 있습니다.

위 콘텐츠는 『이것이 Spring AI다』의 내용을 재구성하여 작성되었습니다.