blog.ruahverce Vol · 2026 · Issue 012 — A field log of LLMs, RAG, and ML systems

Series · Folio

RAG Agent · Harness 제대로 만들기

10 parts

상태 루프부터 안전한 운영 하네스까지 이어지는 초·중급 10편

Agent 상태 루프에서 도구 계약, query routing, planning, 근거 판정, memory, durable execution, tracing, security, trajectory evaluation로 이어지는 RAG Agent Harness 로드맵
대상
검색 pipeline을 만든 뒤 도구·메모리·복구·평가를 갖춘 RAG Agent로 확장하려는 개발자
읽고 나면
Agent 상태 머신, tool contract, routing, planning, corrective retrieval, memory, durable execution, tracing, authorization, trajectory evaluation을 하나의 운영 가능한 harness로 연결할 수 있음
추천 진입
01편 → 02편 → 05편 → 07편 → 10편
№001 rag-agent-harness-foundations · 01

RAG Agent는 무엇인가: Workflow에서 상태 기반 제어 루프로 (1/10)

고정 RAG pipeline을 observe·decide·act·evaluate 상태 루프로 바꾸고, LLM과 deterministic harness의 책임을 분리해 종료 조건·예산·불변식·실패 상태를 가진 첫 RAG Agent를 Python으로 구현합니다.

#RAG #Agent #AgentHarness #StateMachine
사용자 목표가 상태 저장소, LLM 행동 제안, 정책 게이트, 도구 실행, 관찰과 근거 판정을 순환한 뒤 답변 또는 실패로 끝나는 RAG Agent Harness
№002 rag-agent-harness-foundations · 02

Tool Calling 설계: JSON Schema와 안전한 실행 계약 (2/10)

LLM의 tool call을 실제 API 실행과 분리하고 JSON Schema 입력 계약, 의미·권한 검증, 구조화된 결과와 오류 envelope, side-effect·idempotency·version metadata를 갖춘 안전한 tool registry를 설계합니다.

#Agent #ToolCalling #JSONSchema #MCP
LLM의 tool proposal이 JSON Schema, 의미와 권한 gate, executor, output validator를 통과해 provenance가 있는 observation으로 바뀌는 도구 실행 계약
№003 rag-agent-harness-foundations · 03

Query Router와 Adaptive RAG: 질문마다 다른 검색 경로 (3/10)

질문의 지식 필요성·신선도·식별자·복잡도·모호성·위험도를 판별해 no retrieval, direct lookup, single·iterative search, clarification을 선택하고 routing regret로 검증하는 RAG router를 설계합니다.

#RAG #QueryRouting #AdaptiveRAG #Agent
질문 분석 결과에 따라 검색 없음, 정확 조회, 단일 검색, 반복 검색, 사용자 확인 경로로 분기하고 confidence와 예산 gate가 경로를 통제하는 Adaptive RAG router
№004 rag-agent-harness-foundations · 04

Agent Planning 패턴: ReAct·Plan/Execute·ReWOO·Tree Search (4/10)

ReAct, plan-execute, ReWOO, tree search를 비용과 적응성으로 비교하고 dependency·success criteria·failure policy를 가진 plan DAG와 replan trigger·stop rule을 설계합니다.

#Agent #Planning #ReAct #ReWOO
즉시 관찰하며 행동하는 ReAct, 계획 후 실행하는 plan-execute, dependency DAG를 만드는 ReWOO, 여러 경로를 탐색하는 tree search를 비용과 불확실성에 따라 비교한 Agent planning 지도
№005 rag-agent-harness-foundations · 05

근거 충분성 판정: Self-RAG·CRAG·FLARE로 재검색하기 (5/10)

질문을 evidence requirement로 분해하고 relevance·coverage·support·contradiction·freshness를 판정해 Self-RAG·CRAG·FLARE식 재검색·확인 질문·안전 종료를 bounded loop로 구현합니다.

#RAG #SelfRAG #CRAG #Evidence
질문의 evidence requirement와 source span ledger를 비교해 충분, 부분 충족, 무관, 모순, 오래됨으로 판정하고 query rewrite·다른 source·확인 질문·안전 종료로 교정하는 RAG loop
№006 rag-agent-harness-foundations · 06

Agent Memory 설계: Working·Episodic·Semantic·Procedural (6/10)

Agent state·context·memory·corpus를 구분하고 working·episodic·semantic·procedural memory의 write·retrieve·update·forget lifecycle을 provenance·유효 기간·ACL·민감도로 설계합니다.

#Agent #Memory #RAG #MemGPT
현재 run의 working state, 과거 사건의 episodic memory, 검증된 사실의 semantic memory, versioned procedure를 분리하고 쓰기·검색·통합·갱신·망각하는 Agent memory architecture
№007 rag-agent-harness-foundations · 07

Durable Agent Execution: Checkpoint·Retry·Idempotency (7/10)

프로세스·네트워크 장애 뒤에도 RAG Agent를 안전하게 재개하도록 checkpoint·replay·idempotency·timeout·retry·cancellation·compensation을 설계합니다.

#Agent #DurableExecution #Idempotency #Retry
Agent 실행을 event log와 checkpoint에서 replay하고 idempotency receipt로 외부 부작용 중복을 막으며 timeout·retry·cancel·compensation으로 복구하는 durable execution 구조
№008 rag-agent-harness-foundations · 08

Agent Observability: Trace·Span·Event로 실패 재현하기 (8/10)

RAG Agent의 router·retrieval·model·tool·checkpoint를 trace·span·event·artifact로 연결하고 version·비용·latency·error를 기록해 최초 실패 지점을 재현합니다.

#Agent #Observability #OpenTelemetry #Tracing
Agent run을 router·retrieval·model·tool·checkpoint span tree로 연결하고 state event, manifest, metric, redaction으로 실패 원인과 비용을 재현하는 관측성 구조
№009 rag-agent-harness-foundations · 09

RAG Agent 보안: Prompt Injection·Capability·실행 직전 승인 (9/10)

검색 문서와 tool result를 untrusted data로 격리하고 provenance·taint·최소 capability·human approval·commit-time authorization으로 Agent 부작용과 정보 유출을 막습니다.

#Agent #Security #PromptInjection #Authorization
Untrusted 문서와 tool result에 taint를 유지하고 capability, action-bound approval, commit-time authorization을 통과한 요청만 실행하는 RAG Agent 보안 구조
№010 rag-agent-harness-foundations · 10

Production RAG Agent Harness: Trajectory 평가와 Release Gate (10/10)

State·tool·router·evidence·memory·durable runtime·trace·security를 production harness로 통합하고 final state와 trajectory의 품질·비용·보안 gate로 안전하게 릴리스합니다.

#Agent #AgentHarness #Evaluation #Trajectory
RAG Agent 실행 모듈을 typed state·policy로 감싸고 durable runtime·trace·trajectory evaluation·release gate로 검증하는 production harness 구조