Spring AI Tool Calling과 작동 프로세스

JSCODE 시니

2026. 06. 13.

✅ 1. Spring AI Tool Calling이란 무엇일까?

• Tool Calling(또는 Function Calling)은 AI 모델이 외부 시스템(DB, API, 사내 시스템)과 직접 상호작용할 수 있도록 권한을 부여하는 기능

• 주요 용도
• 정보 검색: 최신 날씨, 실시간 주가, 사내 DB 검색
• 작업 수행: 이메일 발송, 결제 승인, DB 데이터 수정

• 개발자의 역할 : AI가 사용할 수 있는 도구(기능)를 개발하고, AI가 이해할 수 있는 규격(Tool Spec)으로 정의해 주어야 함

✅ 2. RAG / 일반 API 호출과는 무엇이 다를까?

• 가장 큰 차이는 ‘누가 주도권을 가지고 있는가?’임

• RAG / 일반 호출: 개발자(사람)가 판단해서 참고할 데이터를 결정해주면, AI가 검색함

• Tool Calling: AI가 스스로 판단함

• 유저의 질문을 듣고 "아, 이건 내가 모르는 거니까 외부 도구를 써서 데이터를 가져와야겠다" 혹은 "사용자에게 추가 정보를 더 물어봐야겠다"라고 AI가 먼저 요청을 보내는 것이 특징임

✅ 3. Tool Calling의 작동 프로세스 (6단계)

• 도구 정의 전달
• 유저의 질문과 함께 쓸 수 있는 도구 목록과 설명서(Tool Spec)를 AI에게 보냄

• AI의 판단 (Tool Call)
• AI가 "이 질문은 OOO 도구가 필요하네!"라고 판단하면, 도구 이름과 실행할 파라미터를 담아 서버로 응답을 보냄

• 도구 실행 (개발자 영역)
• Spring 서버가 AI의 요청을 받아 실제 자바 코드로 된 Tool(메서드)을 실행함

• 결과 처리 판단
• 실행 결과를 그대로 사용자에게 반환할지(returnDirect), 다시 AI에게 보낼지 판단함

• 결과 전달
• Tool 실행 결과를 다시 AI 모델에게 던져줌

• 최종 응답 생성
• AI가 Tool의 결과를 바탕으로 유저의 질문에 대한 최종 답변을 만들어 반환함

✅ 4. Tool Specification

• AI가 자바 코드를 직접 읽을 수는 없으므로, 도구의 사용법을 JSON Schema 형태로 번역해서 알려주어야 함.

• 참고로 OpenAI가 최초로 정의한 규격을 따름

• type: 도구의 유형 (대부분 "function")

• name: 도구의 이름

• description: 이 도구가 언제, 왜 쓰이는지 AI에게 설명하는 부분.

• parameters: 입력값의 이름, 타입, 필수 여부 (JSON Schema 규격)

✅ 5. Spring AI에서 Tool을 구현하는 방법

• Spring AI는 ToolCallback 인터페이스를 통해 Tool을 모델링함. 방법은 여러가지가 있음

• @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();
    }

}