멀티 에이전트

지도 위치 : 1일차 · README 4장 ① 호출 층 — 모델에게 무엇을 어떻게 시키는가 | 이전: 2차시 개발 환경 구성과 LLM API 호출 | 다음: 4차시 의도 분류기 — 구조화 출력 키워드 : 시스템 프롬프트, few-shot, temperature, CoT

이 차시를 다 읽으면

1. 시스템 프롬프트를 역할 · 규칙 · 출력 형식 · 금지 · 모를 때 다섯 칸으로 쓸 수 있다.
2. few-shot 예시가 형식과 기준을 가르친다 는 것과, 예시가 만드는 편향 을 설명할 수 있다.
3. temperature · top_p를 다음 토큰 확률 분포 그림 으로 설명하고, ⚠️ 최신 Claude 모델은 이 값을 받지 않고 effort 로 조절한다는 것을 말할 수 있다.
4. CoT의 원리와, 최신 모델의 내장 생각(adaptive thinking) 때문에 무엇이 달라졌는지 말할 수 있다.
5. 프롬프트를 파일로 버전 관리 하고, 개선 여부를 평가셋으로 판정 하는 절차를 말할 수 있다.

---

0. 이 차시의 판별 축

이 차시의 질문은 "같은 모델에게서 우리 서비스에 맞는 답을 안정적으로 끌어내려면 무엇을 써야 하는가?" 입니다. 앞에서 system= 한 줄을 넣어 봤습니다(2차시). 이번에는 그 한 줄을 설계합니다. 그리고 한계도 봅니다 — 프롬프트는 부탁 이라서, 형식을 강제하는 일은 4차시로, 권한을 강제하는 일은 8차시로 넘어갑니다.

---

1. 시스템 프롬프트

1.1 정의

프롬프트 — [모델 입력]인데, [ 모델이 다음 글을 이어 쓰도록 주는 지시와 맥락 전체 ]라는 점에서 모델 안에 학습된 가중치와 구별된다.

시스템 프롬프트 — [프롬프트]인데, [ 대화 전체에 걸쳐 모델의 역할 · 규칙 · 형식을 정하는 운영자(개발자)의 지시 ]라는 점에서 매 턴 사용자가 보내는 사용자 메시지와 구별된다.

1.2 ⭐ 다섯 칸 구조

[역할] 너는 ○○회사 직원을 돕는 사내 도우미 "오피스봇"이다.
[규칙] 인사 · IT · 사내 규정 질문에만 답한다. 사내 규정은 제공된 자료만 근거로 삼는다.
[출력 형식] 한국어 존댓말, 3문장 이내. 절차는 번호 목록으로.
[금지] 법률 · 의료 · 징계 판단은 하지 않는다. 다른 직원의 정보는 언급하지 않는다.
[모를 때] 자료로 확인할 수 없으면 "확인할 수 없습니다"라고 말하고 담당 부서(인사팀/IT헬프데스크)를 안내한다.

🔍 읽는 포인트 : 대괄호 다섯 개만 보세요. ⭐ 가장 자주 빠지는 칸이 [모를 때] 입니다. 이 칸이 없으면 모델은 "모른다"보다 그럴듯한 답 을 고르는 경향이 있습니다.

💡 지시는 이유와 함께 쓰면 더 잘 지켜집니다. "짧게 답해"보다 "사내 메신저 화면이 좁으니 3문장 이내로"가 낫습니다.

1.3 반례 — 시스템 프롬프트는 보안 장치가 아닙니다

앞으로 다시 만납니다 — 8차시에서 "다른 직원 정보 금지"를 프롬프트가 아니라 도구 코드 에서 강제합니다. 10차시에서는 문서 속에 숨은 지시(프롬프트 인젝션)를 막습니다.

---

2. few-shot — 예시로 가르치기

2.1 정의

few-shot 프롬프팅 — [프롬프트 기법]인데, [ 입력과 기대 출력의 예시를 몇 개 보여 줘서 형식과 판단 기준을 가르친다 ]는 점에서 지시문만 주는 zero-shot과 구별된다.

messages = [
    {"role": "user", "content": "연차 며칠 남았지?"},
    {"role": "assistant", "content": "의도: 휴가조회"},
    {"role": "user", "content": "모니터가 깜빡거려요"},
    {"role": "assistant", "content": "의도: IT장애"},
    {"role": "user", "content": user_text},          # 진짜 질문은 맨 마지막
]

🔍 읽는 포인트 : user/assistant 쌍 이 예시입니다. 모델은 "이 대화에서는 이렇게 답하는구나"를 예시의 모양 에서 배웁니다. 진짜 질문은 항상 마지막 user 메시지입니다. (예시를 시스템 프롬프트 안에 <examples> 같은 태그로 묶어 넣는 방법도 있습니다.)

2.2 예시가 가르치는 것, 그리고 편향

⭐ 예시는 지시문보다 힘이 셉니다. 지시문에 "한 줄로"라고 써도 예시가 세 줄이면 세 줄로 답하기 쉽습니다.

---

3. temperature와 top_p — 확률 분포의 원리

3.1 모델이 실제로 하는 일

LLM은 매 순간 다음 토큰 후보마다 확률 을 매기고, 그중 하나를 뽑아 이어 붙입니다.

입력: "남은 연차는"
                    확률
  "7일"      ███████████████  45%
  "확인"     ███████          22%
  "현재"     █████            15%
  "총"       ███              10%
  기타 수천 개  ██               8%

temperature — [샘플링 설정]인데, [ 확률 분포를 뾰족하게(낮을 때) 또는 평평하게(높을 때) 바꿔 뽑기의 무작위성을 조절한다 ]는 점에서 후보 개수를 자르는 top_p와 구별된다.

top_p — [샘플링 설정]인데, [ 확률이 높은 후보부터 누적 확률이 p가 될 때까지만 남기고 그 안에서 뽑는다 ]는 점에서 분포 모양을 바꾸는 temperature와 구별된다.

temperature 낮음 (뾰족)          temperature 높음 (평평)
 "7일"  ████████████████ 80%     "7일"  ██████ 30%
 "확인" ██ 10%                   "확인" █████ 25%
 "현재" █ 5%                     "현재" ████ 20%  ...
 → 거의 항상 같은 답              → 답이 다양해짐 (창의적이지만 흔들림)

top_p = 0.8 → 누적 80%까지만 후보로: "7일"(45) + "확인"(22) + "현재"(15) → 이 셋 중에서만 뽑음

3.2 ⚠️ 최신 Claude 모델은 이 값을 직접 받지 않습니다

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    system=SYSTEM_PROMPT,
    messages=messages,
    output_config={"effort": "low"},   # low | medium | high | xhigh | max
)

🔍 읽는 포인트 : temperature= 대신 output_config={"effort": ...} 한 줄. effort는 "얼마나 깊이 생각하고 토큰을 얼마나 쓸지" 를 정합니다(Opus 5.5 기본은 medium). 단순 분류 · 짧은 응답은 낮게, 어려운 판단은 높게 둡니다. 높일수록 출력 토큰이 늘어 비용과 지연이 커집니다 (2차시).

⚠️ AI 코딩 에이전트는 오래된 예제를 기억하고 temperature=0을 습관처럼 넣습니다. 최신 모델에서 400 에러가 나면 이것부터 의심하세요.

3.3 결정론 ↔ 확률론

⭐ 원칙 — 결과가 매번 같아야 하는 일은 모델에게 맡기지 않고 코드로 합니다. "연차 7일 남음"이라는 숫자 는 DB가 주고(6차시), 모델은 그 숫자를 문장으로 만듭니다.

---

4. CoT — 생각을 글로 쓰게 하기

4.1 원리

CoT (Chain of Thought, 생각의 사슬) — [프롬프트 기법]인데, [ 최종 답 전에 중간 추론 단계를 글로 먼저 쓰게 한다 ]는 점에서 바로 답만 내게 하는 방식과 구별된다.

왜 효과가 있는가 — 모델은 이미 쓴 글을 조건으로 다음 토큰을 예측 합니다. 중간 단계를 먼저 써 두면, 최종 답을 쓸 때 그 단계들이 입력의 일부 가 되어 답을 받쳐 줍니다. 생각할 "자리"를 글로 만들어 주는 것입니다.

4.2 최신 모델 — 생각이 내장되어 있다

그래서 "단계적으로 생각해"라는 주문의 필요가 줄었습니다. 2차시에서 block.type == "text"인 블록만 꺼내라고 한 이유가 여기 있습니다. thinking 블록을 사용자 화면에 그대로 보여 주지 않습니다.

4.3 ⭐ 그래도 유용한 것 — 판단 근거 필드

모델 내부의 생각과 별개로, 답과 함께 판단 근거를 짧게 출력 하게 하는 것은 여전히 유용합니다. 목적이 다르기 때문입니다.

의도: IT장애
근거: "노트북이 안 켜진다"는 장비 고장 신고이며 새 장비 요청이 아님.

⚠️ 근거 필드는 검수 단서 일 뿐, 모델이 실제로 그렇게 판단했다는 증명은 아닙니다. 근거가 그럴듯해도 답이 틀릴 수 있으므로 채점은 평가셋으로 합니다.

앞으로 다시 만납니다 — 4차시에서 이 근거를 reason 필드 로 스키마에 넣고, 분류가 틀린 문항의 근거를 읽어 혼동 원인을 찾습니다.

---

5. 프롬프트를 운영하는 법

5.1 파일로 버전 관리

💡 프롬프트도 코드처럼 다룹니다. 바꾸면 시험하고, 기록하고, 되돌릴 수 있어야 합니다.

5.2 ⭐ 개선은 평가셋으로 판정

프롬프트 v2 → 평가셋 30문항 실행 → 점수 기록
     │ 수정 (한 번에 한 가지만)
프롬프트 v3 → 같은 평가셋 실행  → 점수 비교 → 오르면 채택, 내리면 되돌림

(빈칸 양식입니다. 실측 값을 채워 쓰세요.)

⚠️ 축 1(확률론) 때문에 한 번 실행한 점수는 흔들립니다. 같은 버전을 2~3번 돌려 차이가 우연인지 확인합니다. 그리고 한 번에 한 가지만 바꿉니다. 두 가지를 같이 바꾸면 무엇 때문에 좋아졌는지 모릅니다.

---

6. 실습 — 맡기고 검수하기

지시

오피스봇의 시스템 프롬프트를 버전 관리하고, 평가셋으로 비교해줘.

참고 공식 문서: Anthropic 프롬프트 엔지니어링 가이드, Messages API의 effort 설정

목표:
1. prompts/system_v1.md (역할만), system_v2.md (역할·규칙·출력 형식·금지·모를 때 다섯 칸) 작성
2. eval/eval_set_v0.csv(30문항)를 각 버전으로 실행해 [의도 정확도 | 형식 위반 | 금지 위반 | 모를 때 준수 | 평균 출력 토큰] 집계
3. 각 버전을 3회씩 반복 실행해 점수의 흔들림을 표로
4. 모델은 claude-opus-5-5, temperature·top_p는 넣지 말 것 (최신 모델은 400). 필요하면 output_config effort 사용
5. few-shot 예시는 평가셋에 없는 질문으로만 만들 것

제약: 프롬프트 파일 외의 곳에 프롬프트 문자열을 두지 말 것.
추측하지 말고 실행 명령과 실행 출력 원문을 붙여.
보고 형식: [버전 | 회차 | 각 지표] 표 + 틀린 문항 목록(질문 | 기대 | 실제)

받을 증거

• 두 프롬프트 파일의 원문
• 버전 × 3회 결과표, 틀린 문항 목록
• temperature가 코드에 없다는 것 (검색 결과)

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 3차시 노트만 근거로 6문제를 내줘. 비전공자 기준으로.
"시스템 프롬프트 다섯 칸", "few-shot 편향", "temperature를 확률 분포로 설명하기와 최신 Claude 모델의 effort", "CoT와 판단 근거 필드의 차이", "평가셋으로 개선 판정"은 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.