멀티 에이전트

지도 위치 : 3일차 · README 4장의 ⑤ 협업 층 | 이전: 20차시 복합 요청 분해 처리 | 다음: 22차시 오케스트레이션 키워드 : 에이전트 분리 기준, 전문화, 입출력 계약

이 차시를 다 읽으면

1. 멀티에이전트가 발전된 형태가 아니라 맞바꿈 이라는 것을 축 ⑤와 문장 1로 설명할 수 있다.
2. 에이전트를 나눌 때와 나누지 말아야 할 때 를 네 가지 기준(도구 · 권한 · 지식 · 모델 크기)으로 판단할 수 있다.
3. 전문 에이전트를 유와 종차로 정의하고, 전문화의 세 요소를 말할 수 있다.
4. 에이전트 사이의 입출력 계약 을 스키마로 정하고, 계약과 내부 구현을 축 ②로 구별할 수 있다.
5. 오피스봇의 인사 · IT · 규정 에이전트 명세표를 쓰고, 에이전트별 모델과 단독 평가셋 을 정할 수 있다.
6. 에이전트 사이에 일을 넘길 때 생기는 비용(정보 손실 · 토큰 · 지연)을 댈 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 "에이전트를 언제, 어떤 기준으로 나누고, 나눈 것들은 무엇으로 서로 연결되나?" 입니다. 앞 차시(20차시)에서 워커는 지시 한 줄을 받아 처리하는 부품이었습니다. 이번에는 워커를 자기 도구 · 자기 지식 · 자기 권한을 가진 전문 에이전트 로 키웁니다. 그 전에, 나누는 것이 정말 필요한지부터 묻습니다.

---

1. ⭐ 축 ⑤ — 멀티에이전트는 발전형이 아니다

1.1 정의

멀티에이전트 시스템 — [에이전트 시스템]인데, [ 역할이 다른 여러 에이전트가 정해진 형식으로 결과를 주고받으며 하나의 요청을 처리한다 ]는 점에서 에이전트 하나가 모든 도구를 쥐고 처리하는 단일 에이전트와 구별된다.

전문 에이전트 — [에이전트]인데, [ 좁은 시스템 프롬프트 · 작은 도구 세트 · 자기 지식 범위만 가지고 한 분야만 처리한다 ]는 점에서 모든 일을 받는 범용 에이전트와 구별된다.

1.2 맞바꿈 — 무엇을 얻고 무엇을 내주나

⭐ README의 문장 1을 다시 꺼냅니다 — "에이전트 하나로 되면 멀티에이전트를 만들지 않는다." 앞에서 배운 다중 도구 라우팅(7차시)에서 도구가 많아질수록 선택이 흔들린다고 했습니다. 그 흔들림이 평가셋으로 확인될 때 나누는 것이지, "멀티에이전트가 더 고급이라서" 나누는 것이 아닙니다.

1.3 반례 — 이건 멀티에이전트가 아닙니다

마지막 반례가 실무에서 가장 흔합니다. 프롬프트에 "너는 인사 담당이다"라고 써도 모든 도구를 쥐고 있다면 다른 직원의 정보를 조회할 수 있습니다. 전문화의 실체는 프롬프트가 아니라 도구 목록과 권한 입니다.

💡 비유 (기억 보조용) — 혼자 다 하는 동네 가게와 부서가 나뉜 회사. 회사는 전문화되지만 결재 · 인수인계 비용 이 생깁니다. 손님이 적으면 가게가 낫습니다.

---

2. 분리 기준 — 나눌 때와 나누지 말 때

2.1 나눌 때

2.2 나누지 말 때

---

3. 전문화 — 세 요소

⚠️ "범위 밖일 때 돌려줄 것"이 빠지기 쉽습니다. 인사 에이전트가 노트북 질문을 받으면 아는 척 답하지 말고 out_of_scope를 돌려줘야, 관리 에이전트(22차시)가 다른 담당에게 넘길 수 있습니다. 그래서 이 값이 다음 절의 계약에 들어갑니다.

---

4. 축 ② — 입출력 계약

4.1 정의

입출력 계약 — [인터페이스 약속]인데, [ 에이전트가 무엇을 받고 무엇을 돌려주는지만 스키마로 정하고 내부 방식은 정하지 않는다 ]는 점에서 프롬프트 · 도구 · 모델 같은 내부 구현과 구별된다.

앞에서 배운 도구 정의(5차시)에서 도구의 선언 (이름 · 설명 · 인자 형식)과 실제 함수 를 축 ②로 갈랐습니다. 에이전트도 같습니다. 다른 에이전트는 계약만 보고, 계약 안쪽은 마음대로 바꿔도 됩니다.

from pydantic import BaseModel
from typing import Literal

class AgentRequest(BaseModel):
    task: str                                # 무엇을 해 달라는지 (한 줄)
    requester_id: str                        # 코드가 로그인 세션에서 채움 — 모델이 채우지 않음
    context: dict[str, str]                  # 앞 작업 결과 등, 필요한 것만

class AgentResult(BaseModel):
    status: Literal["done", "not_found", "out_of_scope", "needs_approval", "error"]
    answer: str
    sources: list[str]                       # 근거 (규정 조항, 조회한 도구 이름)
    confidence: Literal["high", "low"]

🔍 읽는 포인트

• requester_id — 코드가 로그인 세션에서 채웁니다. 앞에서 배운 권한 경계(8차시)처럼, 에이전트 사이를 건너도 신원은 모델이 말한 값이 아니라 세션 값입니다.
• status: Literal[...] — 성공만이 아니라 못 했다는 것도 정해진 값으로 돌려줍니다. 받는 쪽(관리 에이전트, 22차시)이 이 값으로 다음 길을 고릅니다.
• sources — 근거가 계약에 들어 있어야 종합 단계에서 출처가 사라지지 않습니다(14차시).
• ⭐ 계약에 내부 구현은 없습니다. 인사 에이전트가 안에서 루프를 돌든, 도구를 한 번만 부르든, 모델을 바꾸든 이 형식만 지키면 다른 에이전트는 영향을 받지 않습니다.

4.2 반례 — 계약이 아닌 것

---

5. 오피스봇 적용 — 세 에이전트 명세표

5.1 에이전트별 모델 선택

⚠️ 가격과 모델 이름은 바뀝니다. 공식 가격 페이지를 확인 하세요. 그리고 "가벼운 일이니 작은 모델"은 가설 입니다. 6절의 단독 평가셋에서 작은 모델의 점수가 기준을 넘는지 확인한 뒤에 정합니다.

---

6. 단독 시험과 넘겨주는 비용

6.1 단독 시험 — 에이전트마다 따로 평가셋

멀티에이전트 전체를 한꺼번에 시험하면, 답이 틀렸을 때 어느 에이전트 탓인지 알 수 없습니다. 계약이 있으므로 에이전트 하나를 AgentRequest만 넣어 따로 시험할 수 있습니다.

(빈칸 양식입니다. 실측 후 채우세요. 같은 문항으로 모델만 바꿔 돌리면 5.1의 모델 선택 근거가 됩니다.)

⭐ 평가셋에는 범위 밖 문항 을 꼭 넣습니다. 전문 에이전트의 가장 흔한 실패는 틀린 답이 아니라, 자기 일이 아닌데 아는 척 답하는 것 입니다.

6.2 넘겨주는 비용

앞으로 다시 만납니다 — 22차시에서 관리 에이전트(Supervisor)가 이 세 에이전트에게 일을 맡기고 AgentResult를 모아 답을 종합합니다. 그때 넘겨주는 비용 전체에 총 반복 · 총 비용 상한 을 겁니다. 23차시에서는 needs_approval을 받은 흐름이 사람의 승인을 기다립니다.

---

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

지시

오피스봇의 단일 에이전트를 인사 · IT · 규정 전문 에이전트 셋으로 나눠줘.
참고 공식 문서: Claude API 도구 사용(tool use), 구조화 출력, 모델 개요와 가격 페이지.
구조: 5절 명세표대로. 세 에이전트 모두 AgentRequest를 받고 AgentResult를 돌려줄 것 (Pydantic 검증).
제약:
- 에이전트마다 명세표의 도구만 등록. 다른 에이전트의 도구를 넘겨주지 말 것.
- requester_id는 로그인 세션에서만 채울 것. 도구 함수 안에서 requester_id == 대상 검사.
- 범위 밖 요청은 status="out_of_scope"로 돌려줄 것.
- 쓰기 도구(create_ticket 등)는 테스트 DB에서만. 실제 시스템 연결 전에는 나에게 승인받을 것.
테스트: 에이전트별 평가셋 15문항(범위 밖 5문항 포함)을 단독으로 실행.
  hr은 claude-haiku-5-5와 claude-sonnet-5-5 두 모델로 각각 돌려 비교.
보고 형식: 6.1 표를 채우고, 오답 문항은 [문항 | 기대 status | 실제 status | 답 | 원인 추정] 표로.
  단일 에이전트 구현과 같은 평가셋 점수 · 평균 토큰도 나란히.
추측하지 말고 실행 출력 원문을 붙여.

받을 증거

• 세 에이전트의 등록된 도구 목록 출력 (코드에서 실제로 넘긴 목록)
• 6.1 표, 오답 표, 단일 에이전트와의 점수 · 토큰 비교
• hr 에이전트에 다른 직원 사번으로 휴가를 물은 실행 기록

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 21차시 노트만 근거로 비전공자용 5문제를 내줘.
"멀티에이전트는 발전형이 아니다", "나눌 때와 나누지 말 때", "입출력 계약과 내부 구현(축 ②)", "넘겨주는 비용"은 반드시 포함해줘.
내가 답한 뒤에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.