Router 기반 Agent에서 Tool-calling Agent로
Router 기반 Agent에서 Tool-calling Agent로
EVA의 기능과 사용자 요청이 늘어나면서, 각각의 요청을 어떤 사전 정의 경로에서 처리할지 결정하는 일이 점점 어려워지고 있습니다. EVA v3.1에서는 Chat 아키텍처를 Router 기반 Agent에서 Tool-calling Agent로 변경했습니다.
기존 아키텍처는 요청을 분류한 뒤 사전 정의된 처리 경로로 전달했습니다. 새로운 아키텍처에서는 LLM에 사용 가능한 기능 목록을 제공하고, 요청을 처리하는 데 필요한 Tool을 선택한 뒤 실행 결과를 바탕으로 응답하도록 합니다.
1. 왜 아키텍처를 변경했는가
Router 기반 아키텍처는 요청 유형별 처리 경로가 명확하다는 장점이 있습니다. 하지만 기능과 질문 유형이 늘어나면서 다음과 같은 한계가 드러났습니다.
- 새로운 기능을 추가하려면 Router와 연결된 Graph 분기를 함께 수정해야 하는 경우가 많습니다.
- Prompt와 코드에 포함된 매뉴얼 내용을 업데이트하고 관리하기 어렵습니다.
- 현재 Runtime 설정에 대한 질문과 일반적인 기능 설명 질문이 같은 Q&A 흐름에 섞일 수 있습니다.
2. Router 기반 Agent와 Tool-calling Agent
두 아키텍처는 서로 다른 질문에 답합니다.
| 아키텍처 | 핵심 질문 | 일반적인 흐름 |
|---|---|---|
| Router 기반 Agent | “이 요청을 어느 경로에서 처리할 것인가?” | 요청 → 분류 → 사전 정의된 Node 또는 Subgraph → 응답 |
| Tool-calling Agent | “이 요청을 처리하려면 어떤 기능이 필요한가?” | 요청 → 의도 분석 → 필요한 Tool 선택 → Tool 실행 → 응답 |
Router 기반 설계에서는 코드가 사용할 수 있는 분기를 정의하고 그중 하나를 선택합니다. Tool-calling 설계에서는 LLM이 사용 가능한 Tool Schema를 전달받고, 요청에 필요한 Tool을 판단합니다.
이 차이는 단순히 Router를 LLM으로 교체하는 것에 그치지 않습니다. 처리 결정을 어디에서 내리고, 기능을 시스템에 어떻게 추가할지까지 바꾸는 구조적 변화입니다.
Router 기반 Agent
사용자 요청
→ 요청 유형 분류
→ 사전 정의된 하나의 경로 선택
→ Node 또는 Subgraph 실행
→ 응답
Tool-calling Agent
사용자 요청
→ 의도 분석
→ 필요한 Tool 선택
→ Tool 실행
→ 실행 결과 확인
→ 응답
3. Prepare–Decide–Tool–Compose–Finalize 흐름
새로운 Agent는 다음 다섯 가지 개념적 단계로 동작합니다.
사용자 요청
↓
Prepare
↓
Decide
↓
Tool
↓
Compose
↓
Finalize
| 단계 | 역할 |
|---|---|
Prepare | 언어, 대화 이력, 현재 설정 등 요청에 필요한 정보를 준비합니다. |
Decide | 요청 의도를 분석하고 필요한 Tool을 선택합니다. |
Tool | 선택된 Tool을 실행합니다. |
Compose | Tool 실행 결과를 자연스러운 답변으로 정리합니다. |
Finalize | 결과를 최종 응답 형식으로 변환합니다. |
예를 들어 “AI 추론 간격을 30초로 변경해줘.”라는 요청은 다음과 같이 처리할 수 있습니다.
Decide
→ set_detection_interval 선택
→ 입력값 30초 검증
→ 설정 변경
→ 실행 결과 반환
→ 최종 응답 생성
모든 요청이 각 단계를 별도의 작업으로 수행해야 하는 것은 아닙니다. 중요한 점은 Tool 선택, 실행, 응답 생성이 일관된 생명주기 안에서 명시적으로 처리된다는 것입니다.
4. 매뉴얼 Q&A를 Prompt에서 Knowledge RAG로
아키텍처 변 경은 EVA의 매뉴얼과 기능 관련 질문을 처리하는 방식에도 영향을 줍니다.
Prompt 기반 Chat
기존 설계에서는 요청 유형에 따라 Guide를 선택하고, 답변을 생성하기 전에 해당 내용을 Prompt에 포함했습니다.
사용자 질문
→ 질문 분류
→ 관련 Guide 선택
→ Guide를 Prompt에 포함
→ LLM 응답 생성
예를 들어 객체 탐지 민감도에 대한 질문이 용어나 App 기능 질문으로 분류되면, 코드가 TERM_GUIDE 또는 APP_GUIDE를 선택해 Prompt에 포함하는 방식입니다.
이 방식에는 다음과 같은 한계가 있습니다.
- 별도의 문서 검색 단계가 없습니다.
- Prompt에 포함된 Guide 내용의 범위 안에서만 답변합니다.
- Guide가 변경되면 Prompt 또는 코드를 수정해야 할 수 있습 니다.
- 코드가 질문에 맞는 Guide를 선택해야 합니다.
Tool-calling 기반 Chat
새로운 설계에서는 매뉴얼 질문이 answer_eva_question을 선택합니다. 이 Tool은 질문을 임베딩하고 Knowledge 저장소를 검색한 뒤, 관련 페이지를 답변 모델의 Context로 전달합니다.
사용자 질문
→ answer_eva_question 선택
→ 질문 임베딩 생성
→ Qdrant에서 관련 페이지 검색
→ 검색된 페이지 내용을 Context로 전달
→ 답변 생성
예를 들어 “EVA에서 탐지 시나리오는 어떻게 설정하나요?”라는 질문이 들어오면, 시스템은 관련 설정 절차가 포함된 매뉴얼 페이지를 검색하고 그 페이지를 근거로 답변을 생성합니다.
이제 매뉴얼은 독립적으로 관리되는 Knowledge 소스가 됩니다. 관련된 페이지만 검색할 수 있고, 검색 결과에 파일명과 페이지 번호 같은 Metadata를 포함할 수도 있습니다. 매뉴얼이 변경되면 Chat Prompt 자체를 수정하는 대신 문서를 다시 Ingest하여 반영할 수 있습니다.
다만 검색 품질이 답변 품질에 직접 영향을 준다는 새로운 책임이 생깁니다. Knowledge Pipeline과 평가 체계가 Chat 시스템의 중요한 구성 요소가 됩니다.
5. 페이지 단위 Knowledge Ingest
RAG 검색을 사용하려면 매뉴얼을 사용자가 질문하기 전에 검색 가능한 형태로 저장해야 합니다. 현재 Ingest 흐름은 다음과 같습니다.
PDF 또는 Markdown
↓
본문, 표, 그림 정보 추출
↓
페이지 단위 콘텐츠 구성
↓
Embedding 생성
↓
페이지 벡터를 Qdrant에 저장
질문 시에는 다음 흐름이 실행됩니다.
사용자 질문
→ Query Embedding 생성
→ Qdrant 유사도 검색
→ 관련 페이지 반환
→ 답변 Context로 사용
왜 페이지 단위로 검색하는가
한 페이지에는 함께 읽어야 의미가 생기는 정보가 포함되어 있는 경우가 많습니다. 예를 들어 한 페이지에 다음 내용이 함께 있을 수 있습니다.
- 상단의 기능 설명
- 중단의 설정 화면 이미지
- 하단의 주의사항
페이지를 너무 작은 문장 단위 Chunk로 분리하면 이와 같은 관련 정보가 서로 다른 검색 결과로 나뉠 수 있습니다. 페이지 단위 검색은 설명, 설정 절차, 표, 그림 설명, 주의사항 사이의 관계를 유지합니다.
페이지 단위 검색의 목적은 단순히 Chunk를 크게 만드는 것이 아닙니다. 한 페이지 안에서 함께 설명되는 정보의 관계를 보존하는 것입니다.
현재 구조에서는 페이지 단위로 관련 자료를 찾은 뒤, 페이지 텍스트와 Metadata를 ToolResult에 포함해 답변 모델에 전달합니다. 이렇게 하면 설명, 설정 절차, 표, 주의사항 사이의 관계를 유지하면서 Knowledge 검색과 답변 생성의 책임을 분리할 수 있습니다.
고객 환경에 맞는 Knowledge 확장
Knowledge에는 EVA 매뉴얼뿐만 아니라 고객 환경에 따라 필요한 문서도 함께 포함할 수 있습니다. 고객사별 운영 매뉴얼, 설비 기준서, 작업 절차서, 안전환경규정집 등을 Ingest하면, 일반적인 기능 설명을 넘어 해당 현장의 기준과 규정에 근거한 답변을 제공할 수 있습니다.
예를 들어 안전환경규정집을 Knowledge에 추가하면, 탐지 알람이 발생했을 때 단순히 알람 사실만 확인하는 데 그치지 않고 해당 알람과 관련된 안전·환경 규정, 현장 대응 절차, 후속 보고 기준을 질의할 수 있습니다. 고객별 문서를 별도의 Knowledge 소스로 관리하면 현장마다 다른 규정과 운영 기준을 반영하면서도 동일한 Tool-calling 흐름으로 검색하고 답변할 수 있습니다.
6. 전체 아키텍처
전체 시스템은 오프라인 Knowledge Ingest 흐름과 온라인 Inference 흐름으로 구성됩니다.
오프라인 Knowledge 흐름
PDF / Markdown
→ 본문, 표, 그림 정보 추출
→ 페이지 단위 텍스트 구성
→ 페이지 Embedding 생성
→ 벡터를 Qdrant에 저장
온라인 Inference 흐름
사용자 요청
→ 대화 이력과 현재 설정 준비
→ 사용 가능한 Tool Registry를 LLM에 Bind
→ LLM이 필요한 Tool call 생성
→ 선택된 Tool 실행
→ ToolResult 반환
→ 필요할 때 자연어 답변으로 Compose
→ 응답 Finalize
Tool-calling 기반 Chat
Tool Registry에는 다음과 같은 종류의 기능이 포함될 수 있습니다.
- 애플리케이션 상태를 변경하는 Action Tool
- Knowledge 기반 답변을 제공하는 Q&A Tool
- 일반적인 대화를 처리하는 Conversation Tool
- Runtime 정보나 시스템 상태를 조회하는 Meta Tool
answer_eva_question이 선택되면 Query Embedding 생성과 Qdrant 검색 흐름이 시작됩니다. 검색된 페이지 내용은 ToolResult로 반환되고, 이후 Compose 모델이 최종 답변을 만드는 데 사용할 수 있습니다.
이 구조는 각 구성 요소의 책임도 분리합니다. Tool은 구체적인 작업을 수행하고, Knowledge 검색은 근거를 제공하며, LLM은 최종 응답을 생성합니다.
7. 구조 변경으로 얻는 효과
Tool-calling이 주는 실질적인 이점
Tool-calling의 장점은 단순히 LLM이 함수를 호출할 수 있다는 데 있지 않습니다. 요청 해석, 실제 작업, Knowledge 검색, 최종 답변의 책임을 분리해 각 단계가 명확한 역할을 수행하도록 한다는 점이 핵심입니다.
- 기능 확장: 새로운 기능을 Router 분기와 Graph 경로에 일일이 연결하는 대신 Tool과 Schema를 Registry에 추가할 수 있습니다.
- 최신 정보 사용: 매뉴얼과 Runtime 상태를 Prompt에 고정하지 않고, 필요한 시점에 Knowledge 또는 상태 조회 Tool에서 가져올 수 있습니다.
- 안전한 실행: Action Tool마다 입력 검증과 권한, 실행 조건을 둘 수 있어 자연어 해석과 실제 상태 변경을 분리할 수 있습니다.
- 관찰과 개선: 어떤 Tool을 선택했는지, 어떤 입력을 전달했는지, 검색 결과가 무엇이었는지를 단계별로 기록하고 평가할 수 있습니다.
평가한 요청 기준으로는 기존 Router 기반 흐름보다 평균 응답 속도가 약 30% 빨라졌습니다. 불필요한 분류 단계를 줄이고 요청에 필요한 Tool을 직접 실행한 결과입니다.
기능 확장 용이성
기존 아키텍처에서는 새로운 기능을 추가할 때 Router와 Graph 분기를 함께 수정해야 할 수 있었습니다. 새로운 아키텍처에서는 기능을 Tool로 구현하고 Schema와 함께 Registry에 등록할 수 있습니다.
기존
→ Router와 Graph 분기 수정
변경 후
→ Tool 구현
→ Tool Schema 등록
독립적인 Knowledge 관리
매뉴얼 내용을 더 이상 Prompt나 애플리케이션 코드 안에서 관리할 필요가 없습니다. 매뉴얼을 Knowledge 문서로 관리하고 Ingest Pipeline을 통해 반영할 수 있습니다.
요청 목적의 명확한 분리
같은 주제라도 사용자의 요청 목적에 따라 서로 다른 Backend에 연결할 수 있습니다.
현재 Runtime 값
→ Runtime 설정 조회
기능 설명
→ Knowledge 검색
설정 변경
→ Action Tool
응답 속도 개선과 함께 기능 수가 늘어날 때 처리 구조를 더 유연하게 확장할 수 있게 되었습니다.
8. 새롭게 고려해야 할 운영 항목
구조가 유연해진 만큼 모니터링하고 평가해야 할 영역도 새롭게 생겼습니다.
| 영역 | 확인해야 할 질문 |
|---|---|
| Tool 선택 | Agent가 요청에 맞는 Tool을 선택하는가? |
| Tool Schema | LLM이 Tool의 목적과 입력값을 정확히 이해하는가? |
| Action 안전성 | 어떤 상태 변경 Action을 자동으로 실행할 수 있는가? |
| RAG 검색 | 핵심 정보를 놓치지 않고 관련 페이지를 검색하는가? |
| 페이지 단위 검색 | 하나의 페이지에 서로 무관한 주제가 너무 많이 섞여 있지 않은가? |
| 문서 관리 | 버전과 중복 Qdrant Point를 어떻게 관리하는가? |
| Ingest | 서비스 설정과 Ingest Script가 일치하는가? |
| 평가 | Tool 선택, Action 실행, RAG 답변을 어떻게 테스트하는가? |
특히 성공적인 Tool-calling 시스템을 만들기 위해서는 최종 답변의 문장만 평가해서는 부족합니다. 올바른 Tool을 선택했는지, 입력값이 유효했는지, Action이 안전했는지, 답변이 적절한 Knowledge 페이지에 근거했는지도 함께 확인해야 합니다.
마무리
Router 기반 Agent에서 Tool-calling Agent로의 전환은 단순히 Chat 컴포넌트 하나를 교체한 것이 아닙니다. 코드가 요청의 처리 경로를 결정하던 구조에서, LLM이 요청을 처리하는 데 필요한 기능과 Knowledge를 선택하는 구조로 바꾼 것입니다.
이 구조를 통해 EVA는 매뉴얼을 독립적인 Knowledge 소스로 관리하고, Registry에 Tool을 추가하는 방식으로 기능을 확장할 수 있게 되었습니다. 동시에 Tool Schema, Action 안전성, 검색 품질, 문서 버전 관리, End-to-end 평가가 안정적인 Agent 운영을 위한 핵심 요소가 되었습니다.
