도구 호출: 모델의 제안과 실제 실행

핵심 개요

이 강의의 주문·금액·정책·호출 기록은 교육용 합성 예제입니다. 실제 API를 호출하는 실습은 아닙니다.

1. 학습 목표

이 강의를 마치면 다음을 할 수 있다.

• 모델이 만든 도구 호출 요청과 프로그램이 수행한 실제 작업을 구분한다.
• 도구의 입력 형식·서버 권한·업무 규칙을 각각 어디에서 검사할지 정한다.
• 조회 결과를 이용해 답변하되, 사용자가 요청하지 않은 변경을 막는다.
• 잘못된 인자·권한 거부·타임아웃·중복 실행에 필요한 검증을 설명한다.

2. 먼저 볼 문제: 주문 금액을 물었는데 환불까지 하면 안 된다

사용자가 상담 AI에게 묻는다.

주문 O-1042에서 환불 가능한 금액이 얼마인지 확인해줘. 환불은 실행하지 마.

모델은 주문 DB의 현재 값을 저절로 알지 못한다. 주문 정보가 학습 데이터에 들어 있더라도 현재 상태·소유자·이미 환불한 금액을 확인하는 근거가 되지 않는다. 다른 주문을 조회하거나 실제 환불을 실행하면 사용자의 의도와 권한을 벗어날 수도 있다.

필요한 것은 세 가지다. 현재 주문을 조회할 방법, 조회해도 되는 사용자인지 판단할 방법, 반환한 값이 사용자에게 올바르게 전달됐는지 확인할 방법이다. 모델의 자연어 이해는 주문 번호와 질문 의도를 파악하는 데 쓰고, DB 접근·권한·계산·실행은 프로그램의 책임으로 둔다.

3. 도구 호출의 정확한 의미

도구 호출은 모델이 사용할 도구와 입력값을 정해 프로그램에 전달하는 방식이다. 함수 호출(Function Calling)은 보통 이름과 구조화된 인자를 주고받는 도구 인터페이스를 가리킨다. 제공자에 따라 내장 도구·사용자 정의 함수·원격 도구의 실행 주체가 다를 수 있다.

이 강의는 앱이 직접 실행하는 사용자 정의 도구를 기준으로 한다. 모델은 ‘이 함수를 이 인자로 사용하자’고 제안한다. 앱은 그 요청을 받아 검증한 뒤 실행하거나 거절한다. 연결된 함수가 없다면 모델이 함수 이름을 출력해도 DB를 조회한 것은 아니다.

모델이 ‘사용자는 관리자입니다’라는 인자를 만들어도 권한은 늘어나지 않는다. 사용자 신원과 역할은 인증된 세션에서 가져온다. 도구 설명에 안전하다고 쓰여 있어도 서버의 권한 검사를 대신하지 못한다.

4. 입력·처리·출력의 흐름

중요한 분기는 앱의 검사다. 모델이 잘못된 도구를 선택해도 실행 전에 거절할 수 있어야 한다. 추가 호출은 작업 범위와 예산 안에서만 가능하며, 실패를 같은 방식으로 무한 반복하지 않는다.

출처가 되는 것은 4단계의 실제 서비스 결과다. 모델이 2단계에서 적어낸 금액이나 5단계에서 새로 상상한 주문 상태는 조회 증거가 아니다.

5. 작은 예제로 전체 과정을 따라가기

5.1 도구 계약

이번 작업에 허용하는 도구는 하나다.

스키마는 ‘문자열·필수 필드·추가 필드 금지’를 검사할 수 있다. O-1042가 실제 존재하는지, 로그인 사용자의 주문인지, 이미 환불됐는지는 서비스와 정책이 검사한다. 형식에 맞는 다른 사람의 주문 번호도 여전히 접근 금지 대상이다.

5.2 모델이 제안한 호출

다음은 제공자와 무관한 설명용 표현이며 실제 SDK의 메시지 포맷은 아니다.

{
  "call_id": "q-001",
  "tool_name": "get_refund_quote",
  "arguments": {"order_id": "O-1042"}
}

이 객체가 존재한다는 사실만으로 조회가 실행된 것은 아니다. 앱이 허용 도구인지, 인자가 맞는지, 사용자 신원이 유효한지, O-1042에 접근할 수 있는지 확인한 뒤 주문 서비스를 호출한다.

5.3 주문 서비스가 확인한 원시 자료

교육용 정책은 ‘주문 상품 합계에서 이미 환불된 금액을 뺀 나머지를 조회 시점의 가능 금액으로 반환’이라고 가정한다. 배송비·세금·기한·부분 환불 예외는 이 예에 없다.

가능 금액은 일반 계산 코드로 구한다. 자연어 모델에게 정확한 곱셈·차감을 맡길 필요가 없다. 정책 자체가 복잡해지면 별도 규칙 서비스가 책임지고, 모델이 정책을 새로 만들어 적용하지 않게 한다.

5.4 도구 결과

{
  "call_id": "q-001",
  "result": {
    "order_id": "O-1042",
    "currency": "KRW",
    "order_total": 12000,
    "refunded_amount": 0,
    "refundable_amount": 12000,
    "quote_status": "eligible",
    "as_of": "2026-10-20T14:00:00+09:00"
  }
}

금액은 이 예에서 원 단위 정수다. 실제 시스템은 통화별 최소 단위와 반올림 정책을 계약에 명시해야 한다. call_id는 어떤 요청의 응답인지 연결하며, 업무의 중복 실행을 막는 멱등성 키와 같은 개념으로 취급하지 않는다.

5.5 사용자에게 전달할 답변

조회 시점 기준, O-1042의 환불 가능 금액은 12,000원입니다. 환불은 실행하지 않았습니다.

앱은 주문 ID·통화·가능액이 도구 결과와 같은지 확인한다. ‘환불하지 않음’은 변경 도구가 실행되지 않았다는 기록으로 확인한다. 화면에 적힌 문장만 보고 실제 미실행을 판단하지 않는다.

6. JSON이 맞아도 틀릴 수 있는 네 가지

구조화 출력은 형식 오류를 줄이는 데 도움이 되지만 사실과 권한을 보장하지 않는다. 거절·출력 중단·호출 오류도 정상적인 분기로 처리한다. 모든 실패를 억지로 같은 성공 스키마 안에 넣으면 모델이나 앱이 없는 값을 채우게 될 수 있다.

7. 실제 변경 작업으로 확장하면 무엇이 추가되는가

사용자가 뒤이어 ‘이 주문에서 확인한 12,000원을 환불해줘’라고 요청했다고 가정하자. 이제 목표가 조회에서 변경으로 바뀐다. 앱 정책에 따라 구체적인 사용자 요청 자체가 충분한 승인일 수도 있고 추가 검토가 필요할 수도 있다. 모든 도구에 반복 확인창을 띄우는 것이 원칙은 아니다.

필요한 것은 허용된 범위와 실제 실행을 연결하는 것이다.

• 주문·금액·통화·사용자·가능액을 실행 직전에 다시 확인한다.
• 승인이 필요한 경우 승인 대상을 구체적인 주문·금액·작업 버전에 묶는다. 이전 조회를 다른 금액의 승인으로 재사용하지 않는다.
• 멱등성 키를 업무 요청에 연결하고 같은 요청이 이미 성공했는지 조회한다.
• 타임아웃은 실패 확정이 아니다. 서버에서는 성공했는데 응답만 늦었을 수 있다.
• 재시도 전에 결과를 조회하고, 부작용이 있는 요청을 무조건 반복하지 않는다.
• 최종 상태는 모델의 완료 선언 대신 서비스 기록으로 확인한다.

상세 구현은 권한·승인·멱등성·재시도에서 다룬다. 이 강의에서 실제 환불 도구를 만들거나 실행하지 않는다.

8. 도구 호출·일반 코드·Workflow·Agent 선택

도구 호출 하나가 곧 복잡한 Agent 시스템을 의미하지 않는다. 모델 호출 1회와 조회 1회로 충분할 수 있다. 반대로 모델이 도구 결과를 보고 다음 행동을 반복 선택한다면 상태·예산·종료를 관리하는 실행기가 중요해진다.

9. 실패 사례와 개선 방법

실패할 때마다 프롬프트만 길게 바꾸지 않는다. 입력 계약 오류는 계약·검증으로, 권한 오류는 서버 정책으로, 중복 실행은 상태·멱등성으로, 설명 왜곡은 출력 대조로 해결한다.

10. 어떻게 맞는지 검증할 것인가

이 예의 정답 계산은 3,000×2+6,000×1−0=12,000이다. 다음 테스트는 후속 구현 시 수행할 검증 명세다. 실제 모델·SDK를 실행한 결과표가 아니다.

평가셋에는 정상 예뿐 아니라 형식 오류·권한 거부·자료 없음·시간 초과·불필요한 호출을 넣는다. ‘도구 호출이 올바른 JSON이었다’는 중간 지표와 ‘사용자가 요청한 조회만 정확히 끝났다’는 최종 성공을 따로 측정한다.

최종 설명 문장만 저장하면 실제 호출 여부·중복 실행·권한 거부를 알기 어렵다. trace에는 필요한 요청 ID·도구·상태·시간·판정만 남기고 비밀키·불필요한 개인정보는 기록하지 않는다.

확인 문제

직접 설명해보기

• 형식에 맞는 주문 번호라도 다른 사용자의 주문이면 왜 접근을 거부해야 할까요?
• 변경 도구가 타임아웃됐을 때, 즉시 재시도하기 전에 어떤 상태를 확인해야 할까요?
• 모델이 “환불했습니다”라고 썼을 때 실제 변경 여부는 어떤 기록으로 확인할까요?

참고 자료

• OpenAI Function calling : 모델 호출 제안·앱 실행·결과 반환의 흐름.
• Claude Tool use : 다른 제공자의 도구 연결 구조 비교.
• Structured model outputs : 형식 준수와 값의 오류 가능성 구분.
• OWASP Prompt Injection : 비신뢰 자료가 지시로 작동하는 위험.

함께 볼 강의: 검색과 RAG

검색 키워드: 도구 호출, 함수 호출, Tool Calling, Function Calling.

모델이 주문 O-17의 환불 도구를 호출하자고 제안했습니다. 사용자는 아직 환불을 승인하지 않았고, 네트워크 재시도로 같은 호출이 두 번 들어왔습니다.