멀티 에이전트

지도 위치 : 1일차 · README 4장 ② 행동 층의 문지기 — 도구 실행에 선을 긋는다 | 이전: 7차시 다중 도구 라우팅 | 다음: 9차시 에이전트 루프 직접 구현 키워드 : 권한 경계, 마스킹, 예외 처리

이 차시를 다 읽으면

1. 인증과 인가를 유와 종차로 구별하고, ⭐ 권한은 프롬프트가 아니라 도구 코드에서 검사하는 이유를 말할 수 있다.
2. 사번을 세션에서 가져오고 모델이 준 인자를 믿지 않는 코드를 알아볼 수 있다.
3. 역할별 도구 목록(최소 권한)과 쓰기 도구의 확인 단계를 설계할 수 있다.
4. 외부 API로 나가기 전과 로그에 남기기 전에 마스킹 할 자리를 짚을 수 있다(축 ④).
5. 도구 실패를 다섯 종류로 나눠 모델에게 줄 메시지와 로그를 분리 하고, 행동 시험으로 확인할 수 있다.

---

0. 이 차시의 판별 축

이 차시의 질문은 "모델이 속거나 틀려도 사고가 나지 않게 하려면, 어디에 무엇으로 선을 그어야 하나?" 입니다. 앞에서 "모델은 요청만, 실행은 코드"를 배웠습니다(5차시). 이 차시는 그 코드 쪽 문지기 를 완성합니다. 그리고 1일차를 정리합니다.

---

1. ⭐ 권한 경계 — 프롬프트가 아니라 코드에서

1.1 인증과 인가

인증 (Authentication) — [보안 절차]인데, [ "당신은 누구인가"를 확인한다 (로그인)]는 점에서 할 수 있는 일을 정하는 인가와 구별된다.

인가 (Authorization) — [보안 절차]인데, [ 확인된 사용자가 "이것을 해도 되는가"를 판정한다 ]는 점에서 신원만 확인하는 인증과 구별된다.

1.2 사번은 세션에서, 모델 인자는 불신

def get_leave_balance_tool(raw_input: dict, session: Session) -> ToolResult:
    args = LeaveBalanceArgs.model_validate(raw_input)        # 6차시: 인자 검증
    target = getattr(args, "employee_id", None) or session.employee_id  # 팀장용 도구에만 인자 존재
    if target != session.employee_id and not session.can_view(target):
        return ToolResult.denied("본인 또는 소속 팀원의 연차만 조회할 수 있습니다.")
    return ToolResult.ok(get_leave_balance(target, args.year))

🔍 읽는 포인트 : session.employee_id는 로그인 시스템이 넣은 값 이고, args는 모델이 채운 값 입니다. if 한 줄이 "요청자 = 대상인가, 아니면 볼 권한이 있는가"를 검사합니다. 이 검사는 모델이 무엇을 말하든 같은 결과 를 냅니다(결정론, 3차시).

⭐ 세 문장 중 문장 2 — 모델은 판단하고, 코드는 지킨다. 권한은 "어기면 안 되는 선"이므로 부탁하지 않고 강제합니다. 프롬프트의 금지 문구(3차시)는 답의 말투 를 다듬는 보조일 뿐입니다.

1.3 최소 권한 — 역할별 도구 목록

최소 권한 원칙 — [보안 원칙]인데, [ 일에 필요한 최소한의 권한만 준다 ]는 점에서 편의를 위해 넓게 열어 두는 방식과 구별된다.

tools = TOOLS_BY_ROLE[session.role]       # 역할에 없는 도구는 모델이 존재조차 모름

🔍 읽는 포인트 : 이 한 줄이 1.2의 if보다 앞선 방어선 입니다. 모델에게 보이지 않는 도구는 요청할 수 없습니다. 그래도 1.2의 검사는 지우지 않습니다 — 방어선은 겹쳐 둡니다.

1.4 쓰기 도구는 확인 단계

멱등성 — [연산의 성질]인데, [ 같은 요청을 여러 번 보내도 결과가 한 번 보낸 것과 같다 ]는 점에서 보낼 때마다 결과가 쌓이는 연산과 구별된다.

앞으로 다시 만납니다 — 23차시에서 이 확인 단계를 그래프의 승인 게이트 (멈추고 상태를 저장한 뒤 사람의 승인으로 재개)로 직접 구현합니다.

---

2. 마스킹 — 무엇이 밖으로 나가는가

2.1 정의와 자리

마스킹 — [개인정보 보호 기법]인데, [ 민감한 값을 일부 또는 전부 가린 채로 전달 · 저장한다 ]는 점에서 값을 복원 가능하게 바꾸는 암호화와 구별된다.

 내 서버 (로컬)                                         밖 (원격)
 ┌─────────────────────────────────────┐
 │ 사용자 질문 ──┐                       │   ① 마스킹    ┌─────────────────┐
 │ 도구 결과 ────┼──▶ 프롬프트 조립 ──────┼──────────▶ │ 외부 LLM API     │
 │ 대화 이력 ────┘                       │             └─────────────────┘
 │                                     │   ② 마스킹    ┌─────────────────┐
 │ 요청 · 응답 로그 ──────────────────────┼──────────▶ │ 로그 저장소 · 트레이싱│
 └─────────────────────────────────────┘             └─────────────────┘

2.2 코드

import re

PATTERNS = [
    (re.compile(r"\d{6}-?[1-4]\d{6}"), "[주민번호]"),
    (re.compile(r"01[016789]-?\d{3,4}-?\d{4}"), "[전화번호]"),
    (re.compile(r"\d{2,6}-\d{2,6}-\d{2,6}"), "[계좌번호?]"),
]

def mask(text: str) -> str:
    for pattern, label in PATTERNS:
        text = pattern.sub(label, text)
    return text

🔍 읽는 포인트 : 패턴 목록과 바꿀 이름표만 보면 됩니다. mask()는 프롬프트 조립 직전 과 로그 기록 직전 두 곳에서 부릅니다.

⚠️ 한계 — 정규식은 모양이 정해진 값 만 잡습니다. 이름, "우리 팀 박 대리가 병가 중인데" 같은 문장 속 민감 정보는 못 잡습니다. 그래서 순서가 중요합니다. ① 애초에 안 넣기 (도구 결과 최소화) → ② 마스킹 → ③ 외부 서비스의 데이터 보관 정책 확인(회사 보안 담당 · 공식 문서).

앞으로 다시 만납니다 — 11차시에서 트레이싱 기록이 외부 서비스로 나갈 때, 17차시에서 장기 기억에 무엇을 저장하지 말지 정할 때 이 그림을 다시 씁니다.

---

3. 예외 처리 계층

3.1 다섯 종류 — 모델에게 줄 말과 로그를 분리

⭐ 원칙 — 모델에게는 짧고 대응 가능한 문장만, 자세한 내용은 로그에만. 내부 오류의 SQL 문 · 테이블 이름 · 서버 경로를 모델에게 주면 답에 섞여 사용자에게 보이고, 외부 API로도 나갑니다.

3.2 코드 — 한곳에서 감싸기

def run_tool(name: str, raw_input: dict, session: Session) -> dict:
    try:
        result = TOOL_FUNCS[name](raw_input, session)       # 각 도구는 ok / denied / not_found 반환
    except ValidationError:
        return error_result("입력 값이 올바르지 않습니다. 형식을 확인해 주세요.")
    except TimeoutError:
        log.warning("tool=%s timeout user=%s", name, session.employee_id)
        return error_result("시스템이 응답하지 않습니다. 잠시 후 다시 시도해 주세요.")
    except Exception:
        log.exception("tool=%s internal error", name)       # 자세한 내용은 로그에만
        return error_result("일시적인 오류가 발생했습니다.")
    if result.denied:
        log.warning("DENIED tool=%s user=%s input=%s", name, session.employee_id, mask(str(raw_input)))
    return result.to_tool_result()

🔍 읽는 포인트 : except 세 갈래와 if result.denied — 다섯 종류가 한 함수에서 갈립니다. 모든 갈래가 예외로 서비스를 죽이지 않고 tool_result로 돌아갑니다. log.exception만 자세한 내용을 담습니다.

---

4. 행동 시험 — 말이 아니라 행동으로 확인

코드를 읽지 않고도 확인할 수 있는 방법이 있습니다. 공격자처럼 물어보는 것 입니다.

⭐ 2와 3에서 모델이 어떻게 말하는지 는 중요하지 않습니다. 모델이 "알겠습니다, 관리자님"이라고 답해도, 도구 결과가 권한 없음이면 데이터는 나가지 않습니다. 확인할 것은 말이 아니라 도구 로그의 DENIED 기록과 응답에 숫자가 없는 것 입니다.

앞으로 다시 만납니다 — 10차시에서 사용자 질문이 아니라 도구 결과 · 문서 속에 숨은 지시 (간접 프롬프트 인젝션)를 막는 가드레일을 만듭니다.

---

5. 1일차 정리 → 2일차 예고

5.1 1일차에 쌓은 것

지금의 오피스봇 (워크플로우 — 1차시 사다리의 2칸)
질문 ─▶ 마스킹 ─▶ 의도 분류 ─▶ 역할 · 의도별 도구 세트 ─▶ 모델이 도구 요청
                                                      │
                          run_tool: 검증 → 권한 → 실행 → 예외 처리 ─▶ 결과 ─▶ 모델이 답

5.2 아직 못 하는 것 → 2일차

⭐ 2일차에 루프가 생겨도 이 차시의 문지기는 그대로 씁니다. 루프는 run_tool을 여러 번 부를 뿐, 권한 검사와 마스킹은 매번 같은 자리에서 일어납니다. 문지기를 1일차에 만든 이유입니다.

---

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

지시

오피스봇 도구 계층에 권한 · 마스킹 · 예외 처리를 넣고, 행동 시험을 돌려줘.

참고 공식 문서: Anthropic Tool use 문서(is_error), Python re · logging 문서

목표:
1. Session(employee_id, role)을 로그인 대신 테스트 픽스처로 만들 것 (직원 E1024, 팀장 E3001, IT 담당 E5001)
2. 역할별 도구 목록 TOOLS_BY_ROLE. 일반 직원 도구에는 employee_id 인자를 두지 말 것
3. 모든 도구 실행은 run_tool 한 곳을 거치게: 검증 실패 / 권한 없음 / 없음 / 타임아웃 / 내부 오류
   → 모델에는 짧은 문장 + is_error, 자세한 내용은 로그에만
4. mask(): 주민번호 · 전화번호 · 계좌 패턴. 외부 API 요청 직전과 로그 기록 직전 두 곳에서 호출
5. 쓰기 도구 request_equipment는 실행하지 말고 초안 테이블에만 저장
테스트: 노트 4절의 행동 시험 6개를 자동화

제약: 권한 검사를 프롬프트로 대신하지 말 것. 모델이 채운 사번을 그대로 쓰지 말 것.
위험 작업(실제 DB 쓰기, 외부 서비스 설정 변경)은 실행 전에 나에게 승인을 받을 것.
추측하지 말고 실행 명령과 실행 출력 원문을 붙여.
보고 형식: [시나리오 | 로그인 사용자 | 모델이 요청한 도구·인자 | run_tool 판정 | 최종 답 | 로그 한 줄] 표

받을 증거

• 행동 시험 6개의 결과표와 로그 원문
• 시나리오 4의 외부 API로 보낸 요청 본문 (마스킹 결과가 보여야 함)
• 시나리오 6 후 신청 테이블 조회 결과(0건)

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 8차시 노트만 근거로 6문제를 내줘. 비전공자 기준으로.
"인증과 인가", "권한은 프롬프트가 아니라 도구 코드에서(사번은 세션에서)", "마스킹할 두 자리", "예외 다섯 종류와 메시지·로그 분리", "행동 시험에서 볼 것"은 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.