Skip to Content

작은 도구 연결 실습

실습복습
관련 기초 개념

개요

조회·계산·검증을 분리한 처리 흐름을 검증한다.

먼저 권한·승인·멱등성·재시도, 문서·PDF·Excel 추출과 대사의 핵심 개념을 확인하세요.

핵심 개요

작은 도구 연결은 모델 없이도 실행 계약부터 검증할 수 있습니다. 도구 이름과 인수를 허용 목록으로 제한하고, 검증된 인수만 실제 함수에 전달합니다. 자유 텍스트를 임의 코드로 실행하지 않습니다.

조회 도구와 변경 도구는 부작용이 다릅니다. 우선 읽기 전용 예제로 성공·없는 대상·잘못된 인수를 구분한 뒤 변경 작업에 승인과 멱등성을 더합니다.

필요한 용어

  • Dispatcher: 허용된 도구 이름을 실제 함수에 연결하는 실행기
  • 부작용: 함수 반환값 외에 저장·삭제·전송 등 외부 상태가 변하는 효과

작동 과정

  1. 단일 목적의 함수와 입력·오류 계약을 작성합니다.
  2. 허용 목록과 인수 검사를 거쳐 함수를 호출합니다.
  3. 정상·없는 대상·형식 오류를 자동 검사합니다.

풀이 예제

아래 입력과 기록은 직접 만든 교육용 가상 자료입니다.

입력·조건

get_stock 도구는 상품 ID만 받아 재고 수를 돌려줍니다. 상품 B의 재고는 7입니다.

판단·결과

B 조회는 7, 없는 상품은 명시적인 not_found 결과로 처리합니다.

이렇게 판단한 이유

오류를 정상 값 0으로 바꾸면 재고 없음과 상품 없음이 섞입니다. 모델이 후속 판단을 하려면 상태를 구분해야 합니다.

로컬 실행 예제

실행 파일 받기

Python 3.12. python tool_dispatch.py

python tool_dispatch.py
"""Allowlist, argument contract, authorization, and explicit not-found."""
def dispatch(name, args, *, allowed):
    if name != 'order_status':
        return {'status': 'unknown_tool'}
    if type(args) is not dict or set(args) != {'order_id'} or type(args['order_id']) is not str:
        return {'status': 'invalid_arguments'}
    if not allowed:
        return {'status': 'forbidden'}
    orders = {'A1': 'shipped'}
    value = orders.get(args['order_id'])
    return {'status': 'ok', 'value': value} if value is not None else {'status': 'not_found'}
assert dispatch('order_status', {'order_id':'A1'}, allowed=True) == {'status':'ok','value':'shipped'}
assert dispatch('delete_order', {}, allowed=True)['status'] == 'unknown_tool'
assert dispatch('order_status', {'order_id':0}, allowed=True)['status'] == 'invalid_arguments'
for malformed in (None, 42, ['order_id']):
    assert dispatch('order_status', malformed, allowed=True)['status'] == 'invalid_arguments'
assert dispatch('order_status', {'order_id':'A1'}, allowed=False)['status'] == 'forbidden'
assert dispatch('order_status', {'order_id':'X'}, allowed=True)['status'] == 'not_found'
print('PASS: success, allowlist, invalid arguments, forbidden, not found')

기대 결과: 정상·알 수 없는 도구·잘못된 인수·권한 거절·없는 주문 검사

2026-10-22 Python 3.12.14에서 정상·허용 목록·인수·권한·없는 대상 경로를 다시 실행했습니다. None·숫자·배열 등 잘못된 JSON 인수 13개가 예외 없이 invalid_arguments로 거절되는 회귀검사도 통과했습니다. 실제 모델이나 외부 API를 호출하지 않습니다.

흔한 실패와 복구

알 수 없는 도구 이름을 eval 같은 임의 실행으로 연결하지 않습니다. 등록된 함수 외에는 거절합니다.

확인 문제

작은 도구 실행기를 검증할 때 필요한 사례는?

  1. 정상 요청 한 건만
  2. 정상·없는 대상·잘못된 인수·권한 오류
  3. 모델이 설명한 예상 결과만

풀이 기록 기능을 불러오는 중…

해설 보기

정답: B. 정상·없는 대상·잘못된 인수·권한 오류

정상·없는 대상·잘못된 인수·권한 오류 알 수 없는 도구 이름을 eval 같은 임의 실행으로 연결하지 않습니다. 등록된 함수 외에는 거절합니다.

참고 자료

  1. MCP: Architecture  — host·client·server 및 세션 경계.
  2. Python: json  — JSON의 직렬화·파싱과 자료형.

자료 확인: 2026-10-21. 사례·문항·실습은 자체 제작했습니다. 외부 서비스 호출과 실제 모델 품질 측정은 학습자가 별도 환경에서 수행합니다.

직접 적용하기

교육용 가상 상황

주문 상태 조회기를 구현할 때 허용 도구·인수·없는 주문·권한 오류를 어떻게 구분할지 정의하세요.

조회·계산·검증을 분리한 처리 흐름을 검증한다. 판단 근거와 검증할 결과를 적으세요.

답안 저장 기능을 불러오는 중…

검증 기준과 해설 보기
  1. 조회 전용 계약을 작성한다
  2. 임의 함수 실행을 막는다
  3. 정상·오류 응답을 각각 시험한다

get_order_status만 허용하고 주문 ID 형식·사용자 소유권을 검사합니다. 응답 상태를 ok·not_found·forbidden으로 구분하되 타인의 주문 존재를 노출하지 않는 정책을 적용합니다. 함수 호출 전후 입력과 결과를 검증하는 테스트를 작성합니다.

복습하기

  1. Dispatcher는 무엇을 하나요?
  2. 없는 상품을 0으로 반환하면 왜 곤란한가요?
  3. 모델 없이 검사할 수 있나요?
답변 확인 기준
  1. Dispatcher는 무엇을 하나요?

    허용 이름을 실제 함수에 연결합니다.

  2. 없는 상품을 0으로 반환하면 왜 곤란한가요?

    상품 없음과 재고 0의 의미가 섞입니다.

  3. 모델 없이 검사할 수 있나요?

    실행 계약과 함수는 직접 호출해 검사할 수 있습니다.

← 이전 강의다음 강의 →학습 기록 →