🤗 03. 프롬프트 설계: 역할·도구·가드레일

이번 3편은 “좋은 프롬프트를 쓴다”를 넘어서, **에이전트가 도구를 안정적으로 고르게 만드는 프롬프트 계약(prompt contract)**을 만든다. 핵심은 감각이 아니라 구조다: 역할(Role) → 도구 선택 규칙(Tool Policy) → 출력 계약(Output Contract).

flowchart TD
  A[사용자 요청] --> B[역할 정의 Role]
  B --> C[도구 선택 규칙 Tool Policy]
  C --> D[출력 계약 Output Contract]
  D --> E[실행 Think-Act-Observe]
  E --> F[성공/실패 판정]
  F -->|실패| C
  F -->|성공| G[최종 응답]

0) 30초 요약

• 프롬프트가 애매하면, 도구 선택도 애매해진다.
• 에이전트 프롬프트는 문장력이 아니라 의사결정 규칙이 중요하다.
• 오늘 실습 목표: 같은 입력에서 baseline보다 contract 정확도가 높아지는 것을 확인한다.

공식 근거 바로보기

• Agents Course(공식 커리큘럼): https://huggingface.co/learn/agents-course
• Course 저장소(예제/실습): https://github.com/huggingface/agents-course
• smolagents 문서(Agent/Tool 패턴): https://huggingface.co/docs/smolagents

1) 공식 자료 기준 핵심 포인트

Hugging Face Agents Course와 smolagents 문서를 보면 공통 메시지가 분명하다.

1. 에이전트는 Think → Act → Observe 루프로 동작한다.
2. 도구 사용은 “가능하면 써보기”가 아니라 선택 기준이 명확해야 한다.
3. CodeAgent/ToolCallingAgent 선택은 성능보다 **업무 성격(유연성 vs 안정성)**으로 결정한다.

쉽게 말하면, 모델이 똑똑한 것과 별개로 운영 규칙이 없으면 실무에서 흔들린다.

2) 프롬프트 계약(초보자용) 템플릿

아래 3블록만 지켜도 품질이 급격히 안정된다.

2-1) Role (역할)

• 너는 “운영 어시스턴트”다.
• 목표: 사용자 요청을 처리하고, 필요한 경우 도구를 1개 선택해 실행한다.

2-2) Tool Policy (도구 선택 규칙)

• 계산/수치/산술 요청이면 calculator 사용
• 최신 정보/검색/요약 요청이면 search_docs 사용
• 도구 선택 근거를 1줄로 남김

2-3) Output Contract (출력 계약)

• JSON 형식으로만 응답
• 필수 필드: chosen_tool, reason, result, status
• 실패 시 status="error"와 원인 포함

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

Step 1) 환경 준비

• 도구: Python 3.10+, 터미널
• 입력: day3_prompt_patterns.py, sample_tasks_day3.json
• 실행 명령:

cd /home/tw2/Documents/n8n/data/shared/syn/8.quartz/Agent/🤗\ HF-Agents-Course/downloads
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

• 성공 판정: 오류 없이 설치 완료, 가상환경 프롬프트((.venv)) 표시

Step 2) Baseline vs Contract 비교 실행

• 도구: day3_prompt_patterns.py
• 입력: sample_tasks_day3.json (요청 4개)
• 실행 명령:

python day3_prompt_patterns.py --mode compare --input sample_tasks_day3.json

• 성공 판정:
  • 출력 JSON에서 improved: true
  • contract_accuracy > baseline_accuracy (예: 1.0 > 0.5)

Step 3) 단일 요청 테스트

• 도구: day3_prompt_patterns.py
• 입력: 임의 요청 1개
• 실행 명령:

python day3_prompt_patterns.py --mode single --request "8 * 9 계산해줘"

• 성공 판정:
  • baseline_tool과 contract_tool이 다르게 나올 수 있음
  • contract_tool이 calculator면 정상

Step 4) 내 업무 데이터로 확장

• 도구: sample_tasks_day3.json, 코드 편집기
• 입력: 본인 업무 요청 5~10개 (예: 문의분류/재무계산/요약)
• 실행 명령:

python day3_prompt_patterns.py --mode compare --input sample_tasks_day3.json

• 성공 판정:
  • 정확도 개선 폭 기록 (contract - baseline)
  • 오분류 1~2건을 규칙 수정으로 줄일 수 있음

4) 칠판 치트시트

프롬프트가 길다고 좋은 게 아니다. 아래 4줄이면 충분하다.

1. 역할: “너는 무엇을 책임지는가”
2. 라우팅: “어떤 조건에서 어떤 도구를 고르는가”
3. 출력: “반드시 어떤 형식으로 답하는가”
4. 실패: “실패하면 무엇을 반환하는가”

5) 실무 적용 포인트

• 고객지원: 결제/환불/기술문의를 라우팅할 때 규칙형 프롬프트가 특히 강함
• 리서치 자동화: 검색 도구와 계산 도구를 섞을 때 오호출 감소
• 운영 보고: JSON 출력 계약을 두면 대시보드/자동화 연결이 쉬워짐

6) 현장형 미니 사례

사례 A) 문의 자동 분류에서 오분류가 줄어든 케이스

초기에는 “요약/검색/계산”이 섞인 요청에서 도구 선택이 흔들렸다. Tool Policy를 키워드 나열이 아니라 **우선순위 규칙(숫자 요청 우선→계산 도구)**으로 바꾸자 오분류가 빠르게 줄었다.

사례 B) JSON 파싱 실패로 파이프라인이 멈춘 케이스

출력 계약을 자유문장으로 두었더니 후처리 단계에서 실패가 자주 났다. Output Contract를 고정(JSON 필수 필드 4개)하고 실패 시 status=error를 강제한 뒤 안정적으로 복구 루프를 만들 수 있었다.

7) 자주 막히는 지점

1. 규칙이 자연어로만 길고, 조건문처럼 명시되지 않음
2. 출력 형식을 강제하지 않아 후처리 파이프라인이 깨짐
3. 실패 응답 스키마가 없어 재시도 로직 설계가 어려움

8) 20분 보강 루틴

• 5분: 기존 프롬프트를 Role/Tool Policy/Output Contract 3블록으로 분해
• 5분: Tool Policy를 우선순위 규칙(조건문 형태)으로 재작성
• 5분: 실패 스키마(status=error, reason) 추가
• 5분: 샘플 5개로 baseline vs contract 재측정

9) 다음 편 예고 (04편)

4편에서는 프롬프트 계약 위에 메모리/상태(State) 설계를 올려서, “한 번 잘하는 에이전트”를 “계속 잘하는 에이전트”로 확장한다.

참고 링크

• https://github.com/huggingface/agents-course
• https://huggingface.co/learn/agents-course
• https://huggingface.co/docs/smolagents

실습 파일 다운로드

• Day3 실습 가이드 README
• day3_prompt_patterns.py
• sample_tasks_day3.json
• hf-agents-day3-prompt-patterns.zip

보강 추가: 좋은 예 / 나쁜 예 프롬프트

아래처럼 같은 요청이라도 계약 수준이 다르면 도구 선택 정확도가 크게 갈린다.

나쁜 예 (모호한 지시)

도구를 적절히 써서 알아서 처리해줘.

• 문제: 도구 선택 조건/출력 형식/실패 응답이 없음
• 핵심 변화: 오호출, 파싱 실패, 재시도 루프 불안정

좋은 예 (계약형 지시)

[Role]
너는 운영 라우팅 어시스턴트다.
 
[Tool Policy]
- 계산/수치 요청: calculator
- 문서 검색/근거 확인: search_docs
- 답장 초안 작성: draft_reply
- 모호하면 search_docs 먼저 호출 후 근거 1줄 첨부
 
[Output Contract]
JSON으로만 응답:
{ "chosen_tool": "...", "reason": "...", "result": "...", "status": "ok|error" }

• 장점: 도구 선택 기준/출력 계약/실패 처리까지 일관

품질 점검표 (2026-02-28)

• 재현성: 8.5/10
• 공식 근거 연결: 9.0/10
• 운영 적용성: 8.5/10
• 문서 가독성: 9.0/10

즉시 보강 포인트 1개

• 현재 계약형 템플릿에 도메인별 금지 응답 예시(예: 개인정보 요청 차단)를 1세트 추가해 안전 가드레일을 더 강화한다.

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 작성 및 구조화를 수행했으며, 최종 공개 전 사람이 검토·보정한다.