Tool Argument Augmentation — 툴 호출 이유까지 잡아내는 Spring AI의 묘한 확장 포인트
Tool Argument Augmentation — 툴 호출 이유까지 잡아내는 Spring AI의 묘한 확장 포인트
툴 호출 기반 에이전트를 만들다 보면 어느 순간 궁금해지는 게 있다.
모델이 왜 이 도구를 골랐는지 알고 싶다는 점이다.
지금까지의 툴 호출은 보통 여기서 멈춘다.
- 어떤 도구를 골랐는가
- 어떤 인자를 넣었는가
- 결과가 무엇이었는가
하지만 실제 디버깅과 운영에서는 이것만으로 부족할 때가 많다.
- 왜 이 도구가 필요하다고 판단했지?
- 자신감은 어느 정도였지?
- 어떤 중간 판단을 하고 있었지?
- 이 정보를 메모리로 남기면 다음 대화에 도움이 되지 않을까?
Spring AI의 Tool Argument Augmentation은 바로 이런 요구를 겨냥한다. 핵심은 툴 자체를 바꾸지 않고도, 툴 입력 스키마에 추가 필드를 동적으로 붙여서 모델의 reasoning이나 메타데이터를 함께 받는 것이다.
문제는 분리 계층에 있다
직관적으로는 “그냥 모든 도구에 reasoning 필드 하나 더 넣으면 되지 않나?” 싶다. 하지만 그건 금방 나쁜 구조가 된다.
- 모든 로컬 툴 시그니처를 바꿔야 하고
- 외부 툴이나 MCP 툴은 수정이 불가능할 수 있고
- 툴 본래 책임과 관찰/메모리 책임이 뒤섞인다
즉 애플리케이션이 추가로 필요로 하는 정보와, 툴 자체가 필요로 하는 입력은 분리되어야 한다. Tool Argument Augmentation은 이 문제를 꽤 우아하게 해결한다.
어떻게 동작하나
원문 설명을 풀면 흐름은 이렇다.
- 원래 도구 정의가 있다.
- LLM에게 보내기 직전에 입력 JSON Schema를 가로챈다.
- 여기에
innerThought,confidence,memoryNotes같은 추가 필드를 붙인다. - 모델은 원래 인자 + 추가 인자를 함께 채워서 반환한다.
- 애플리케이션은 추가 인자를 따로 소비한다.
- 실제 도구에는 원래 필요한 인자만 넘긴다.
즉 모델은 확장된 스키마를 보지만, 도구 구현체는 자신이 확장되었다는 사실조차 몰라도 된다.
이게 이 기능의 핵심 미덕이다.
reasoning capture의 실전 가치
이 기능이 흥미로운 건 단순 로그용이 아니라는 점이다. 원문은 특히 두 가지 용도를 강조한다.
1) Observability / Debugging
모델이 툴을 선택한 이유를 직접 볼 수 있다.
예를 들어 “Amsterdam에서 오늘 뭘 입어야 하지?”라는 질문에 날씨 도구를 호출할 때, 모델이 왜 날씨 확인이 필요하다고 봤는지 reasoning을 남길 수 있다.
이건 디버깅에 엄청 유용하다. 잘못된 툴 선택이 생겼을 때 결과만 보는 것보다, 선택 논리를 보는 편이 훨씬 빠르게 원인을 찾을 수 있다.
2) Memory Enhancement
툴 호출 직전의 판단을 장기 메모리로 남길 수 있다.
이건 꽤 재미있는 지점이다. 보통 메모리라고 하면 사용자 선호나 사실 정보만 떠올리는데, 원문은 모델의 판단 흔적 자체를 미래 추론에 쓸 수 있는 문맥으로 본다.
예를 들어,
- 사용자가 어떤 종류의 질문을 자주 하는지
- 어떤 추가 확인이 자주 필요한지
- 어떤 맥락에서 어떤 툴을 선호했는지
같은 힌트를 축적할 수 있다.
구현 방식이 Spring AI스럽다
원문은 AugmentedToolCallbackProvider를 통해 기존 툴이나 기존 ToolCallbackProvider를 감싸는 방식을 보여 준다.
이 설계가 좋은 이유는, 새로운 툴 체계를 강요하지 않기 때문이다.
- 기존
@Tool기반 로컬 도구도 감쌀 수 있고 - 기존 ToolCallbackProvider도 감쌀 수 있고
- MCP 도구 제공자도 같은 패턴으로 확장 가능하다
즉 Tool Argument Augmentation은 기존 도구 레이어를 깨지 않고, 가로단 관찰/메타데이터 계층을 덧씌우는 방식이다.
Structured Output과 함께 쓰면 더 강하다
원문 후반부에서 재밌는 포인트 하나는, reasoning을 단지 내부 로그로만 남기지 않고 Structured Output으로 최종 응답에 함께 실어 보낼 수도 있다는 점이다.
이건 상황에 따라 꽤 유용하다.
- 관리자용 디버그 화면
- 감사 로그
- 내부 운영 도구
- 모델 판단 근거를 보여 주는 고신뢰 앱
다만 사용자-facing 서비스에선 그대로 노출할지 신중해야 한다. reasoning을 전부 다 내보내는 게 항상 좋은 UX는 아니기 때문이다.
MCP와도 잘 맞는다
이 기능이 더 흥미로운 건 MCP 도구와도 자연스럽게 이어진다는 점이다. 도구 자체를 수정하지 못하는 외부 제공 툴에도 augmentation 계층을 둘 수 있기 때문이다.
이건 실무적으로 꽤 중요하다. 현실의 에이전트는 로컬 툴만 쓰지 않고, 외부 프로토콜 기반 툴과 섞여 있기 때문이다. Tool Argument Augmentation은 이런 혼합 환경에서도 애플리케이션 주도의 관찰 가능성을 확보하게 해 준다.
하지만 조심할 점도 있다
좋은 기능이지만 몇 가지 주의할 점은 있다.
- reasoning 필드를 너무 많이 요구하면 프롬프트가 무거워진다.
- 모델이 형식적으로만 reasoning을 채울 수도 있다.
- 민감한 내부 추론을 그대로 저장/노출하는 것은 보안/개인정보 이슈를 만들 수 있다.
- “설명 가능성”이 생겼다고 해서 그 자체가 진실 보장을 의미하진 않는다.
즉 핵심은 생각을 무조건 많이 받는 게 아니라, 애플리케이션에 진짜 필요한 메타데이터만 최소한으로 받는 것이다.
이 글에서 가져가야 할 핵심
Tool Argument Augmentation의 진짜 매력은 다음 한 문장으로 요약된다.
툴 구현을 바꾸지 않고도, 모델의 툴 선택 맥락을 애플리케이션 레이어에서 포착할 수 있다.
이건 에이전트 운영에서 꽤 큰 변화다. 이제 우리는 “무슨 도구를 불렀는가”뿐 아니라, “왜 그렇게 판단했는가”까지 좀 더 구조적으로 다룰 수 있다.
마무리
Tool Argument Augmentation은 눈에 띄는 데모 기능은 아닐 수 있다. 하지만 실제로는 아주 깊은 의미가 있다.
- 관찰 가능성을 높이고
- 메모리를 더 풍부하게 만들고
- 툴 호출 디버깅을 쉽게 하고
- 기존 도구 구조를 깨지 않는다
즉 이 기능은 에이전트를 더 화려하게 만들기보다, 더 이해 가능한 시스템으로 만드는 방향에 가깝다.
Spring AI가 이런 확장 포인트를 코어 레벨에서 제공한다는 점은 꽤 인상적이다. 툴 호출을 단순 기능 호출이 아니라, 관찰·메모리·신뢰성까지 엮이는 애플리케이션 구조로 보고 있다는 뜻이기 때문이다.
Series Links
- Spring AI Agentic Patterns (Part 1): Agent Skills 한국어 정리
- AskUserQuestionTool 한국어 정리
- TodoWriteTool 한국어 정리
- Subagent Orchestration 한국어 정리
- A2A Integration 한국어 정리
- Dynamic Tool Discovery 한국어 정리
- Tool Argument Augmentation (원문)