🤗 09. 본편 04: 계획-실행-검증 루프로 에이전트 신뢰도 높이기

이번 편은 “한 번에 답을 내는 에이전트”를 “계획→실행→검증” 루프로 바꿔서 품질을 안정화하는 실전 패턴을 다룬다.

• 이전 편: 🤗 08. 본편 03

한 줄 결론

에이전트가 바로 답부터 내게 두지 말고, (1) 계획 생성 (2) 실행 (3) 체크리스트 검증 단계를 분리하면 초보자도 재현 가능한 결과 품질을 만들 수 있다.

왜 중요한가 (초보자 관점)

실무에서 에이전트 실패는 보통 이 3가지다.

1. 핵심 요구를 빼먹음
2. 민감정보를 그대로 노출
3. 고위험 요청인데 승인 없이 진행

smolagents 문서/코스에서 강조하는 방향처럼, 중간 사고 단계(계획/툴 사용/검증)를 구조화하면 이런 실패를 크게 줄일 수 있다.

flowchart LR
  A[사용자 요청] --> B[Plan: 단계 계획]
  B --> C[Execute: 초안 생성]
  C --> D[Validate: 체크리스트 검증]
  D --> E{통과?}
  E -- Yes --> F[최종 결과 PASS]
  E -- No --> G[REVIEW/수정 요청]

---

실습: 20~30분 재현 (도구/입력/실행명령/성공판정)

실습 파일 경로: /home/tw2/Documents/n8n/data/shared/syn/8.quartz/Agent/🤗 HF-Agents-Course/downloads

Step 1) 도구 준비

• 도구: day9_plan_execute_validate.py
• 입력: 없음
• 실행명령:

cd /home/tw2/Documents/n8n/data/shared/syn/8.quartz/Agent/🤗\ HF-Agents-Course/downloads
python3 day9_plan_execute_validate.py --mode selfcheck

• 성공판정:
  • 출력 JSON에 "selfcheck_ok": true
  • result.final.status가 PASS

Step 2) 단일 요청 실행 (고위험 + 개인정보)

• 도구: day9_plan_execute_validate.py
• 입력:
  • request: 고객 불만 VOC 요약 보고서 작성
  • risk: high
  • pii: 1
  • deadline: 2
• 실행명령:

python3 day9_plan_execute_validate.py \
  --mode single \
  --request "고객 불만 VOC 요약 보고서 작성" \
  --risk high \
  --pii 1 \
  --deadline 2

• 성공판정:
  • plan에 민감정보 마스킹 포함
  • draft에 [REDACTED] 포함
  • validation.ok = true

Step 3) 배치 평가로 재현성 확인

• 도구: sample_tasks_day9.json
• 입력: 샘플 3건
• 실행명령:

python3 day9_plan_execute_validate.py --mode eval --input sample_tasks_day9.json

• 성공판정:
  • pass = true 또는
  • score >= 0.66

---

코드에서 꼭 볼 포인트

1. Plan 분리 (make_plan): 위험도/PII/기한에 따라 단계가 동적으로 바뀜
2. 검증 강제 (validate_output): 요약/체크리스트/마스킹/승인 문구를 자동 검사
3. 최종 게이트 (status): 통과면 PASS, 아니면 REVIEW

실무 적용 포인트

• 콘텐츠 팀: 발행 전 검증 단계로 사실/표현/민감정보 누락 방지
• 운영팀: 고위험 작업은 자동으로 “검토자 승인 필요” 문구 강제
• 자동화 파이프라인(n8n): 에이전트 출력 뒤에 Validate 노드를 둬서 품질 게이트 적용

자주 막히는 지점 3가지

1. 파일 경로 오류
   • 이모지 경로라서 실패하면 전체 경로를 따옴표로 감싸기
2. score가 낮게 나옴
   • sample_tasks_day9.json의 기대값(expect)과 실제 규칙이 맞는지 확인
3. 실무 규칙 반영이 어려움
   • validate_output의 체크 항목을 팀 정책에 맞게 1개씩 추가

체크리스트

• selfcheck 통과 (selfcheck_ok=true)
• single 모드에서 validation.ok=true
• eval 점수 기록 (score)
• 우리 팀 규칙 1개 이상 validation에 반영

참고 링크 (우선순위)

1. https://github.com/huggingface/agents-course
2. https://huggingface.co/learn/agents-course
3. https://huggingface.co/docs/smolagents

실습 파일

• Day9 실습 가이드 README
• day9_plan_execute_validate.py
• sample_tasks_day9.json

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 작성과 구조화를 수행했으며, 최종 발행 전 사람이 사실관계와 재현 절차를 검토했다.