RAG만으로는 왜 부족한가?

시나리오: "CNC-001 알람 E-042, 관련 부품 재고 있어?"

[RAG-only 시스템]
  질문 -> 벡터 검색 -> 매뉴얼 문서 반환 -> LLM 답변
  결과: "E-042는 스핀들 과열입니다. 냉각수를 확인하세요."

  문제: "관련 부품 재고" 에 대한 답이 없다!
  왜? -> RAG는 문서만 검색하지, DB를 조회하지 않으니까.

[Agent 시스템]
  질문 -> Agent 분석 -> "3가지 작업이 필요하군"
    1) RAG: 매뉴얼에서 E-042 정보 검색
    2) KG: CNC-001 관련 부품 목록 조회
    3) 종합: 부품 정보 + 매뉴얼 정보를 합쳐 답변

  결과: "E-042는 스핀들 과열입니다.
         CNC-001의 냉각수펌프(CP-007) 점검이 필요합니다.
         CP-007은 CL-003 냉각시스템에 연결되어 있습니다."

---

Agent 중심 아키텍처의 핵심

                    ┌──────────────┐
                    │   Agent      │
                    │  (두뇌)      │
                    │              │
                    │  "이 질문은  │
                    │   RAG+KG가  │
                    │   필요하군"  │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────▼────┐ ┌────▼─────┐ ┌────▼──────┐
        │ RAG Tool │ │ KG Tool  │ │ Calc Tool │
        │ (팔)     │ │ (팔)     │ │ (팔)      │
        └──────────┘ └──────────┘ └───────────┘

Agent = 두뇌 (어떤 도구를 쓸지 결정) Tools = 팔 (실제 작업 수행)

핵심: Agent는 도구를 직접 구현하지 않는다. 도구를 선택하고 조합한다.

---

좋은 Tool 설계의 3원칙

1. 하나의 도구 = 하나의 책임

# [나쁜 예] 하나에 다 넣기
@tool
def do_everything(query: str) -> str:
    # RAG도 하고 KG도 하고 계산도 하고...
    ...

# [좋은 예] 책임 분리
@tool
def search_documents(query: str) -> str:
    """매뉴얼에서 관련 문서를 검색합니다"""
    ...

@tool
def query_knowledge_graph(entity_id: str) -> str:
    """설비의 관련 노드를 Knowledge Graph에서 탐색합니다"""
    ...

2. 명확한 설명 = Agent의 판단력

# [나쁜 예] 설명이 부실
@tool
def search(q: str) -> str:
    """검색합니다"""  # Agent: "뭘 검색하라는 거지?"

# [좋은 예] Agent가 판단할 수 있는 설명
@tool
def search_documents(query: str) -> str:
    """설비 매뉴얼, 안전 규정, 작업 절차서에서
    관련 내용을 검색합니다.
    설비 고장, 알람 대응, 안전 수칙 질문에 사용하세요."""

3. 구조화된 입출력

# [나쁜 예] 자유 형식
@tool
def kg_query(text: str) -> str:
    ...

# [좋은 예] 구조화
@tool
def query_knowledge_graph(
    entity_id: str,
    relation_type: str = "all",
    depth: int = 2
) -> str:
    """Knowledge Graph에서 엔티티의 관련 노드를 탐색합니다.

    Args:
        entity_id: 설비 ID (예: 'CNC-001')
        relation_type: 관계 유형 ('PART_OF', 'HAS_SENSOR', 'all')
        depth: 탐색 깊이 (기본 2)
    """
    ...

---

오늘 만들 도구 4개

도구	역할	사용 시점
search_documents	매뉴얼/규정 검색	절차, 규정, 방법 질문
query_knowledge_graph	설비 관계 탐색	관계, 영향, 연결 질문
calculate	수치 계산	계산, 변환 질문
get_equipment_info	설비 정보 조회	특정 설비 상태 질문