Spring AI의 새로운 도구 호출 기능: AI와 API의 강력한 연동 방법!

 

🔎 AI와 API 연동의 새로운 패러다임, Tool Calling

AI 애플리케이션에서 API와의 연동은 필수적입니다. 기존에는 함수 호출(Function Calling) 기능을 사용했지만, Spring AI에서는 이를 대체할 Tool Calling(도구 호출) 기능을 새롭게 도입했습니다.

이번 블로그에서는 Spring AI의 Tool Calling 기능이 무엇인지, 기존 방식과 비교해 어떤 장점이 있는지, 그리고 실제 구현 방법까지 자세히 알아보겠습니다. 🚀

반응형

---

📌 Spring AI Tool Calling이란?

Tool Calling(도구 호출)은 AI 모델이 특정 API나 도구를 직접 호출하여 데이터를 가져오거나 연산을 수행할 수 있도록 지원하는 기능입니다.

✅ 이전 방식: 기존에는 함수 호출 API를 사용해 Java의 메서드를 실행했지만, Spring AI에서는 이 API를 더 이상 지원하지 않습니다.
✅ 새로운 방식: Tool Calling 기능을 사용하면 Spring Boot 애플리케이션 내에서 AI 모델이 필요한 정보를 자동으로 가져와 처리할 수 있습니다.

---

🔍 Tool Calling이 필요한 이유

AI 모델은 기본적으로 학습된 데이터만을 기반으로 동작합니다. 하지만 실시간 데이터(예: 최신 주식 시세, 사용자 데이터 등)를 처리하려면 외부 API나 데이터베이스와의 연동이 필수입니다.

🎯 예제: AI가 실시간 주식 데이터를 활용하는 방법

1️⃣ 사용자가 AI에게 "내 주식 포트폴리오의 총 가치는 얼마야?"라고 질문
2️⃣ AI는 내부 데이터베이스에서 보유 주식 수량을 가져옴
3️⃣ AI가 최신 주가 정보를 외부 API에서 호출
4️⃣ AI가 모든 데이터를 종합하여 포트폴리오의 총 가치를 계산 후 반환

이처럼 AI가 직접 API를 호출하고 필요한 데이터를 가져올 수 있도록 도와주는 기능이 바로 Tool Calling입니다.

---

🛠 Spring AI에서 Tool Calling 구현하기

Spring AI의 Tool Calling 기능을 활용해 실제 구현을 진행해 보겠습니다.

1️⃣ 데이터베이스에서 주식 정보 가져오기

우선, 보유한 주식 수량을 조회하는 WalletTools 클래스를 생성합니다.

public class WalletTools {

    private WalletRepository walletRepository;

    public WalletTools(WalletRepository walletRepository) {
        this.walletRepository = walletRepository;
    }

    @Tool(description = "내 포트폴리오에 있는 각 회사의 주식 수량 조회")
    public List<Share> getNumberOfShares() {
        return (List<Share>) walletRepository.findAll();
    }
}

🔹 @Tool(description = "...") 애노테이션을 사용해 AI가 이 메서드의 역할을 이해할 수 있도록 설명을 추가합니다.
🔹 walletRepository.findAll()을 호출해 모든 보유 주식 정보를 가져옵니다.

2️⃣ 외부 API에서 최신 주식 가격 가져오기

외부 주식 API를 호출하는 StockTools 클래스를 생성합니다.

public class StockTools {

    private RestTemplate restTemplate;
    @Value("${STOCK_API_KEY:none}")
    String apiKey;

    public StockTools(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    @Tool(description = "특정 기업의 최신 주가 조회")
    public StockResponse getLatestStockPrices(@ToolParam(description = "기업명") String company) {
        StockData data = restTemplate.getForObject(
                "https://api.twelvedata.com/time_series?symbol={0}&interval=1min&outputsize=1&apikey={1}",
                StockData.class, company, apiKey);
        
        return new StockResponse(Float.parseFloat(data.getValues().get(0).getClose()));
    }
}

🔹 @Tool을 활용해 AI가 적절한 메서드를 호출하도록 만듭니다.
🔹 @ToolParam을 사용해 메서드에 전달될 매개변수를 정의합니다.
🔹 RestTemplate을 이용해 TwelveData API에서 최신 주가 데이터를 가져옵니다.

3️⃣ AI와 연동하여 Tool Calling 실행하기

컨트롤러에서 AI 모델과 연동해 포트폴리오의 총 가치를 계산하는 API를 만듭니다.

@RestController
@RequestMapping("/wallet")
public class WalletController {

    private final ChatClient chatClient;
    private final StockTools stockTools;
    private final WalletTools walletTools;

    public WalletController(ChatClient.Builder chatClientBuilder,
                            StockTools stockTools,
                            WalletTools walletTools) {
        this.chatClient = chatClientBuilder.defaultAdvisors(new SimpleLoggerAdvisor()).build();
        this.stockTools = stockTools;
        this.walletTools = walletTools;
    }

    @GetMapping("/with-tools")
    String calculateWalletValueWithTools() {
        PromptTemplate pt = new PromptTemplate("""
        내 주식 포트폴리오의 총 가치는 얼마야?
        """);

        return this.chatClient.prompt(pt.create())
                .tools(stockTools, walletTools)
                .call()
                .content();
    }
}

🔹 AI 모델이 stockTools와 walletTools을 사용해 필요한 데이터를 가져오도록 설정합니다.
🔹 chatClient.tools(stockTools, walletTools).call()을 통해 AI가 자동으로 필요한 데이터를 조회하도록 만듭니다.

---

🧪 실행 및 테스트

1️⃣ 애플리케이션 실행하기

환경 변수를 설정한 후, Spring Boot 애플리케이션을 실행합니다.

export OPEN_AI_TOKEN=<YOUR_OPEN_AI_TOKEN>
export STOCK_API_KEY=<YOUR_STOCK_API_KEY>

mvn spring-boot:run

2️⃣ API 호출하여 AI 응답 확인하기

curl http://localhost:8080/wallet/with-tools

📌 실행하면 AI가 내부 DB에서 주식 보유 수량을 가져오고, 외부 API에서 최신 주가를 가져와 포트폴리오의 총 가치를 계산해 반환합니다.

728x90

---

🎯  Spring AI Tool Calling이 주는 이점

Spring AI의 Tool Calling 기능은 기존 함수 호출 방식보다 더욱 유연하고 강력한 AI-API 연동 방식을 제공합니다.

✅ AI가 직접 API를 호출해 필요한 데이터를 실시간으로 가져올 수 있음
✅ 데이터베이스, 외부 API와 손쉽게 연동 가능
✅ Spring Boot와 간편하게 통합 가능

앞으로 AI 기반 애플리케이션을 개발할 때 Tool Calling을 활용하면 더욱 실용적인 서비스를 만들 수 있을 것입니다. 🚀

https://piotrminkowski.com/2025/03/13/tool-calling-with-spring-ai/?fbclid=IwZXh0bgNhZW0CMTEAAR3dzZ0lMnOHX4nGn5pHa1ND1pFqGw3no6YFu1174Oem2nU-d4Fz2-D4e1w_aem_zSiqIzydMjXM7tsu5IYHlg

Tool Calling with Spring AI - Piotr's TechBlog