Spring AI Agentic Patterns (Part 3): TodoWriteTool — 에이전트가 중간 단계를 잊지 않게 만드는 방법
Spring AI Agentic Patterns (Part 3): TodoWriteTool — 에이전트가 중간 단계를 잊지 않게 만드는 방법
복잡한 작업을 AI 에이전트에게 맡겨 보면 은근 자주 겪는 일이 있다.
처음엔 그럴듯하게 계획을 세우는 것처럼 보이는데, 작업이 길어질수록 중간 단계를 하나씩 놓친다는 점이다.
- 파일 수정은 했는데 테스트를 안 돌리고
- 테스트는 돌렸는데 문서를 안 고치고
- 설명은 했는데 마지막 정리를 빼먹고
- 처음 요구사항에 있던 핵심 조건이 중간에 사라진다
이건 단순한 “성능 부족” 문제라기보다, 긴 컨텍스트 안에서 해야 할 일들이 가운데에 묻히는 전형적인 현상에 가깝다. Spring AI의 TodoWriteTool은 이 문제를 꽤 실용적인 방식으로 다룬다.
핵심은 간단하다.
계획을 머릿속에만 두지 말고, 에이전트가 스스로 할 일 목록을 외부에 적게 하자.
TodoWriteTool이 하는 일
TodoWriteTool은 LLM이 작업 중에 할 일 목록을 생성하고, 진행 상태를 갱신하고, 새로 발견한 일까지 추가할 수 있게 해주는 도구다.
원문에서 강조하는 포인트는 이게 단순 메모장이 아니라는 점이다. 에이전트의 암묵적인 계획을 명시적이고 관찰 가능한 워크플로우로 바꿔 준다.
각 todo 항목은 보통 다음 정보를 가진다.
idcontent: 해야 할 일status: 대기 / 진행 중 / 완료
이 구조가 별것 아닌 것처럼 보여도 효과가 크다. 이유는 두 가지다.
- 모델이 지금 무엇을 하고 있는지 잊지 않기 쉬워진다.
- 사용자와 개발자가 현재 진행 상태를 관찰할 수 있다.
중요한 제약: 동시에 하나만 진행 중
원문에서 특히 좋다고 느껴지는 설계는, 한 번에 하나의 task만 in_progress 상태가 될 수 있게 강제한다는 점이다.
이게 왜 중요하냐면, 에이전트는 그럴듯하게 “여러 작업을 동시에 잘할 것 같은” 느낌을 주지만 실제로는 산만해지기 쉽기 때문이다. 한 번에 하나만 진행 중으로 두면,
- 지금 무엇을 하는지 선명해지고
- 단계별 집중이 쉬워지고
- 중간에 새 작업이 생겨도 목록 안에서 흡수할 수 있다
즉 TodoWriteTool은 단순 기록이 아니라, 에이전트 실행 리듬을 강제로 정돈하는 장치이기도 하다.
언제 써야 하나
원문 툴 설명에는 꽤 실용적인 기준이 들어 있다.
3개 이상의 구분되는 단계가 필요한 작업이면 사용하고, 단순하고 짧은 작업이면 생략하라.
이 기준이 좋은 이유는, 너무 작은 작업까지 전부 todo로 만들면 오히려 오버헤드가 커지기 때문이다.
예를 들어 아래 같은 작업은 도입 가치가 높다.
- 기능 구현 + 테스트 + 문서 갱신
- 분석 + 비교 + 최종 추천
- 자료 조사 + 정리 + 요약본 작성
- 여러 파일을 건드리는 리팩터링
반대로 “문장 하나 다듬기”, “간단한 질의응답” 같은 건 굳이 todo를 만들 필요가 없다.
Chat Memory와 함께 봐야 한다
이 글에서 중요한 실무 포인트 하나는 TodoWriteTool이 Chat Memory와 거의 세트처럼 움직인다는 점이다.
원문은 특히 다음을 강조한다.
- Todo 업데이트 내용이 메모리에 남아야 하고
- 모델이 그 상태를 다시 참조할 수 있어야 하며
- 재귀적 툴 호출 흐름에서는
ToolCallAdvisor와 메모리 어드바이저 구성이 중요하다
즉 TodoWriteTool은 “체크리스트 하나 붙이면 끝”이 아니다. 실제로는
- tool calling
- memory
- advisor 체인
이 함께 맞물려야 제대로 효과가 난다.
이 점이 Spring AI스럽다. 단일 기능으로 포장하기보다, 에이전트 실행 파이프라인의 일부로 설계하게 만든다.
이벤트 기반 진행 상황 표시도 가능하다
원문에서 꽤 실용적인 부분은 todo 변경 이벤트를 발행해서 UI에 연결할 수 있다는 점이다.
예를 들면 이런 식이다.
- 콘솔에서는 현재 진행률 출력
- 웹에서는 작업 상태 패널 실시간 갱신
- 관리자 화면에서는 에이전트 진행 상황 추적
이 구조가 왜 좋냐면, 사용자가 “지금 뭐 하는 중이지?”를 덜 불안해하기 때문이다. 에이전트 UX에서 체감 품질은 정답만이 아니라 진행 상태의 가시성에서도 크게 갈린다.
AskUserQuestionTool 다음에 TodoWriteTool이 오는 이유
시리즈 흐름상 이 글이 AskUserQuestionTool 다음에 오는 건 자연스럽다.
- AskUserQuestionTool은 무엇을 해야 하는지 더 정확히 묻는 단계를 다루고
- TodoWriteTool은 그 작업을 어떻게 잊지 않고 끝까지 밀고 갈지를 다룬다
즉 하나는 요구사항 정렬이고, 다른 하나는 실행 관리다.
에이전트를 실무형으로 만들려면 두 축이 모두 필요하다.
이 도구가 특히 잘 맞는 앱
개인적으로 TodoWriteTool은 아래 상황에서 효과가 크다.
1) 코드 작업형 에이전트
파일 수정, 테스트, 검토, 문서 반영처럼 단계가 분명한 경우.
2) 운영/지원형 에이전트
장애 분석, 체크리스트 기반 점검, 후속 조치 정리.
3) 장문 산출물 생성형 에이전트
조사 → 구조화 → 초안 → 검토 → 마무리 같은 흐름이 있는 경우.
4) 사용자 신뢰가 중요한 업무
에이전트가 지금 무엇을 하는지 보이는 것만으로도 신뢰도가 올라간다.
한계도 있다
물론 todo를 쓴다고 모든 문제가 해결되지는 않는다.
- 작업 분해가 나쁘면 목록도 나쁘다.
- 너무 잘게 쪼개면 오히려 느려진다.
- 메모리 구성이 부실하면 todo 상태가 제대로 반영되지 않는다.
- 사용자에게는 “보여 주는 계획”과 “실제로 필요한 계획”이 다를 수 있다.
그래서 핵심은 많아 보이는 계획이 아니라, 실행 가능한 적정 수준의 계획이다.
이 글에서 가져가야 할 핵심
TodoWriteTool의 진짜 가치는 화려한 기능보다 다음 한 문장에 있다.
에이전트의 계획을 외부화해서, 잊지 않게 하고, 보이게 만든다.
AI 에이전트는 종종 똑똑해 보이지만, 중간 단계 관리에는 놀랄 만큼 허술할 수 있다. TodoWriteTool은 바로 그 약점을 메우는 가장 현실적인 패턴 중 하나다.
마무리
TodoWriteTool은 “할 일 목록 앱을 에이전트에 붙였다” 수준이 아니다. 더 정확히는, 에이전트 실행 과정을 관찰 가능한 워크플로우로 끌어내는 장치다.
Spring AI 관점에서 보면 이 도구의 의미는 더 분명하다.
- tool calling과 연결되고
- chat memory와 맞물리며
- advisor 체인 안에서 실행 흐름을 안정화한다
즉 단순 편의 기능이 아니라, 에이전트를 운영 가능한 형태로 바꾸는 설계 요소에 가깝다.
다음 글의 Subagent Orchestration으로 넘어가면 문제는 한 단계 더 커진다. 이제는 한 에이전트가 할 일을 잊지 않는 수준을 넘어서, 전문화된 여러 에이전트에게 일을 나누는 구조를 다루게 된다.
Series Links
- Part 1: Agent Skills 한국어 정리
- Part 2: AskUserQuestionTool 한국어 정리
- Part 3: TodoWriteTool (원문)
- Part 4: Subagent Orchestration 한국어 정리
- Part 5: A2A Integration 한국어 정리
- Dynamic Tool Discovery 한국어 정리
- Tool Argument Augmentation 한국어 정리