멀티 에이전트

지도 위치 : 1일차 · README 4장 ② 행동 층 — 도구가 여럿일 때 어느 것을 고르는가 | 이전: 6차시 데이터 조회 도구 구현 | 다음: 8차시 보안 — 안전한 도구 실행 키워드 : 도구 라우팅, 컨텍스트 비용, 디버깅

이 차시를 다 읽으면

1. 도구가 늘면 생기는 세 문제( 설명 겹침 · 선택 오류 · 컨텍스트 비용 )를 말할 수 있다.
2. 라우팅의 두 방식( 모델이 고름 ↔ 분류기가 먼저 좁힘 )을 "누가 흐름을 정하는가" 축으로 비교할 수 있다.
3. 질문-기대 도구 평가셋 으로 도구 선택 정확도를 재는 표를 만들 수 있다.
4. 선택 오류를 줄이는 네 수단(설명 다듬기 · 이름 구분 · 도구 묶음 줄이기 · 의도별 도구 세트)과 프롬프트 캐싱을 적용할 수 있다.
5. 요청 · 응답 로그의 tool_use 기록으로 어떤 도구를 왜 골랐는지 추적할 수 있다.

---

0. 이 차시의 판별 축

이 차시의 질문은 "도구가 두 개에서 열 개, 스무 개로 늘어도 모델이 맞는 도구를 고르게 하려면?" 입니다. 앞에서 조회 도구 두 개를 만들었습니다(6차시). 오피스봇이 자라면 휴가 · 티켓 · 장비 · 회의실 · 사내 연락처 도구가 계속 붙습니다. 그때 생기는 문제를 측정하고 고칩니다.

---

1. 도구가 늘면 생기는 문제

1.1 정의

도구 라우팅 — [도구 호출 설계]인데, [ 여러 도구 중 이번 요청에 맞는 도구(또는 도구 없음)를 고르는 과정 ]이라는 점에서 고른 도구를 실제로 실행하는 단계와 구별된다.

1.2 세 문제

컨텍스트 — [모델 입력]인데, [ 이번 호출에 함께 보내는 모든 것(시스템 프롬프트 · 도구 정의 · 대화 · 도구 결과) ]이라는 점에서 모델이 학습으로 가진 지식과 구별된다.

1.3 선택 오류의 네 종류

1.4 컨텍스트 비용 재기

tokens_2 = client.messages.count_tokens(model=MODEL, tools=TOOLS[:2], messages=msgs).input_tokens
tokens_20 = client.messages.count_tokens(model=MODEL, tools=TOOLS, messages=msgs).input_tokens
print("도구 2개:", tokens_2, "/ 도구 20개:", tokens_20)

🔍 읽는 포인트 : 같은 질문, 도구 목록만 다르게 해서 입력 토큰을 셉니다(2차시의 count_tokens). 차이가 질문마다 붙는 도구 정의 비용 입니다. 앞에서 본 "곱하기 건수"가 여기서도 적용됩니다. 9차시 에이전트 루프는 한 질문에 여러 번 호출하므로 곱하기 반복 횟수 까지 붙습니다.

---

2. 라우팅의 두 방식 — 누가 흐름을 정하는가

(A) 모델이 고름                          (B) 분류기가 먼저 좁힘
질문 ─▶ 모델 + 도구 20개 전부             질문 ─▶ 분류기(4차시) ─▶ intent="휴가조회"
          │ 모델이 하나 고름                                      │ 코드가 도구 세트 선택
          ▼                                                     ▼
       tool_use                             모델 + 휴가 도구 3개만 ─▶ tool_use

⭐ 정답은 하나가 아닙니다. 도구가 몇 개뿐이면 (A)로 충분하고, 늘어나면 (B)를 검토합니다 — 1차시 문장 1 "충분하면 멈춘다"가 여기에도 적용됩니다. 어느 쪽이 나은지는 3절의 평가셋으로 잰 뒤 정합니다.

💡 (B)의 약점 대비 — 분류가 low이거나 기타면 넓은 도구 세트 를 주는 식으로 섞을 수 있습니다(4차시 3.2).

앞으로 다시 만납니다 — (B)는 19차시에서 그래프의 조건 분기 로, 22차시에서 관리 에이전트가 전문 에이전트를 고르는 오케스트레이션 으로 다시 나옵니다. 도구 대신 에이전트를 고를 뿐 같은 질문입니다.

---

3. 도구 선택 정확도 측정

3.1 평가셋 — 1차시 평가셋에 열 추가

번호 | 질문                           | 기대 도구            | 기대 인자              | 비고
101  | 올해 연차 며칠 남았지?            | get_leave_balance   | year=2026             |
102  | 연차는 몇 년차부터 늘어나요?        | (도구 없음 → 규정 검색) |                       | 오선택 유도
103  | 내가 올린 장애 처리됐어?           | get_ticket_status   | status_filter=전체     |
104  | 처리 중인 티켓만 보여줘             | get_ticket_status   | status_filter=처리중   |
105  | 고마워요                         | (도구 없음)           |                       | 불필요 호출 유도
106  | 연차 남은 거랑 티켓 상태 둘 다       | get_leave_balance + get_ticket_status |  | 병렬

(예시 형식입니다.) ⭐ "도구 없음"이 정답인 문항 을 꼭 넣습니다. 이것이 없으면 불필요 호출을 잴 수 없습니다.

3.2 결과표

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

도구 선택 정확도 = 정답 도구 ÷ 전체 문항. 확률론(3차시) 때문에 같은 구성을 2~3회 돌려 흔들림도 봅니다.

⚠️ 도구 선택만 맞고 최종 답이 틀릴 수도 있습니다(도구 결과를 무시하고 답함). 선택 정확도와 답의 정확도는 따로 셉니다.

---

4. 개선 수단

4.1 네 수단

# 설명 다듬기 — 비슷한 도구와의 차이를 적음
"description": "현재 사용자의 남은 연차 일수를 숫자로 조회한다. "
               "'며칠 남았어' 같은 잔여 질문에만 사용. "
               "연차가 생기는 기준 · 규정 질문에는 사용하지 않는다(규정 검색이 담당)."

# 의도별 도구 세트
TOOLSETS = {
    "휴가조회": [LEAVE_BALANCE, LEAVE_HISTORY],
    "IT장애":  [TICKET_STATUS, IT_NOTICE],
    "기타":    ALL_READ_TOOLS,             # 분류가 애매하면 넓게
}
tools = TOOLSETS.get(intent.intent, ALL_READ_TOOLS)

🔍 읽는 포인트 : 위는 설명의 마지막 문장 (쓰지 말 때와 담당자), 아래는 TOOLSETS 딕셔너리 — 의도 이름이 열쇠, 도구 목록이 값. 모르는 의도면 넓은 세트로 갑니다.

4.2 ⚠️ 한 번에 하나씩

설명을 고치면서 이름도 바꾸고 세트도 나누면, 점수가 올라도 무엇 덕분인지 모릅니다. 3차시에서 프롬프트를 고칠 때와 같은 규칙입니다. 결과표(3.2)에 한 줄씩 추가합니다.

4.3 프롬프트 캐싱으로 도구 정의 비용 줄이기

요청의 앞부분은 도구 정의 → 시스템 프롬프트 → 대화 순서로 놓입니다. 도구 정의와 시스템 프롬프트가 요청마다 같다면 캐싱으로 재사용할 수 있습니다(2차시).

response = client.messages.create(
    model=MODEL, max_tokens=16000,
    tools=tools, system=SYSTEM_PROMPT, messages=messages,
    cache_control={"type": "ephemeral"},
)
log.info("cache_read=%s input=%s",
         response.usage.cache_read_input_tokens, response.usage.input_tokens)

🔍 읽는 포인트 : 두 번째 요청부터 cache_read가 0보다 크면 도구 정의 부분을 캐시에서 읽은 것입니다.

⭐ (A)와 (B)의 비용 비교는 캐싱까지 켠 상태에서 해야 공정합니다. 3.2 결과표의 "평균 입력 토큰" 옆에 cache_read 평균을 함께 적으세요.

---

5. 디버깅 — 어떤 도구를 왜 골랐나

5.1 남길 로그

[REQ-7c21] user=E1024 intent=휴가조회(high) toolset=휴가조회[2]
[REQ-7c21] step=1 stop_reason=tool_use tool=get_leave_balance input={"year": 2026}
[REQ-7c21] step=1 result_len=48 is_error=false
[REQ-7c21] step=2 stop_reason=end_turn answer_len=31 in=1830 out=42 cache_read=1610

🔍 읽는 포인트 : 같은 요청 ID (REQ-7c21)로 한 질문이 거친 단계를 묶습니다. 볼 칸은 intent, toolset, tool, input, stop_reason — "어떤 후보를 줬고, 무엇을 골랐고, 어떤 인자를 채웠는가".

5.2 오류를 거꾸로 따라가기

💡 모델이 도구 호출 전에 짧은 text 블록으로 이유를 남기는 경우도 있습니다. 로그에 함께 남기면 단서가 됩니다. 단, 3차시의 판단 근거 필드와 마찬가지로 증명이 아니라 단서 입니다.

⚠️ 로그에는 질문 원문과 도구 결과가 남습니다. 개인정보가 함께 남으므로 마스킹 이 필요합니다(8차시).

앞으로 다시 만납니다 — 11차시에서 이 로그를 직접 쓰는 대신 트레이싱 도구 가 단계별로 기록하게 합니다.

---

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

지시

오피스봇 읽기 도구를 6개로 늘리고(휴가 잔여, 휴가 사용 이력, 티켓 상태, IT 공지, 회의실 조회, 사내 연락처),
도구 선택 정확도를 두 방식으로 비교해줘.

참고 공식 문서: Anthropic Tool use 문서(도구 설명 작성 권장사항), 토큰 세기, 프롬프트 캐싱

목표:
1. eval/tool_eval_v0.csv: [번호 | 질문 | 기대 도구(없음 포함) | 기대 인자] 30문항.
   "도구 없음" 5문항, 비슷한 도구 사이 헷갈리는 질문 5문항, 둘 이상 필요한 질문 3문항 포함
2. 구성 A(도구 6개 전부), 구성 B(4차시 분류기 → 의도별 도구 세트) 각각 실행, 각 2회
3. 결과표: [구성 | 정답 도구 | 오선택 | 불필요 호출 | 누락 | 인자 오류 | 평균 입력 토큰 | 평균 cache_read]
4. 모든 호출을 요청 ID로 묶은 로그로 남길 것 (intent, toolset, tool, input, stop_reason, usage)
5. 오선택 문항마다 [질문 | 기대 | 실제 | 그때 후보 도구 목록]

제약: 도구 설명을 고치는 것은 이번 실습 범위가 아님 — 먼저 현재 상태를 잴 것. tool_choice 강제 금지.
추측하지 말고 실행 명령과 실행 출력 원문을 붙여.
보고 형식: 위 결과표 + 오선택 표 + 로그 원문 10줄

받을 증거

• 결과표와 오선택 문항 표
• 요청 ID로 묶인 로그 원문 일부

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 7차시 노트만 근거로 6문제를 내줘. 비전공자 기준으로.
"도구가 늘면 생기는 세 문제", "모델이 고름과 분류기가 좁힘의 비교", "도구 선택 평가셋과 도구 없음 문항", "의도별 도구 세트와 캐싱의 충돌", "로그로 원인 찾기"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.