🤗 24. 본편 14: smolagents Agentic RAG — 파티 호스트 에이전트 실습

한 줄로 말하면, Agentic RAG은 “문서 검색 도구”를 에이전트에게 주면, 에이전트가 스스로 언제·무엇을 검색할지 결정한다는 것이다. 이번 본편 14는 HF Agents Course Unit 3의 Agentic RAG 유스케이스를 smolagents로 재현한다.

한 줄 결론

smolagents의 Tool로 RAG 검색기를 감싸면, 에이전트가 질문에 맞춰 자동으로 문서를 검색·요약·필터링하는 “지능형 정보 조수”를 20분에 만들 수 있다.

맥락 보완

지금까지 시리즈에서 다룬 핵심:

• 본편 01: 첫 CodeAgent 실행
• 본편 05: ReAct 도구 선택 흐름
• 본편 08: 웹검색 요약 에이전트

이번엔 검색 대상이 웹이 아니라 로컬 문서라는 점이 다르다. 에이전트가 도구로 “문서 검색”을 호출하면, RAG 파이프라인이 임베딩 →检索 → 컨텍스트 주입을 수행한다.

---

1. Agentic RAG이 일반 RAG과 다른 점

구분	일반 RAG	Agentic RAG
검색 시점	사용자 질문 → 1회 검색	에이전트가 필요시마다 다회 검색
검색 전략	고정 (similarity top-k)	에이전트가 쿼리 재작성, 필터 선택
답변 생성	검색 결과 → LLM 1회	에이전트가 검증 후 추가 검색 가능
도구 확장	불가	날씨 API, 계산기 등 다른 도구와 조합

flowchart LR
    U[사용자 질문] --> A[CodeAgent]
    A -->|도구 호출| R[RAG 검색 Tool]
    R -->|결과 없음| A2[쿼리 재작성]
    A2 -->|재검색| R
    R -->|결과 충분| S[답변 생성]
    A -->|다른 도구| W[날씨 API 등]
    W --> S
    S --> U

실무 포인트: 고객 지원, 내부 문서 QA, 컴플라이언스 조회 등 “정확한 출처가 필요한 질문”에 Agentic RAG이 강력하다.

---

2. 실습: 알프레드의 갈라 파티 호스트

HF Agents Course의 시나리오를 그대로 사용한다. 알프레드(에이전트)가 갈라 파티의 호스트 역할을 하며, 게스트 정보 문서에서 답을 찾아야 한다.

2-1. 사전 준비

# 패키지 설치
pip install smolagents langchain-community sentence-transformers faiss-cpu
 
# 환경변수 (OpenAI 사용 시)
export OPENAI_API_KEY="sk-..."
# 또는 HF 토큰
export HF_TOKEN="hf_..."

성공 판정: python -c "import smolagents; print(smolagents.__version__)" 에 에러가 없으면 OK.

2-2. 게스트 정보 데이터셋 준비

# guest_data.py
from datasets import load_dataset
 
# HF Agents Course에서 제공하는 게스트 데이터
guest_dataset = load_dataset("agents-course/unit3-invitees", split="train")
 
# 확인
print(f"게스트 수: {len(guest_dataset)}")
print(guest_dataset[0])

성공 판정: 게스트 수와 첫 번째 레코드가 정상 출력되면 OK.

2-3. RAG 검색 도구 만들기

# rag_tool.py
from smolagents import Tool
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_community.vectorstores import FAISS
from langchain.text_splitter import RecursiveCharacterTextSplitter
from datasets import load_dataset
 
 
class GuestInfoRetrieverTool(Tool):
    name = "guest_info_retriever"
    description = (
        "갈라 파티 게스트에 대한 정보를 검색합니다. "
        "게스트의 이름, 직업, 관심사, 초대 이유 등을 알 수 있습니다."
    )
    inputs = {
        "query": {
            "type": "string",
            "description": "게스트에 관한 질문 예: 'Tesla의 창립자는 누구인가?'"
        }
    }
    output_type = "string"
 
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        # 임베딩 모델 (경량)
        embeddings = HuggingFaceEmbeddings(
            model_name="all-MiniLM-L6-v2"
        )
        # 게스트 데이터를 텍스트로 변환
        guest_ds = load_dataset("agents-course/unit3-invitees", split="train")
        docs = []
        for guest in guest_ds:
            text = (
                f"이름: {guest.get('name', 'N/A')}. "
                f"직업: {guest.get('role', 'N/A')}. "
                f"관심사: {guest.get('interests', 'N/A')}. "
                f"초대 이유: {guest.get('invitation_reason', 'N/A')}. "
            )
            docs.append(text)
        # FAISS 인덱스 생성
        splitter = RecursiveCharacterTextSplitter(
            chunk_size=300, chunk_overlap=30
        )
        split_docs = splitter.create_documents(docs)
        self.db = FAISS.from_documents(split_docs, embeddings)
 
    def forward(self, query: str) -> str:
        results = self.db.similarity_search(query, k=3)
        if not results:
            return "해당 게스트에 대한 정보를 찾을 수 없습니다."
        return "\n---\n".join([doc.page_content for doc in results])

2-4. 에이전트 실행

# alfred_agent.py
from smolagents import CodeAgent, HfApiModel, OpenAIServerModel
from rag_tool import GuestInfoRetrieverTool
 
# 모델 선택 (둘 중 하나)
model = HfApiModel("Qwen/Qwen2.5-72B-Instruct")
# model = OpenAIServerModel("gpt-4o-mini")
 
# 도구 인스턴스
guest_tool = GuestInfoRetrieverTool()
 
# 에이전트 생성
alfred = CodeAgent(
    tools=[guest_tool],
    model=model,
    max_steps=5,
    name="alfred",
    description="갈라 파티 호스트 알프레드. 게스트 정보를 검색해 답변합니다."
)
 
# 질문!
result = alfred.run("Tesla와 관련된 게스트가 누구인가요?")
print(result)

성공 판정: Tesla 창립자/관련 인물 정보가 포함된 응답이 나오면 OK.

2-5. 금지 주제 가드레일 추가

# alfred_guarded.py
from smolagents import CodeAgent, HfApiModel, Tool
from rag_tool import GuestInfoRetrieverTool
 
 
class TopicGuardTool(Tool):
    """정치·종교 주제를 차단하는 가드레일 도구"""
    name = "topic_guard"
    description = "질문이 금지된 주제(정치, 종교)인지 확인합니다."
    inputs = {
        "question": {
            "type": "string",
            "description": "확인할 질문"
        }
    }
    output_type = "string"
 
    FORBIDDEN = ["정치", "정당", "선거", "종교", "신앙", "교리"]
 
    def forward(self, question: str) -> str:
        if any(kw in question for kw in self.FORBIDDEN):
            return "BLOCKED: 갈라 파티에서는 정치와 종교 주제를 피해주세요."
        return "OK: 안전한 주제입니다."
 
 
guest_tool = GuestInfoRetrieverTool()
guard_tool = TopicGuardTool()
 
alfred = CodeAgent(
    tools=[guest_tool, guard_tool],
    model=HfApiModel("Qwen/Qwen2.5-72B-Instruct"),
    max_steps=6,
)
 
# 정상 질문
print("=== 정상 질문 ===")
print(alfred.run("파티에서 가장 과학에 관심 있는 게스트는?"))
 
# 금지 질문
print("\n=== 금지 질문 ===")
print(alfred.run("어떤 게스트가 보수 정당을 지지하나요?"))

성공 판정:

• 정상 질문 → 게스트 관심사 기반 답변 출력
• 금지 질문 → “BLOCKED” 또는 거부 메시지 출력

---

3. Agentic RAG 흐름 도식

sequenceDiagram
    participant U as 사용자
    participant A as Alfred (CodeAgent)
    participant G as TopicGuard
    participant R as RAG 검색기
    participant DB as FAISS 인덱스

    U->>A: "Tesla 관련 게스트 누구?"
    A->>G: 주제 안전 확인
    G-->>A: "OK"
    A->>R: guest_info_retriever("Tesla 관련")
    R->>DB: similarity_search("Tesla")
    DB-->>R: 상위 3개 문서
    R-->>A: 게스트 정보 텍스트
    A->>A: 컨텍스트 기반 답변 생성
    A-->>U: "일론 머스크, Tesla CEO..."

---

4. 실무 적용 포인트

시나리오	적용 방법
고객 지원	제품 매뉴얼·FAQ를 FAISS에 색인 → 에이전트가 담당자 배정 + 답변
내부 위키	사내 문서를 임베딩 → “휴가 정책이 어떻게 되나요?” 질문에 자동 답변
컴플라이언스	규정 문서 검색 + 가드레일로 승인 필요 항목 차단
리서치	논문/보고서를 RAG로 검색 + 웹검색 도구와 조합

핵심 차이: 일반 RAG은 1회 검색으로 끝나지만, Agentic RAG은 에이전트가 “결과가 불충분하면 다시 검색”을 스스로 결정한다. 본편 11에서 다룬 planning_interval과 결합하면 더 정교한 검색 전략이 가능하다.

---

5. 마무리

이번 본편에서 다룬 것:

1. Agentic RAG = 에이전트 + RAG 검색 도구 + 자율 판단
2. smolagents.Tool로 RAG 검색기를 감싸면 즉시 도구화
3. TopicGuard처럼 가드레일도 도구로 구현 가능
4. FAISS + sentence-transformers로 로컬 검색 구축

다음 예고

실습편 07에서는 이번 Agentic RAG을 바탕으로 사내 문서 QA 미니 프로젝트를 핸즈온으로 진행한다.

참고 링크

• HF Agents Course — Unit 3 Agentic RAG
• smolagents 공식 문서
• 이전 편: 본편 13 — 에이전트 오케스트레이션과 실행 제어

---

이 글은 생성형 AI(GPT-5.3)의 도움을 받아 작성되었습니다. 내용 검토 후 게시합니다.