[AI Agent] KBO 메이트 Agent 서비스/MVP 명세 정리

개요

과거 Agent 기획 글

예전에 AI Agent 학습 과정에서 KBO 직관 플래너 Agent를 주제로 서비스 기획과 Tool 구조를 설계하고, 이를 바탕으로 대략적인 구현까지 진행한 적이 있습니다.

당시에는 Agent의 구조와 동작 방식을 직접 구현해보는 데 의미를 두었다면, 이번에는 그 경험을 바탕으로 기획부터 다시 다듬어 실제 서비스 수준의 완성도를 목표로 프로젝트를 처음부터 끝까지 개발해보려고 합니다.

기획
→ 서비스/MVP 정의
→ 데이터 설계
→ RAG 구축
→ Tool 구현
→ Agent 연결
→ Frontend/Backend 개발
→ 테스트와 개선

이번 프로젝트에서는 완성된 결과만 정리하는 것이 아니라, 각 단계의 개발 이력과 의사결정, 시행착오를 함께 기록하며 MVP 개발을 진행해나가겠습니다.

이 글은 그 시작점으로, 실제 개발에 들어가기 전에 서비스의 방향과 MVP 범위를 다시 정리한 내용입니다.

1. 서비스 정의

KBO 도우미 Agent는 KBO와 관련된 경기 일정, 구장 정보, 예매, 야구 규칙, 팀 정보, 날씨 등 사용자가 궁금한 정보를 질문에 맞게 찾아주고 연결해주는 AI Agent입니다.

이번 프로젝트에서는 단순히 LLM에 KBO 데이터를 연결하는 것보다, 이 문제가 실제로 Agent 구조에 적합한지부터 다시 정의하는 것을 먼저 진행했습니다.

AI Agent를 만들 때 가장 먼저 정해야 하는 것은 “LLM을 어디에 붙일 것인가”가 아닙니다.

먼저 아래 질문들을 답해야 될 필요가 있습니다.

이 문제가 정말 Agent가 필요한 문제인가?

사용자의 요청에 따라 실행 경로가 달라지는가?

Tool은 어떤 기준으로 나눌 것인가?

정확한 값이 필요한 정보와
설명형 정보는 어떻게 분리할 것인가?

MVP에서는 어디까지 구현하고
어디부터 다음 단계로 미룰 것인가?

KBO 관련 질문은 사용자의 목적에 따라 필요한 정보와 실행 경로가 달라집니다.

오늘 롯데 경기 있어?
→ 경기 일정 조회

잠실야구장 위치 알려줘.
→ 구장 정보 조회

롯데 홈경기 예매는 어디서 해?
→ 예매 정보 검색

오늘 사직 경기 날씨 어때?
→ 경기 및 구장 확인
→ 날씨 조회

보크가 뭐야?
→ 야구 지식 검색

⇒ 즉, 모든 요청을 같은 순서로 처리하는 Workflow보다는 사용자의 질문을 해석하고 필요한 Tool을 선택해 실행하는 Agent 구조가 더 적합하다고 판단했습니다.

⇒ MVP에서는 이러한 Agent의 기본 동작을 검증하는 데 초점을 맞춰, 정형 데이터 조회와 문서 기반 RAG 검색을 하나의 대화 흐름으로 연결하는 것을 우선 목표로 잡았습니다.

2. 대상 사용자

KBO 도우미 Agent의 대상 사용자는 단순히 야구를 처음 접하는 사용자만으로 한정하지 않았습니다.

KBO에 관심은 있지만 필요한 정보를 직접 여러 사이트에서 찾아야 하는 사용자까지 포함하는 것을 목표로 잡았습니다.

대표 사용자는 아래와 같습니다.

• KBO를 처음 보기 시작한 야구 입문자
• 응원할 팀이나 관심 있는 팀의 정보를 찾고 싶은 사용자
• 특정 날짜나 기간의 경기 일정을 빠르게 확인하고 싶은 사용자
• 익숙하지 않은 구장의 위치, 시설, 이용 정보를 찾는 사용자
• 경기 예매 방법이나 구단별 예매 정보를 확인하고 싶은 사용자
• 야구 규칙이나 용어를 경기 상황과 함께 이해하고 싶은 사용자
• 경기 당일 날씨나 관람에 필요한 정보를 확인하고 싶은 사용자

⇒ 이 사용자들의 공통점은 하나의 정보만 찾는 것으로 끝나지 않는다는 점입니다. 예를 들어 경기 일정을 확인한 뒤에는 자연스럽게 다음 질문으로 이어질 수 있습니다.

오늘 롯데 경기 있어?
어디서 경기해?
사직야구장은 어디에 있어?
오늘 비는 안 와?
예매는 어디서 해?

즉, 각각의 질문은 독립적으로 보이지만 실제 사용 흐름에서는 하나의 맥락으로 이어집니다.

KBO 도우미 Agent는 이러한 연속적인 질문의 맥락을 유지하면서 필요한 정보를 단계적으로 연결해주는 사용자 경험을 주요 대상으로 합니다.

MVP에서는 이 중에서도 경기 일정, 구장 정보, 날씨, 예매 정보, 야구 지식처럼 비교적 명확하게 Tool과 RAG로 분리할 수 있는 사용자 요청부터 우선 지원합니다.

3. 해결하려는 문제

KBO와 관련된 정보는 한 곳에 모여 있지 않습니다.

경기 일정은 KBO나 구단 사이트에서 확인해야 하고, 구장 정보나 예매 방법은 다시 다른 페이지를 찾아야 하며, 야구 규칙이나 용어가 궁금하면 별도의 검색이 필요하고, 경기 당일 날씨까지 확인하려면 또 다른 서비스를 이용해야 하기에, 사용자 입장에서는 하나의 질문이 다음과 같이 여러 정보 탐색으로 이어지게 됩니다.

이번 주말 롯데 경기 있어? 
→ 
경기 일정 확인 
→ 
어느 구장에서 하는지 확인 
→ 
구장 위치와 이용 정보 확인 
→ 
예매 방법 확인 
→ 
경기 당일 날씨 확인

각 정보 자체를 찾는 것은 어렵지 않지만, 필요한 정보를 사용자가 직접 판단하고 여러 출처를 오가며 연결해야 한다는 점이 불편할 수가 있습니다.

특히 야구에 익숙하지 않은 사용자라면 무엇을 먼저 확인해야 하는지조차 알기 어려울 수 있기에 , 이번 프로젝트에서는 이 문제를 다음과 같이 정의했습니다.

1. 흩어진 KBO 정보를 하나의 대화 흐름에서 확인할 수 있어야 한다. 
2. 사용자가 원하는 정보에 따라 필요한 Tool이나 검색 방식을 자동으로 선택해야 한다. 
3. 경기 일정이나 날씨처럼 정확성이 중요한 데이터는 정형 데이터와 API를 통해 조회해야 한다. 
4. 예매 안내나 야구 규칙처럼 설명이 필요한 정보는 문서 기반 RAG를 통해 검색해야 한다. 
5. 이전 질문의 맥락을 활용해 사용자가 같은 조건을 반복해서 입력하지 않아도 되어야 한다.

⇒ 즉, KBO 도우미 Agent가 해결하려는 핵심 문제는 정보를 단순히 제공하는 것보다, 사용자의 질문과 현재 대화 맥락을 기준으로 필요한 정보를 찾아 연결하는 것입니다.

4. 서비스 설계 원칙

이번 프로젝트에서 가장 중요하게 잡은 기준은 모든 정보를 같은 방식으로 처리하지 않는 것입니다.

KBO 관련 정보는 성격이 서로 다릅니다.

경기 일정, 경기 시간, 구장 위치, 날씨처럼 정확한 값이 필요한 정보가 있는 반면, 예매 방법, 구장 이용 팁, 야구 규칙처럼 문서를 읽고 설명해야 하는 정보도 있습니다.

이 두 종류를 같은 방식으로 처리하면 정확도와 유지보수 측면에서 문제가 생길 수 있습니다.

그래서 다음과 같은 원칙을 기준으로 설계했습니다.

정확한 값이 필요한 정보
→ 정형 데이터 또는 외부 API를 통해 조회한다.

설명과 근거가 필요한 정보
→ 문서 검색과 RAG를 사용한다.

정보의 출처와 기준 시점을 가능한 범위에서 함께 제공한다.

정보가 없거나 오래된 경우
→ 추측하지 않고 한계를 명확하게 안내한다.

필수 조건이 부족한 경우
→ Tool을 실행하기 전에 사용자에게 필요한 정보를 확인한다.

처음부터 모든 기능을 구현하지 않고
→ 하나의 사용자 흐름을 완성한 뒤 단계적으로 확장한다.

예를 들어 경기 일정은 날짜와 팀 조건으로 정확하게 조회해야 하기 때문에 RAG보다 정형 데이터 조회가 적합합니다.

반면 다음과 같은 질문은 문서 기반 검색이 더 자연스럽습니다.

사직야구장 음식물 반입 가능해?

롯데 홈경기 예매는 어떻게 해?

보크가 뭐야?

⇒ 이처럼 이번 프로젝트에서는 Tool과 RAG를 기능이 아니라 데이터의 성격을 기준으로 분리했습니다.

⇒ 이 원칙은 이후 Tool 설계와 Agent routing 기준에도 그대로 적용합니다.

5. 왜 Agent가 필요한가

이 서비스를 단순 Workflow로 구현한다면 모든 요청이 같은 순서로 처리될 가능성이 높습니다.

경기 일정 조회
→ 구장 정보 조회
→ 예매 정보 조회
→ 날씨 조회
→ 야구 지식 검색

하지만 실제 사용자의 질문은 매번 다릅니다. 어떤 질문은 경기 일정만 조회하면 되고, 어떤 질문은 경기와 구장을 먼저 확인한 뒤 날씨까지 조회해야 합니다.

또 어떤 질문은 정형 데이터 조회 없이 RAG 검색만으로 해결할 수 있습니다.

오늘 롯데 경기 있어?
→ 경기 일정 Tool

오늘 사직 경기 날씨 어때?
→ 경기 일정 Tool
→ 구장 정보 확인
→ 날씨 Tool

롯데 홈경기 예매는 어디서 해?
→ 예매 정보 RAG

보크가 뭐야?
→ 야구 지식 RAG

다음 주말 서울에서 경기 보고 싶은데 뭐 있어?
→ 기간 기반 경기 일정 조회
→ 지역 조건 필터링

즉, 모든 요청에 동일한 실행 순서를 적용하는 방식은 불필요한 Tool 호출을 만들거나, 반대로 필요한 정보를 놓칠 수 있습니다.

KBO 도우미 Agent에서는 사용자의 질문을 먼저 해석한 뒤 현재 요청에 필요한 Tool만 선택해서 실행하도록 설계합니다.

사용자 요청
→ 의도와 조건 분석
→ 필요한 Tool 선택
→ Tool 실행
→ 결과 확인
→ 필요하면 추가 Tool 실행
→ 최종 응답 생성

여기서 Agent의 역할은 모든 정보를 직접 생성하는 것이 아닙니다.

어떤 정보를 어디에서 가져와야 하는지 판단하고, 필요한 실행 경로를 선택하는 것이 핵심입니다.

따라서 이번 프로젝트에서는 Agent를 단순한 LLM 응답기가 아니라 KBO 관련 여러 데이터 소스와 Tool을 연결하는 실행 주체로 정의했습니다.

6. 핵심 사용자 여정

KBO 도우미 Agent는 모든 사용자가 같은 순서로 서비스를 이용하도록 강제하지 않습니다.

사용자는 자신이 궁금한 지점부터 바로 질문할 수 있고, Agent는 현재 요청과 대화 맥락을 기준으로 필요한 정보를 이어서 제공합니다.

대표적인 사용자 흐름은 다음과 같습니다.

사용자 질문

→ 질문에서 필요한 조건 추출

→ 필요한 Tool 또는 RAG 선택

→ 데이터 조회 및 검색

→ 결과를 바탕으로 응답 생성

→ 다음 질문에서도 이전 대화 맥락 활용

예를 들어 사용자가 경기 일정을 먼저 확인한 경우에는 다음과 같이 자연스럽게 질문이 이어질 수 있습니다.

사용자
→ 다음 주 롯데 경기 있어?

Agent
→ 경기 일정 조회

사용자
→ 그중에 토요일 경기 어디서 해?

Agent
→ 이전 경기 조회 결과를 기준으로 구장 확인

사용자
→ 거기 비 와?

Agent
→ 선택된 경기와 구장을 기준으로 날씨 조회

사용자
→ 예매는 어디서 해?

Agent
→ 현재 팀과 경기 정보를 기준으로 예매 정보 검색

반대로 야구 규칙처럼 독립적인 질문은 별도의 경기 정보 조회 없이 바로 처리할 수 있습니다.

사용자
→ 보크가 뭐야?

Agent
→ 야구 지식 RAG 검색
→ 규칙 설명

즉, 핵심 사용자 여정은 정해진 메뉴를 순서대로 이동하는 방식보다 대화를 통해 필요한 정보를 하나씩 연결해가는 구조입니다.

MVP에서는 이 흐름을 안정적으로 구현하는 것을 우선하고, 이후 사용자 프로필이나 선호 팀, 좌석 추천, 교통 정보처럼 더 많은 맥락을 활용하는 방향으로 확장합니다.

7. MVP1 범위

MVP1의 목표는 KBO 도우미 Agent의 모든 기능을 완성하는 것이 아닙니다.

우선 사용자가 하나의 채팅 화면에서 질문을 입력했을 때, Agent가 요청을 해석하고 필요한 Tool을 선택해 실행한 뒤 그 결과를 다시 대화로 연결할 수 있는 기본 구조를 만드는 데 집중합니다.

MVP1에서 우선 검증할 흐름은 다음과 같습니다.

사용자 질문

→ 요청 분석

→ Tool routing

→ Tool 실행

→ 결과 반환

→ assistant 응답 생성

→ 다음 질문에서 이전 대화 맥락 활용

기능 범위는 다음과 같이 제한합니다.

로그인 사용자 기준 채팅

경기 일정 조회

구장 기본 정보 조회

경기/구장 기준 날씨 조회

예매 정보 RAG 검색

구장 이용 안내 RAG 검색

야구 규칙 및 용어 RAG 검색

conversation/message 저장

이전 대화 복원

Tool 실행 결과를 화면에 표시

선택한 경기 정보를 다음 질문의 context로 활용

여기서 중요한 것은 기능의 수를 늘리는 것이 아니라, Agent가 필요한 Tool을 선택하고 그 결과가 실제 서비스의 대화 흐름 안에서 안정적으로 이어지는지 확인하는 것입니다.

따라서 MVP1에서는 좌석 추천, 지도·교통, 사용자 취향 기반 추천처럼 추가 데이터와 복잡한 판단이 필요한 기능은 우선 제외합니다.

먼저 가장 기본적인 KBO 질문들을 안정적으로 처리할 수 있는 구조를 완성하고, 이후 기능을 하나씩 추가하는 방향으로 개발합니다.

8. MVP1 Tool 범위

MVP1에서는 KBO 관련 모든 기능을 하나의 Tool에 몰아넣지 않고, 데이터 성격과 책임에 따라 Tool을 분리했습니다.

현재 MVP1에서 사용하는 Tool은 다음과 같습니다.

Tool	역할	데이터 성격
find_kbo_game	팀, 날짜, 기간 조건으로 경기 일정 조회	정형 데이터
get_stadium_info	구장 기본 정보 조회	정형 데이터
get_weather_context	경기 또는 구장 기준 날씨 조회	외부 API
search_ticketing_guide	예매 절차와 관련 안내 검색	RAG
search_stadium_guide	구장 이용 안내, 반입, 시설 정보 검색	RAG
search_baseball_knowledge	야구 규칙, 용어, 플레이 설명 검색	RAG

Tool을 나눈 기준은 단순합니다.

정확한 값이 필요한 정보
→ 정형 데이터 또는 API Tool

설명과 근거가 필요한 정보
→ RAG Tool

예를 들어 경기 일정은 날짜와 팀 조건으로 정확하게 조회해야 하기 때문에 find_kbo_game을 사용합니다.

반면 다음과 같은 질문은 문서 기반 검색이 더 적합합니다.

사직구장 음식물 반입 가능해?
→ search_stadium_guide

롯데 홈경기 예매는 어떻게 해?
→ search_ticketing_guide

인필드 플라이가 뭐야?
→ search_baseball_knowledge

이렇게 Tool의 책임을 분리해두면 Agent는 사용자의 요청을 해석한 뒤, 필요한 Tool만 선택해서 실행할 수 있습니다.

또한 이후 기능을 확장하더라도 기존 Tool의 책임을 크게 변경하지 않고 새로운 Tool을 추가할 수 있습니다.

9. RAG 적용 기준

이번 프로젝트에서는 모든 정보를 RAG로 처리하지 않습니다.

RAG를 사용할지 여부는 데이터가 어떤 형태로 존재하고, 사용자가 어떤 방식의 답변을 필요로 하는지를 기준으로 판단합니다.

RAG가 적합하다고 판단한 기준은 다음과 같습니다.

단일 값 조회보다 문서의 내용을 이해해야 답할 수 있다.

사용자의 표현과 실제 문서의 표현이 다를 수 있어
의미 기반 검색이 필요하다.

답변과 함께 근거가 되는 문서와 출처를 제공할 필요가 있다.

팀, 구장, 문서 종류 등의 metadata를 활용해
검색 범위를 제한할 수 있다.

예를 들면 다음과 같은 질문입니다.

사직야구장 음식물 반입 가능해?

롯데 홈경기 예매는 어떻게 해?

인필드 플라이가 뭐야?

반대로 다음과 같이 정확한 값을 조회해야 하거나 실시간성이 중요한 정보에는 RAG를 사용하지 않습니다.

경기 일정과 경기 상태

구장 공식 명칭, 주소, 좌표

날씨와 예보 데이터

좌석 가격이나 잔여석처럼 실시간성이 중요한 정보

정해진 조건에 따라 계산할 수 있는 값

RAG는 다양한 문서를 자연어로 검색할 수 있다는 장점이 있지만, 모든 데이터를 조회하기 위한 수단은 아닙니다.

따라서 이번 프로젝트에서는 정확한 값은 정형 데이터와 외부 API로 조회하고, 문서의 내용을 검색하고 설명해야 하는 영역에 RAG를 사용하는 것을 기본 원칙으로 잡았습니다.

10. 단계별 확장 계획

이번 프로젝트는 처음부터 모든 기능을 구현하기보다, 동작하는 하나의 MVP를 먼저 완성하고 개발 이력을 남기면서 단계적으로 확장하는 방식으로 진행합니다.

전체적인 개발 방향은 다음과 같이 잡았습니다.

1. KBO 도우미 Agent 서비스/MVP 정의

2. 기본 채팅과 Tool 실행 구조 구축

3. 경기·구장 등 정형 데이터 구축

4. 외부 API 기반 Tool 연결

5. RAG 데이터 수집 및 검색 파이프라인 구축

6. Tool routing과 Agent 실행 흐름 개선

7. RAG 평가셋 구축 및 검색 품질 개선

8. 사용자 대화 Context와 상태 관리 확장

9. 응원 팀 및 사용자 취향 정보 활용

10. 좌석 추천 기능 확장

11. 지도·교통 API 기반 기능 확장

12. 전체 Agent 평가 및 서비스 품질 개선

각 단계를 한 번에 완성하기보다는 실제 구현 과정에서 발생한 문제와 선택한 해결 방법을 함께 기록할 예정입니다.

특히 RAG의 경우 데이터를 Vector DB에 넣는 것으로 끝내지 않고,

어떤 데이터를 수집했는가?

어떤 기준으로 문서를 Chunking 했는가?

Metadata는 어떻게 구성했는가?

실제 질문에서 원하는 문서가 검색되는가?

검색된 문서가 답변의 근거로 충분한가?

와 같은 부분까지 직접 검증해보려고 합니다.

이후 개발 글에서는 이러한 순서를 기준으로 기획부터 데이터 구축, RAG, Tool, Agent, Frontend/Backend 연결, 테스트와 개선까지의 개발 과정을 차례대로 기록해나갈 예정입니다.

11. 정리

이번 프로젝트의 핵심은 KBO 도우미 Agent를 LLM 하나가 모든 정보를 직접 답하는 챗봇으로 만들지 않는 것입니다.

경기 일정이나 구장, 날씨처럼 정확한 정보는 Tool을 통해 조회하고, 야구 규칙이나 예매·구장 안내처럼 문서의 내용과 근거가 필요한 정보는 RAG를 통해 검색합니다.

Agent는 사용자의 질문과 현재 대화 맥락을 해석한 뒤, 필요한 Tool이나 RAG를 선택하고 그 결과를 하나의 응답으로 연결하는 역할을 담당합니다.

전체적인 구조는 다음과 같습니다.

사용자 질문

→ 요청과 대화 Context 분석

→ 필요한 Tool / RAG 선택

→ 데이터 조회 및 검색

→ 결과를 바탕으로 응답 생성

→ 다음 질문에서 Context 활용

이번 글에서는 실제 개발을 시작하기에 앞서 서비스가 해결하려는 문제, Agent가 필요한 이유, Tool과 RAG의 역할, MVP 범위와 앞으로의 확장 방향을 먼저 정리했습니다.

이제부터는 이 명세를 기준점으로 삼아 실제 프로젝트를 하나씩 구현해나갈 예정입니다.

데이터 구축
→ RAG 구축
→ Tool 구현
→ Agent 연결
→ Frontend / Backend 개발
→ 테스트
→ 평가 및 개선

완성된 결과만 정리하기보다 각 단계에서 왜 이런 구조를 선택했는지, 구현하면서 어떤 문제가 발생했는지, 어떻게 해결하고 개선했는지까지 개발 이력으로 남기면서 MVP를 완성해나가려고 합니다.

이번 글은 그 개발 과정의 시작점입니다.