정리와 체크리스트

22장에서 배운 것

오케스트레이션 — 여러 에이전트가 지휘 아래에서 함께 일하도록 엮는 일. 접수 · 위임 · 종합 세 역할을 채웁니다.
Supervisor 패턴 — 총괄 에이전트 하나가 문의를 받고, 전문 에이전트에게 맡기고, 보고를 묶어 답합니다.
에이전트를 도구로 — 전문 에이전트를 함수로 감싸 @tool을 붙이면 Supervisor의 도구가 됩니다. 위임은 도구 호출입니다.
세 에이전트의 협업 — 한 문의에 주문조회 → 정책안내 → 요청처리가 차례로 움직입니다. 앞의 보고에서 알아낸 사실을 Supervisor가 뒤의 요청문에 담아 넘깁니다.
핸드오프 — 에이전트가 대화를 동료에게 통째로 넘기는 다른 방식. 우리는 추적과 통제가 쉬운 중앙 지휘를 골랐습니다.
별 모양 구조 — 전문 에이전트의 도구 목록에 동료가 없어, 위임은 Supervisor만 할 수 있습니다.
recursion_limit — Supervisor의 실행 단계 상한. 넘으면 GraphRecursionError.
코드 보증 — 처리번호와 티켓번호는 코드가 기록 파일을 실행 전후로 비교해 [시스템 확인] 줄로 붙입니다. 새 기록이 없으면 없다고 붙이고, 아무 도구도 불리지 않았으면 코드가 상담원에게 접수합니다(폴백).
운영 원칙 12개 — 위임 · 고객 경험 · 사실 · 처리 · 범위 다섯 묶음입니다. 요청하면 그 자리에서 처리하고, 묻기만 하면 답한 뒤 묻습니다.

한눈에 보는 핵심

from haru_supervisor import build_supervisor, run_supervisor
from haru_tools import CustomerSession

supervisor = build_supervisor(CustomerSession("C003"))       # 만들기

answer, history = run_supervisor(supervisor, "첫 질문")        # 첫 턴
answer, history = run_supervisor(supervisor, "그거는요?", history)   # 이력을 넣어 이어 가기

누가 하나	하는 일
Supervisor (모델)	위임할 에이전트 고르기, 요청문 쓰기(앞에서 알아낸 주문번호·등급을 담아), 보고를 한 답으로 묶기
전문 에이전트 (모델)	자기 도구로 확인하거나 처리하고 글로 보고하기
처리 도구 (코드)	처리해도 되는지 판정하기, 기록 남기기, 처리번호 만들기
위임 도구 (코드)	전문 에이전트 실행, 기록의 전후 비교와 번호 붙이기, 폴백
구조	전문 에이전트끼리 부를 길을 없애기, 실행 단계 상한

고객의 말	움직이는 에이전트	남는 것
조회 ("배송 어디까지 왔어요?")	주문조회	없음
묻기만 한 문의 ("교환하면 배송비 얼마예요?")	주문조회 → 정책안내	없음
처리 요청 ("교환해 주세요", "배송지 바꿔 주세요")	주문조회 → (정책안내) → 요청처리	처리번호 `A…`
처리할 수 없는 일 ("로그인이 풀려요", "상담원 연결해 주세요")	요청처리	티켓번호 `T…`

체크리스트

[ ] 전문 에이전트 셋만으로 복합 문의를 처리할 수 없는 이유를 설명할 수 있다.
[ ] "에이전트를 도구로"가 가능했던 까닭을 전문 에이전트의 입출력 모양으로 설명할 수 있다.
[ ] 누구에게 위임할지 정하는 것은 모델이고, 실행하는 것은 코드라는 점을 말할 수 있다.
[ ] 전문 에이전트가 앞 대화와 다른 에이전트의 보고를 모른다는 사실과, 그래서 Supervisor가 무엇을 해야 하는지 설명할 수 있다.
[ ] 고객이 말하지 않은 주문번호가 요청처리 에이전트에게 어떻게 전달되는지 설명할 수 있다.
[ ] Supervisor 패턴과 핸드오프의 차이를 두 가지 이상 말할 수 있다.
[ ] "부르지 마라"고 쓰는 것과 도구 목록에 넣지 않는 것의 차이를 설명할 수 있다.
[ ] recursion_limit이 무엇을 세고, 넘으면 어떤 오류가 나는지 안다.
[ ] ask_action_agent가 기록을 실행 전후로 비교해 무엇을 붙이는지, 새 기록이 없을 때는 무엇을 붙이는지 말할 수 있다.
[ ] run_supervisor가 돌려주는 값 두 개와, 대화를 이어 가는 방법을 안다.
[ ] 묻기만 한 문의와 처리를 요청한 문의를 Supervisor가 어떻게 다르게 다루는지, 운영 원칙 6번으로 설명할 수 있다.
[ ] 고객이 등급을 말하지 않아도 등급에 맞는 정책을 답하는 순서를 운영 원칙 9번으로 설명할 수 있다.
[ ] lesson22_supervisor.py를 실행한 뒤 답변의 처리번호·티켓번호가 memory_store의 두 파일에 있는 번호와 같은 것을 확인했다.

한 줄 핵심

Supervisor는 직접 일하지 않습니다. 누구에게 시킬지 고르고, 앞에서 알아낸 것을 다음 요청에 담아 넘기고, 보고를 묶습니다. 처리해도 되는지와 처리됐는지는 그 사이에서 코드가 받칩니다.