Spring AI 2.0: 도구 호출 기능으로 에이전트 아키텍처 혁신
Spring AI 1.x의 내부에 숨겨져 있던 도구 호출 기능을 2.0에서 에이전트 아키텍처(Agent Architecture)의 핵심 구성 요소로 분리함
ToolCallingAdvisor를 통해 도구 호출 루프를 재귀적으로 처리하며, 메모리(Memory) 및 관찰 가능성(Observability) 통합을 지원함
ToolSearchToolCallingAdvisor로 수백 개의 도구 관리 시 컨텍스트 블로트(Context Bloat)를 줄이고 토큰 비용 절감을 달성함
Spring AI 2.0의 재설계된 도구 호출 아키텍처
Spring AI 2.0은 이전 버전과 달리 도구 호출(Tool Calling) 루프를 에이전트 아키텍처(Agent Architecture)의 핵심 구성 요소로 분리하여 재귀적 어드바이저(Recursive Advisor)인 ToolCallingAdvisor로 통합함.
이전 버전에서는 각 모델 구현체 내부에 도구 실행 로직이 숨겨져 있어 확장성 및 조합성(Composability)이 제한적이었으나, 2.0에서는 어드바이저 체인(Advisor Chain)으로 끌어올려 첫 번째 클래스 구성 요소(First-class Component)로 다룸.
이 메커니즘은 도구 호출 루프뿐만 아니라 구조화된 출력 재시도(Structured Output Retry) 및 평가 루프(Evaluation Loop) 등 다양한 동작을 지원하며, 메모리(Memory) 및 관찰 가능성(Observability) 통합을 용이하게 함.
도구 정의 및 실행 방식의 변화
Spring AI 2.0에서는 `@Tool` 어노테이션을 메서드에 적용하는 것만으로도 JSON 스키마(JSON Schema) 생성이 자동화되어 도구 정의가 간편해짐.
`@ToolParam`을 사용하여 파라미터별 설명과 필수/선택 여부를 지정할 수 있으며, `@Nullable` 어노테이션은 기본적으로 선택적 파라미터로 처리됨.
ToolCallingAdvisor는 등록된 모든 도구의 이름, 설명, 입력 스키마를 추출하여 초기 컨텍스트에 주입하며, LLM의 응답에 도구 호출이 포함된 경우 ToolCallingManager가 해당 도구를 찾아 실행하고 결과를 대화 기록에 추가함.
데이터 격리 아키텍처(Data Isolation Architecture)를 위해 `InMemoryChatMemoryRepository`, `RedisChatMemoryRepository` 등 특정 메모리 저장소 구현체만이 도구 메시지를 포함한 전체 대화 기록을 안전하게 저장할 수 있음.
수백 개 도구 관리를 위한 ToolSearchToolCallingAdvisor
도구 수가 30개 이상이거나 MCP 환경에서 수백 개 도구가 집계될 경우, 기존 `ToolCallingAdvisor`는 컨텍스트 블로트(Context Bloat)와 토큰 비용 증가를 유발함.
`ToolSearchToolCallingAdvisor`는 점진적 도구 공개 패턴(Progressive Tool Disclosure Pattern)을 적용하여, 모든 도구 정의를 한 번에 보내는 대신 요청 시 관련 도구만 점진적으로 주입함.
벡터 검색(Vector Search), 루씬(Lucene), 정규식(Regex) 등 다양한 도구 인덱싱 전략을 지원하며, 세션별 도구 인덱스를 사용하여 토큰 사용량 34–64% 절감 효과를 벤치마크 결과로 입증함.
이 기능은 스마트 도구 선택(Smart Tool Selection)을 통해 LLM의 정확도를 높이고 불필요한 비용을 줄이는 데 기여함.
도구 호출 루프 내에서의 메모리 관리 전략
메모리 어드바이저(Memory Advisor)의 위치에 따라 도구 호출 루프(Tool Calling Loop) 내에서 대화 기록(Conversation History)의 저장 범위가 결정됨.
루프 외부(기본값): 최종 사용자 및 어시스턴트 메시지만 저장하여 데이터 미저장 정책(Zero-Retention Policy)과 유사하게 동작하며, Spring AI 1.x와 동일한 메모리 동작을 보임.
루프 내부: 모든 도구 요청 및 응답 트랜잭션을 저장하여 LLM이 이전 시도 내역을 바탕으로 더 풍부한 컨텍스트를 가질 수 있게 함.
`InMemoryChatMemoryRepository`, `RedisChatMemoryRepository` 등 일부 저장소는 도구 메시지 직렬화(Serialization)를 지원하며, JDBC 기반 저장소는 Spring-AI-Session 프로젝트를 통해 지원될 예정임.
MCP(Model Context Protocol) 도구 통합 및 확장성
Spring AI 2.0은 MCP 프로토콜을 통해 원격 MCP 서버의 도구를 소비하거나, 반대로 Spring 관리 도구를 MCP 서버로 노출하는 양방향 통합을 지원함.
`@McpTool` 어노테이션을 사용하여 Spring 빈을 MCP 도구로 쉽게 노출할 수 있으며, 클라이언트에서는 `SyncMcpToolCallbackProvider`를 통해 원격 도구를 동적으로 발견하고 호출함.
로컬 `@Tool` 메서드와 원격 MCP 도구는 동일한 `ToolCallback` 인터페이스를 공유하므로, 모델과 `ToolCallingAdvisor`는 이들을 구분하지 않고 처리함.
이름 충돌(Name Conflict) 시 `DefaultMcpToolNamePrefixGenerator`가 자동으로 접두사를 생성하며, `McpToolFilter`를 통해 노출되는 도구를 제한할 수 있어 보안 및 관리 효율성을 높임.
사용자 제어 도구 실행 및 커스텀 어드바이저 구축
기본 자동 등록된 도구 호출 루프 외에, 외부 승인 단계, SSE/WebSocket 엔드포인트 전달, 부채널 신호 기반 중단 등 특정 시나리오에서는 사용자 제어 실행이 필요함.
`AdvisorParams.toolCallingAdvisorAutoRegister(false)` 설정을 통해 자동 루프를 비활성화하고, `ToolCallingManager`를 사용하여 수동으로 도구 호출을 관리할 수 있음.
커스텀 `ToolCallingAdvisor`는 `ToolAdvisor` 인터페이스를 구현하고, `doInitializeLoop`, `doBeforeCall`, `doAfterCall` 등의 보호된 훅 메서드(Hook Method)를 오버라이드하여 루프의 특정 지점에서 동작을 제어함.
`ToolCallingAdvisor.Builder` 빈을 등록하여 커스텀 어드바이저를 자동 구성 시스템에 투명하게 통합할 수 있으며, 이는 `ToolSearchToolCallingAdvisor`가 내부적으로 사용하는 방식임.
