환각을 일으키지 않는 AI 에이전트 구축하기: 구조화된 워크플로우, 가드레일(Guardrails), 그리고 단계별 평가

취약한 프롬프트 체인(Prompt chains)을 타입화된 스키마(Typed schemas), 검증 게이트(Validation gates), 그리고 모든 단계에서의 평가로 어떻게 교체했는가 — 작업 성공률 94% vs 기준점 60%

프롬프트 체인의 함정 (The Prompt Chain Trap)

2024년 1월. 우리는 12개의 프롬프트가 사슬처럼 연결된 "리서치 에이전트(Research agent)"를 구축했습니다:

1. 질문 분해(Decompose question) → 2. 검색 계획(Search planning) → 3. 검색 실행(Execute searches) → 4. 사실 추출(Extract facts) → 5. 종합(Synthesize) → 6. 사실 확인(Fact-check) → 7. 형식 지정(Format) → ...

이 방식은 60%의 확률로만 작동했습니다. 나머지 40%의 경우에는 다음과 같은 문제가 발생했습니다:

• 3단계에서 잘못된 형식의 JSON이 반환됨 → 4단계에서 충돌 발생
• 5단계에서 인용 문헌을 환각(Hallucinate)함 → 6단계에서 이를 놓침
• 7단계에서 잘못된 형식을 출력함 → 후속 소비자(Downstream consumer)가 실패함
• 어느 단계에서 실패했는지에 대한 가시성(Visibility) 부재

디버깅을 하려면 12개의 LLM 호출에 해당하는 로그를 읽어야 했습니다. 단계를 하나 추가하면 다른 세 개의 단계가 망가졌습니다.

전환: 타입화된 워크플로우로서의 에이전트 (The Shift: Agents as Typed Workflows)

우리는 **프롬프트 체인(Prompt chains)**에서 다음과 같은 기능을 갖춘 **구조화된 워크플로우(Structured workflows)**로 전환했습니다:

• 모든 단계의 입출력을 위한 Pydantic 스키마(Pydantic schemas)
• 검증 및 자동 재시도(Auto-retry)를 수행하는 가드레일(Guardrails)
• (암시적 체이닝이 아닌) 명시적 상태 머신(Explicit state machine)
• (단순히 엔드 투 엔드가 아닌) 단계별 평가 하네스(Evaluation harness per step)

┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  Decompose  │──▶│   Search    │──▶│  Extract    │──▶│ Synthesize  │
│  Question   │   │   Planning  │   │   Facts     │   │  Answer     │
...

핵심 추상화 (Core Abstractions)

# agent_eval/schemas.py
from pydantic import BaseModel, Field
from typing import Literal, Any
...

에이전트 루프 (The Agent Loop)

# agent_eval/agent.py
class StructuredAgent:
    def __init__(self, steps: list[AgentStep], guardrails: list[Guardrail], evaluator: Evaluator):
...

실제로 차단하는 가드레일 (Guardrails That Actually Block)

# agent_eval/guardrails.py
from abc import ABC, abstractmethod

...

단계별 평가 (Per-Step Evaluation) (단순히 엔드 투 엔드가 아닌)

# agent_eval/evaluation.py
class StepEvaluator:
    def __init__(self, judges: list[Judge]):
...

자동 재시도를 포함한 구조화된 출력 추출 (Structured Output Extraction with Auto-Retry)

agent_eval/structured_output.py

import instructor
from openai import AsyncOpenAI
...

결과: 구조화된 출력 vs. 프롬프트 체인 (Results: Structured vs. Prompt Chain)

사고의 전환 (The Mental Shift)

초기 비용(스키마(schemas), 가드레일(guardrails), 평가(eval))은 3단계에서 결실을 맺습니다. 5단계에 이르면 이는 필수 사항이 됩니다.

시작하기 (Getting Started)

pip install agent-eval-framework

from agent_eval import StructuredAgent, DecomposeStep, PlanStep, ExtractStep, SynthesizeStep
from agent_eval.guardrails import CitationValidator, ConfidenceGate, SafetyGuardrail
from agent_eval.judges import create_judge_ensemble
...

오픈 소스 (Open Source)

모두 MIT 라이선스입니다:

• agent-eval-framework — 핵심 에이전트 + 평가 (Core agent + evaluation)
• llm-eval-harness — 판사 앙상블 + CI 통합 (Judge ensembles + CI integration)
• structured-output — 자동 재시도를 포함한 범용 추출기 (Universal extractor with auto-retry)

코드: github.com/yourname/agent-eval-framework |
토론: Hacker News |
팔로우: @yourname