멀티 에이전트

지도 위치 : 1일차 · README 4장 ① 호출 층의 마지막 — 모델의 글을 코드가 쓸 수 있는 데이터 로 | 이전: 3차시 프롬프트 설계 | 다음: 5차시 Function Calling 원리 키워드 : 구조화 출력, 스키마 검증, 예외 처리

이 차시를 다 읽으면

1. 구조화 출력을 유와 종차로 정의하고, 프롬프트로 "JSON으로" 부탁 하는 것과 스키마로 강제 하는 것의 차이를 말할 수 있다.
2. Pydantic과 Literal로 분류값을 고정한 스키마를 읽고, messages.parse 코드의 핵심 줄을 짚을 수 있다.
3. ⭐ 스키마는 형식을 보장할 뿐, 분류가 맞는지는 보장하지 않는다 (축 ⑧)를 예로 설명할 수 있다.
4. 낮은 확신 · 기타, 파싱 실패 · 거절 · 잘림을 각각 어떻게 처리할지 정할 수 있다.
5. 평가셋 혼동표 를 읽고, 분류를 가벼운 모델(Haiku)에 맡길지 비용과 정확도로 판단할 수 있다.

---

0. 이 차시의 판별 축

이 차시의 질문은 "모델의 자유로운 글을, 코드가 if로 분기할 수 있는 값으로 바꾸려면?" 입니다. 앞에서 프롬프트로 형식을 부탁하고 판단 근거를 남기게 했습니다(3차시). 이번에는 형식을 강제 합니다. 그리고 강제로도 해결되지 않는 것(뜻이 맞는가)을 평가셋으로 잽니다.

---

1. 구조화 출력 — 부탁에서 강제로

1.1 정의

의도 분류 — [텍스트 분류]인데, [ 사용자의 말이 무엇을 원하는지 미리 정한 범주 중 하나로 고른다 ]는 점에서 말의 감정(긍정 · 부정)을 고르는 감정 분류와 구별된다.

구조화 출력 (Structured Output) — [LLM 출력 방식]인데, [ 정해진 스키마(필드 이름 · 타입 · 허용 값)에 맞는 데이터로만 답하게 강제한다 ]는 점에서 자유로운 글로 답하는 일반 응답과 구별된다.

스키마 — [데이터 약속]인데, [ 어떤 필드가 있고 각 필드에 어떤 값이 올 수 있는지 기계가 검사할 수 있게 적은 것 ]이라는 점에서 사람이 읽는 설명문과 구별된다.

1.2 부탁 ↔ 강제

⚠️ 최신 Claude 모델은 답의 앞부분을 미리 채워 두는 방식(assistant prefill)으로 형식을 유도할 수 없습니다(400 에러). 형식은 구조화 출력 으로 맞춥니다.

---

2. 스키마 정의 — Pydantic

2.1 Pydantic과 Literal

Pydantic — [파이썬 라이브러리]인데, [ 클래스로 데이터 모양을 선언하면 들어온 값이 그 모양에 맞는지 자동으로 검사한다 ]는 점에서 아무 값이나 담기는 일반 딕셔너리와 구별된다.

from pydantic import BaseModel
from typing import Literal

class Intent(BaseModel):
    intent: Literal["휴가조회", "규정질문", "장비신청", "IT장애", "기타"]
    confidence: Literal["high", "low"]
    reason: str

🔍 읽는 포인트 : 필드 세 개만 보세요.

• intent — Literal[...] 안의 다섯 값 외에는 올 수 없습니다. "휴가 조회"(띄어쓰기)나 "연차문의" 같은 변형이 원천 차단됩니다.
• confidence — 모델이 스스로 매기는 확신. 3.2에서 씁니다.
• reason — 앞에서 배운 판단 근거 필드 (3차시). 틀린 분류의 원인을 찾는 단서입니다.

2.2 호출 — messages.parse

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=CLASSIFIER_PROMPT,
    messages=[{"role": "user", "content": user_text}],
    output_format=Intent,
)
result = response.parsed_output        # 검증된 Intent 객체
print(result.intent, result.confidence, result.reason)

🔍 읽는 포인트 : create 대신 parse, 그리고 output_format=Intent 한 줄. 돌아온 parsed_output은 글이 아니라 .intent로 꺼낼 수 있는 객체 입니다.

💡 Pydantic을 쓰지 않는 방법도 있습니다 — client.messages.create(..., output_config={"format": {"type": "json_schema", "schema": {...}}})로 JSON 스키마를 직접 주면 첫 text 블록이 스키마에 맞는 JSON입니다. 이때 스키마에 "additionalProperties": False와 required를 꼭 넣습니다. 스키마에서 지원하지 않는 제약도 있으니 공식 문서를 확인하세요.

---

3. ⭐ 스키마가 보장하는 것과 보장하지 않는 것

3.1 축 ⑧ — 형식은 맞고 뜻은 틀린 답

{"intent": "장비신청", "confidence": "high", "reason": "노트북 관련 요청"}

질문은 "노트북 화면이 깨져서 안 보여요" 였습니다. 기대 의도는 IT장애(고장 신고)입니다.

⭐ 스키마는 "말이 되는 모양"을 보장하고, 평가셋은 "맞는 말"인지를 잽니다. 둘은 다른 축의 검사라서 하나가 다른 하나를 대신하지 못합니다. AI가 "구조화 출력을 적용해서 분류가 정확해졌습니다"라고 보고하면, 형식 오류가 사라진 것 과 정확도가 오른 것 을 나눠서 증거를 요구하세요.

3.2 낮은 확신과 "기타"

⚠️ confidence도 모델의 자기 평가 입니다. "high"인데 틀리는 경우가 있습니다(3.1의 예). 확신 값이 실제로 쓸모 있는지는 평가셋에서 "low인 문항의 오답률이 high보다 높은가" 로 확인합니다.

💡 "기타"를 빼면 모델은 범위 밖 질문도 다섯 의도 중 하나에 억지로 넣습니다. 탈출구 값은 꼭 둡니다.

---

4. 예외 처리

def classify(user_text: str) -> Intent:
    try:
        response = client.messages.parse(..., output_format=Intent)
    except anthropic.APIError as e:
        log.error("분류 API 오류: %s", e)
        return FALLBACK                     # Intent(intent="기타", confidence="low", reason="분류 실패")
    if response.stop_reason in ("refusal", "max_tokens") or response.parsed_output is None:
        log.warning("분류 비정상 종료: %s", response.stop_reason)
        return FALLBACK
    return response.parsed_output

🔍 읽는 포인트 : 어떤 실패든 FALLBACK(기타 + low)으로 모입니다. 분류기가 실패해도 서비스는 죽지 않고 "사람에게 연결" 쪽으로 안전하게 넘어갑니다. ⚠️ 이 코드는 구조 예시입니다. 거절 · 잘림 때 parse가 예외를 내는지 빈 값을 주는지는 SDK 버전에 따라 다를 수 있으니 공식 문서로 확인하게 하세요.

---

5. 분류 결과로 분기 — 워크플로우

intent = classify(user_text)

if intent.confidence == "low":
    return ask_clarifying_question(user_text)
match intent.intent:
    case "휴가조회": return handle_leave(user)          # 6차시: 휴가 조회 도구
    case "IT장애":  return handle_it_ticket(user)      # 6차시: 티켓 조회 도구
    case "규정질문": return handle_policy(user_text)    # 12~15차시: 문서 검색
    case "장비신청": return draft_equipment_request()   # 23차시: 사람 승인
    case _:        return hand_over_to_human()

🔍 읽는 포인트 : match 아래 다섯 줄이 갈림길 입니다. 어느 길로 갈지는 모델이 고른 값으로 정하지만, 갈림길 자체와 각 길의 처리 순서는 코드가 정했습니다. 1차시 사다리의 2칸 워크플로우 입니다.

앞으로 다시 만납니다 — 7차시에서 이 분류 결과로 쓸 도구 묶음을 좁히고 , 19차시에서 같은 분기를 그래프의 조건부 엣지로 다시 만듭니다.

---

6. 평가셋과 혼동표

6.1 혼동표 읽기

혼동표 (Confusion Matrix) — [평가 표]인데, [ 기대 범주(행)와 실제 예측(열)을 교차해 어떤 범주를 어떤 범주로 착각했는지 센다 ]는 점에서 맞은 비율 하나만 보여 주는 정확도와 구별된다.

(빈칸 양식입니다.) 대각선 이 맞힌 수, 대각선 밖이 착각입니다. 정확도 = 대각선 합 ÷ 전체.

⭐ 정확도 하나보다 어디서 틀리는가 가 더 중요합니다.

• IT장애 행의 장비신청 칸이 크다 → 고장 신고와 새 장비 요청의 경계가 흐림 → 프롬프트에 경계 기준과 예시(3차시)를 추가
• 기타 행이 다른 칸으로 새어 나간다 → 범위 밖 질문을 억지로 분류 → 위험 (1차시 "사람만" 칸이 엉뚱한 처리로 감)

6.2 가벼운 모델로 분류할까

분류는 모든 질문마다 한 번씩 일어납니다. 답을 길게 쓰지도 않습니다. 앞에서 본 한 건 비용 계산(2차시)을 다시 쓰면:

(빈칸 양식입니다. 가격은 공식 가격 페이지 확인.)

판단 순서 — ① 가장 싼 모델부터 평가셋을 돌린다 → ② 완료 기준(1차시)을 넘으면 거기서 멈춘다 → ③ 못 넘으면 프롬프트 개선 → 그래도 안 되면 한 단계 위 모델. ⚠️ 정확도가 비슷해도 기타 행의 오분류 (위험한 요청을 놓침)가 많은 모델은 탈락입니다.

---

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

지시

오피스봇 의도 분류기를 구조화 출력으로 만들고 평가해줘.

참고 공식 문서: Anthropic Structured Outputs(messages.parse, output_format), Pydantic 공식 문서

목표:
1. classifier.py: Intent 모델(intent Literal 5개, confidence high/low, reason)과 classify() 함수
   - refusal, max_tokens, 파싱 실패, API 오류 → 모두 FALLBACK(기타, low)으로, 원인은 로그에
2. router.py: 분류 결과로 분기하는 match 문 (각 처리는 지금은 "TODO: 처리 이름"만 반환)
3. eval_classifier.py: eval/eval_set_v0.csv로 혼동표(5×5), 정확도, confidence별 오답률 출력
4. 같은 평가를 claude-haiku-5-5와 claude-opus-5-5로 각각 실행, usage로 한 건 평균 비용 계산
5. 틀린 문항은 [질문 | 기대 | 예측 | reason] 표로

제약: 프롬프트로 "JSON으로 답해"라고 쓰는 방식은 쓰지 말 것. assistant prefill 금지. temperature 금지.
추측하지 말고 실행 명령과 실행 출력 원문을 붙여.
보고 형식: 모델별 [정확도 | 기타 오분류 | high 오답률 | low 오답률 | 평균 비용] 표 + 혼동표 원문

받을 증거

• 모델별 혼동표 출력 원문 과 틀린 문항 표
• 일부러 max_tokens=20으로 줄여 실행했을 때 FALLBACK으로 떨어진 로그

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 4차시 노트만 근거로 6문제를 내줘. 비전공자 기준으로.
"부탁과 강제", "스키마는 형식만 보장하고 뜻은 평가셋으로", "낮은 확신과 기타 처리", "혼동표 읽기", "분류 모델 고르기"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.