멀티 에이전트

지도 위치 : 1일차 · README 4장 ② 행동 층 — 실제 사내 데이터에 닿는 도구 | 이전: 5차시 Function Calling 원리 | 다음: 7차시 다중 도구 라우팅 키워드 : 도구 함수 설계, 인자 스키마, 결과 반환

이 차시를 다 읽으면

1. 좋은 도구의 네 원칙( 한 가지 일 · 이름과 설명이 곧 프롬프트 · 인자는 최소 · enum )으로 도구 설계를 검토할 수 있다.
2. 읽기 ↔ 쓰기 축으로 도구를 나누고, 왜 조회 도구부터 만드는지 말할 수 있다.
3. 모델에게 SQL을 쓰게 하지 않고 정해진 함수 로 사내 DB에 연결하는 이유를 설명할 수 있다.
4. 모델이 채운 인자를 Pydantic으로 다시 검증 하는 이유를 말할 수 있다.
5. 도구 결과를 필요한 필드만 · 짧게 · 개인정보 최소로 돌려주고, "없음"과 "오류"(is_error)를 구별할 수 있다.

---

0. 이 차시의 판별 축

이 차시의 질문은 "모델이 실제 사내 데이터를 쓰게 하되, 안전하고 쓸모 있게 하려면 도구를 어떻게 만들어야 하나?" 입니다. 앞에서 도구 호출 한 바퀴를 돌렸습니다(5차시). 이번에는 그 도구의 안쪽 (함수 설계 · 인자 검증 · 결과 형식)을 만듭니다.

---

1. 좋은 도구 설계

1.1 정의

도구 함수 — [앱의 함수]인데, [ 모델의 요청을 받아 실행되도록 이름 · 설명 · 인자 스키마와 함께 공개된다 ]는 점에서 앱 내부에서만 쓰이는 일반 함수와 구별된다.

1.2 네 원칙

1.3 ❌ / ⭕

# ❌ 만능 · 모호
{"name": "query", "description": "데이터를 조회한다",
 "input_schema": {"type": "object", "properties": {"sql": {"type": "string"}}}}

# ⭕ 한 가지 일 · 언제 쓸지까지
{"name": "get_ticket_status",
 "description": "현재 사용자가 접수한 IT 지원 티켓의 상태를 조회한다. "
                "'내 티켓', '접수한 장애 어떻게 됐어' 같은 질문에 사용. "
                "새 장애 접수에는 사용하지 않는다.",
 "input_schema": {
     "type": "object",
     "properties": {
         "status_filter": {"type": "string", "enum": ["전체", "처리중", "완료"],
                           "description": "어떤 상태의 티켓을 볼지. 언급이 없으면 전체"}},
     "required": ["status_filter"],
     "additionalProperties": False},
 "strict": True}

🔍 읽는 포인트 : ⭕ 쪽의 description 마지막 문장 "새 장애 접수에는 사용하지 않는다" — 쓰지 말 때를 적었습니다. 그리고 enum 세 값. 사번 인자는 없습니다.

---

2. ⭐ 읽기 ↔ 쓰기 — 조회 도구부터

⭐ 첫 버전은 조회 도구만 붙입니다. 모델이 도구를 잘못 고르거나, 10차시에서 볼 프롬프트 인젝션에 속더라도 조회밖에 못 하면 사고가 작습니다.

앞으로 다시 만납니다 — 쓰기 도구는 8차시에서 읽기 도구와 분리된 목록 으로 두고, 23차시에서 승인 게이트를 거쳐 실행합니다.

---

3. 사내 DB 연동 — 모델에게 SQL을 쓰게 하지 않는다

3.1 왜

이것이 세 문장 중 문장 2 — 모델은 판단하고(어떤 도구 · 어떤 연도), 코드는 지킨다(무엇을 어떻게 조회) 의 모양입니다.

3.2 함수

def get_leave_balance(session_user: str, year: int) -> dict:
    row = db.execute(
        "SELECT granted, used FROM leave_balance WHERE emp_id = ? AND year = ?",
        (session_user, year),                         # 자리표시자 — 값은 따로 전달
    ).fetchone()
    if row is None:
        return {"found": False, "message": f"{year}년 연차 기록이 없습니다."}
    return {"found": True, "year": year, "remaining_days": row.granted - row.used}

🔍 읽는 포인트

• 첫 인자 session_user — 모델이 아니라 로그인 세션 에서 옵니다(8차시).
• ? 자리표시자 — 값을 SQL 문장에 이어 붙이지 않습니다. 이어 붙이면 값 속에 SQL을 숨겨 넣는 공격(SQL 인젝션)이 가능해집니다.
• remaining_days를 코드가 계산 합니다. 뺄셈을 모델에게 맡기지 않습니다(결정론, 3차시).

---

4. 인자 검증 — 모델이 채운 값도 바깥 입력이다

strict: True는 모양 (정수인가, enum 안인가)을 보장합니다(5차시). 그러나 값의 범위 는 모릅니다. year: 1999도 정수입니다.

from pydantic import BaseModel, Field, ValidationError

class LeaveBalanceArgs(BaseModel):
    year: int = Field(ge=2020, le=2030, description="조회 연도")

def run_get_leave_balance(raw_input: dict, session_user: str) -> dict:
    try:
        args = LeaveBalanceArgs.model_validate(raw_input)
    except ValidationError:
        return {"is_error": True, "content": "연도는 2020~2030 사이여야 합니다."}
    return {"content": get_leave_balance(session_user, args.year)}

🔍 읽는 포인트 : model_validate(raw_input) 한 줄이 문지기 입니다. 실패하면 함수를 실행하지 않고 고칠 수 있는 메시지 를 돌려줍니다. 모델은 이 메시지를 읽고 인자를 고쳐 다시 요청할 수 있습니다.

---

5. 결과 반환

5.1 원칙

5.2 ❌ / ⭕

# ❌ 레코드 통째로
{"emp_id": "E1024", "name": "김민수", "rrn": "900101-1******", "phone": "010-....",
 "dept": "재무팀", "salary_grade": "S3", "granted": 15, "used": 8, "updated_at": "..."}

# ⭕ 질문에 필요한 것만
{"found": True, "year": 2026, "remaining_days": 7}

🔍 읽는 포인트 : ❌ 쪽은 연차를 물었는데 주민번호 · 전화 · 급여 등급까지 외부로 보냅니다. 모델이 답에 쓰지 않더라도 이미 나간 것입니다.

5.3 "없음"과 "오류"를 구별

{"type": "tool_result", "tool_use_id": block.id,
 "content": "오류: 인사 시스템에 연결하지 못했습니다.", "is_error": True}

🔍 읽는 포인트 : is_error: True 한 줄. ⚠️ "없음"을 오류로 보내면 모델은 "시스템 오류"라고 안내하고, "오류"를 "없음"으로 보내면 "티켓이 없습니다"라고 틀린 사실을 말합니다.

5.4 오피스봇의 두 조회 도구

💡 get_ticket_status는 티켓이 수십 건일 수 있으므로 최근 5건 처럼 상한을 둡니다. 결과 길이가 곧 비용입니다.

앞으로 다시 만납니다 — 두 도구가 나란히 놓이면 모델이 어느 쪽을 고르는가 가 문제가 됩니다. 7차시에서 도구 선택 정확도를 잽니다.

---

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

지시

오피스봇에 조회 도구 두 개(get_leave_balance, get_ticket_status)를 실제 DB 연동 구조로 만들어줘.

참고 공식 문서: Anthropic Tool use 문서(input_schema, strict, is_error), Pydantic 공식 문서, Python sqlite3 문서

목표:
1. SQLite 가짜 DB: 직원 5명, leave_balance(emp_id, year, granted, used), tickets(ticket_id, emp_id, title, status, updated)
2. 도구 함수는 사번을 인자로 받지 말고 session_user로 받을 것. SQL은 자리표시자(?)만 사용
3. 인자는 Pydantic으로 다시 검증 (year 2020~2030, status_filter enum)
4. 결과는 표에 정한 필드만. 없음은 found False + 문장, 시스템 오류는 is_error True
5. get_ticket_status는 최근 5건까지만
테스트: ① 연차 조회 ② 기록 없는 연도 ③ year=1999 ④ 티켓 처리중만 ⑤ 티켓 0건인 직원 ⑥ DB 파일을 잠시 없애 오류 유도

제약: 모델이 SQL을 쓰는 도구를 만들지 말 것. 쓰기 도구는 이번에 만들지 말 것.
추측하지 말고 실행 명령과 실행 출력 원문을 붙여.
보고 형식: [시나리오 | 모델이 채운 인자 | 검증 결과 | tool_result 원문 | is_error | 최종 답] 표

받을 증거

• 시나리오 6개의 표와 tool_result 원문 (모델에게 실제로 보낸 글)
• 두 도구의 선언 JSON 원문

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 6차시 노트만 근거로 6문제를 내줘. 비전공자 기준으로.
"좋은 도구의 네 원칙", "읽기 도구부터", "SQL을 모델에게 맡기지 않는 이유", "strict와 Pydantic 검증의 차이", "없음과 오류의 구별"은 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.