Tool Calling 가이드: LLM이 API와 함수를 안전하게 사용하는 법
AI
마지막 업데이트

Tool Calling 가이드: LLM이 API와 함수를 안전하게 사용하는 법

LLM은 텍스트를 꽤 그럴듯하게 만들어 내지만, 텍스트만으로는 해결할 수 없는 일이 많습니다. 사용자가 주문 상태를 묻거나, 오늘 환율을 확인하거나, 사내 문서를 찾거나, 캘린더 일정을 추가하려 하면 모델은 자기 말만 잘해서는 부족합니다.

이때 필요한 것이 tool calling입니다. 사내 고객지원 봇을 만들 때, 처음에는 주문 정보를 시스템 프롬프트에 통째로 넣어봤습니다. 당연히 토큰 제한에 걸리고, 주문이 바뀔 때마다 프롬프트를 갱신할 수도 없었습니다. get_order_status 도구 하나를 만들어 붙이니 정확도가 70%에서 95%로 올랐고, 프롬프트 사이즈는 1/10로 줄었습니다.

tool calling은 모델이 무조건 최종 답변부터 만들어 내는 대신, 필요하면 구조화된 외부 동작을 먼저 요청하도록 만드는 방식입니다. 예를 들면:

  • 최신 데이터를 조회하고
  • 계산을 실행하고
  • 내부 지식을 검색하고
  • 데이터베이스에서 상태를 읽고
  • 제한된 시스템 액션을 트리거하는 것

이 글에서는 아래 내용을 다룹니다.

  • tool calling이 정확히 무엇인지
  • 일반 채팅과 무엇이 다른지
  • 단순 API 호출과는 무엇이 다른지
  • RAG나 agent 안에서 어떤 역할을 하는지
  • 안전하고 안정적인 도구 설계는 무엇이 다른지

짧게 요약하면 이렇습니다. tool calling은 모델이 구조화된 액션을 선택하게 하고, 실제 검증과 실행과 권한 통제는 애플리케이션이 맡도록 분리하는 패턴입니다.

왜 tool calling이 그렇게 중요해졌나

tool calling이 없는 LLM은 결국 프롬프트와 학습 기억 안에서만 답을 만들어 냅니다. 설명, 요약, 문장 다듬기에는 그것만으로도 충분할 때가 많지만, 아래처럼 현실 시스템과 연결된 작업은 약해집니다.

  • 지금 막 바뀐 최신 정보
  • 특정 사용자의 실제 상태
  • 정확한 계산 결과
  • 인증이 필요한 데이터 접근
  • 회사 내부 문서나 운영 데이터

그래서 요즘 쓸 만한 AI 제품에서 tool calling이 자주 중심에 놓입니다. 모델의 언어 능력을 실제 시스템과 연결하는 접점이기 때문입니다.

실무에서 모델이 가치 있어지는 순간은 단순히 말을 잘할 때가 아니라:

  1. 사용자의 의도를 이해하고
  2. 외부 도움이 필요한지 판단하고
  3. 어떤 도구를 어떤 입력으로 써야 할지 정하고
  4. 결과를 다시 사람 친화적인 답으로 정리할 때입니다

이 전환이 텍스트 생성기를 조금 더 실제로 일하는 시스템처럼 보이게 만듭니다.

Tool calling이 정확히 무엇인가

tool calling은 모델이 곧바로 최종 문장을 쓰는 대신, 먼저 이런 의미의 구조화된 요청을 내보낼 수 있게 하는 방식입니다.

“이 질문에 제대로 답하려면 이 도구를 이 입력으로 써야 한다.”

그다음 애플리케이션은:

  1. 해당 도구 호출이 허용되는지 확인하고
  2. 인자 형태를 검증하고
  3. 실제 도구를 실행한 뒤
  4. 결과를 다시 대화 맥락에 넣고
  5. 모델이 그 결과를 바탕으로 답을 완성하게 합니다

즉 모델이 혼자 코드를 실행하는 것이 아닙니다. 모델은 도구 호출을 제안하고, 실제 실행 권한은 바깥 시스템이 계속 쥐고 있습니다.

이 차이는 중요합니다. tool calling이 막연히 위험해 보이면서도, 제대로 설계하면 꽤 안전하게 운영할 수 있는 이유가 여기에 있습니다.

보통의 tool calling 흐름

건강한 tool calling 흐름은 대체로 아래 순서를 따릅니다.

  1. 사용자가 요청을 보냅니다
  2. 모델은 사용 가능한 도구 목록과 스키마를 봅니다
  3. 바로 답할지, 도구를 요청할지 결정합니다
  4. 애플리케이션은 요청된 도구와 인자를 검증합니다
  5. 실제 도구를 실행합니다
  6. 그 결과를 모델에 다시 전달합니다
  7. 모델이 최종 사용자용 답변을 만듭니다

겉으로 보기에는 단순하지만, 실제 안정성은 중간 단계에서 거의 결정됩니다.

인자 검증, 권한 확인, 에러 형태 정리를 빼먹으면 tool layer는 금방 취약해집니다. 그래서 tool calling은 단순한 프롬프트 트릭이 아니라 시스템 설계 문제에 가깝습니다.

일반 채팅과는 무엇이 다른가

일반 채팅에서는 모델이 프롬프트를 받고 바로 텍스트로 답합니다.

그 흐름만으로 충분한 작업도 많습니다.

  • 개념 설명
  • 문장 교정
  • 아이디어 브레인스토밍
  • 이미 주어진 텍스트 요약

하지만 tool calling은 현재 대화 안의 텍스트만으로는 부족할 때 흐름을 바꿉니다.

감각적으로 보면:

  • 일반 채팅 -> “텍스트만으로 답한다”
  • tool calling -> “답하기 전에 외부 동작이 필요한지 먼저 판단한다”

그래서 tool calling은 순수 텍스트 생성이라면 추측으로 흘러갈 작업에서 특히 신뢰도를 끌어올립니다.

예를 들면:

  • “캐시가 무엇인지 설명해 줘”는 보통 도구가 필요 없고
  • “주문 4182 결제 완료됐는지 확인해 줘”는 도구가 필요합니다

둘 다 언어 모델이 처리하지만, 하나는 설명 루프이고 다른 하나는 액션 루프입니다.

단순 API 호출과는 무엇이 다른가

tool calling을 그냥 “API 호출”이라고 설명하는 경우가 많지만, 실제로는 조금 더 넓은 개념입니다.

API 호출은 시스템 간 실제 통신 행위입니다. 반면 tool calling은 모델이 아래를 결정하는 데 참여하는 상위 패턴입니다.

  • 지금 외부 호출이 필요한지
  • 어떤 도구를 써야 하는지
  • 어떤 인자를 넣어야 하는지
  • 결과를 받은 뒤 어떻게 이어 갈지

그래서 관계를 정리하면 보통 이렇습니다.

  • API 호출 = 구현 단위
  • tool calling = 모델이 개입하는 오케스트레이션 패턴

이 차이를 이해해야 스키마, 검증, 권한, 재시도, 에러 처리 같은 중요한 주변 설계를 같이 보게 됩니다.

tool calling을 “모델이 API 한 번 치는 것” 정도로만 보면 운영에서 무너지는 부분을 놓치기 쉽습니다.

실전 예시: 주문 상태를 확인하는 고객지원 봇

고객지원 봇이 있다고 가정해 봅시다.

사용자가 이렇게 묻습니다.

“A10294 주문 지금 어디까지 왔어요?”

이 질문에 모델이 기억으로 답하면 거의 틀리거나 지어낼 가능성이 큽니다. 이럴 때는 아래처럼 제한된 도구가 필요합니다.

{
  "name": "get_order_status",
  "description": "주문의 최신 배송 상태를 반환한다",
  "input_schema": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "고객에게 표시된 주문 ID"
      }
    },
    "required": ["orderId"]
  }
}

흐름은 이렇게 됩니다.

  1. 모델이 최신 주문 데이터가 필요하다고 판단하고
  2. get_order_status를 orderId: "A10294"로 요청하고
  3. 애플리케이션이 인자와 권한을 확인한 뒤
  4. 주문 시스템에서 실제 상태를 받아오고
  5. 모델이 이를 사람이 이해하기 쉬운 답으로 정리합니다

예를 들어 도구 결과가 아래와 같다면:

{
  "orderId": "A10294",
  "status": "Out for delivery",
  "updatedAt": "2026-04-14T08:35:00Z"
}

모델은 이렇게 답할 수 있습니다.

“주문 A10294는 현재 배송 출발 상태이며, 마지막 업데이트 시각은 08:35 UTC입니다.”

이 답이 좋아 보이는 이유는 모델이 갑자기 똑똑해져서가 아니라, 잘 제한된 외부 시스템으로 근거를 확보했기 때문입니다.

스키마 설계가 생각보다 훨씬 중요하다

도구 스키마가 애매하면 tool calling 품질도 금방 애매해집니다.

도구 설명이 모호하거나, 인자 이름이 직관적이지 않거나, 입력 규칙이 헐거우면 모델은 도구 사용법을 추측해야 합니다. 그러면 자주 생기는 문제가:

  • 잘못된 도구 선택
  • 형식이 틀린 인자 전달
  • 의도보다 넓은 호출
  • 비슷한 질문에도 일관되지 않은 행동

좋은 스키마는 이 추측 영역을 줄여 줍니다.

실무에서 도움이 되는 습관은:

  • 도구 이름을 명확하게 짓고
  • 이 도구가 하는 일과 안 하는 일을 설명하고
  • 인자 구조를 단순하게 유지하고
  • 필수 값을 명시하고
  • 역할이 너무 많은 만능 도구를 피하는 것입니다

예를 들어 “상품 검색도 하고, 재고 수정도 하고, 환불 생성도 하는 도구”는 백엔드 입장에서는 편해 보여도 모델 입장에서는 의도를 추론하기 어렵습니다. 작고 목적이 분명한 도구가 대체로 더 안전합니다.

모델이 고르더라도, 권한은 애플리케이션이 쥐고 있어야 한다

초기 tool calling 시스템에서 자주 하는 큰 실수는 모델이 요청한 도구 호출을 곧바로 신뢰하는 것입니다.

그러면 안 됩니다.

모델은 어디까지나 “이 도구를 쓰면 좋겠다”라고 제안할 뿐이고, 실제 애플리케이션은 여전히 아래를 판단해야 합니다.

  • 이 사용자가 해당 정보에 접근 가능한지
  • 인자 값이 유효한지
  • 지금 이 맥락에서 이 액션이 허용되는지
  • 결과를 그대로 보여도 되는지

특히 아래 성격의 도구는 더 조심해야 합니다.

  • 돈이 나가는 액션
  • 데이터 쓰기
  • 메시지 전송
  • 민감 정보 노출
  • 되돌리기 어려운 작업

안전한 감각은 이렇습니다.

  • 모델은 그럴듯한 다음 행동을 제안하는 데 강하고
  • 실제 권한과 집행은 애플리케이션이 책임집니다

이 분리가 agent 설계에서도 굉장히 중요합니다.

자주 무너지는 지점들

tool calling이 신뢰도를 높여 줄 수는 있지만, 주변 시스템이 느슨하면 오히려 불안정해질 수도 있습니다.

대표적인 문제는:

  • 사실은 그냥 답해도 되는데 굳이 도구를 쓰는 경우
  • 설명이 모호해서 엉뚱한 도구를 고르는 경우
  • 인자 검증이 없는 경우
  • 백엔드 에러를 그대로 사용자에게 흘려보내는 경우
  • 한 도구에 권한을 너무 많이 몰아주는 경우
  • 실패한 동작을 제한 없이 재시도하는 경우

또 다른 흔한 문제는 백엔드 편의성 중심으로 도구를 설계하는 것입니다.

백엔드 개발자는 선택 파라미터가 잔뜩 달린 거대한 내부 엔드포인트를 좋아할 수 있지만, 모델은 그런 인터페이스를 일관되게 다루기 어렵습니다. 모델 친화성은 내부 구현 편의성과 다를 때가 많습니다.

언제는 tool calling을 쓰지 않는 편이 낫나

tool calling은 강력하지만, 그렇다고 모든 작업에 붙일 이유는 없습니다.

보통 아래 같은 작업은 꼭 필요하지 않습니다.

  • 개념 설명
  • 글 리라이트
  • 사용자가 이미 준 텍스트 요약
  • 외부 데이터가 필요 없는 아이디어 정리

도구가 불필요한 곳에 붙으면 시스템은 느려지고, 깨지기 쉬워지고, 디버깅도 어려워집니다.

먼저 이 질문을 해 보면 좋습니다.

“이 답변에 최신 데이터, 정확한 상태, 외부 액션이 정말 필요한가?”

아니라면 일반 채팅이 더 깔끔한 설계일 수 있습니다.

RAG와 agent 안에서는 어떻게 보이면 좋나

tool calling을 별도 유행어처럼 보지 않으면 위치가 더 분명해집니다.

RAG에서는 검색 시스템 자체가 하나의 도구가 될 수 있습니다.

  • 지식베이스 검색
  • 관련 청크 가져오기
  • 그 결과를 모델에게 다시 주기

agent에서는 tool calling이 더 큰 반복 루프 안의 한 단계로 들어갑니다.

  1. 계획 세우기
  2. 정보 모으기
  3. 도구 호출하기
  4. 결과 평가하기
  5. 계속할지 멈출지 결정하기

그래서 tool calling은 RAG 가이드, AI Agent 가이드, MCP 가이드와 자연스럽게 연결됩니다.

하지만 같은 개념은 아닙니다.

  • tool calling = 구조화된 외부 액션을 요청하고 쓰는 런타임 패턴
  • RAG = 검색된 컨텍스트로 답변을 보강하는 방식
  • agent = 계획, 반복, 여러 도구 사용을 포함할 수 있는 더 큰 시스템
  • MCP = 모델과 도구/리소스를 더 일관되게 연결하기 위한 프로토콜 층

구현 전에 보는 체크리스트

실제 제품에 tool calling을 넣는다면 아래 정도는 기본 점검 항목으로 삼는 편이 좋습니다.

  1. 역할이 작은 단일 목적 도구부터 만든다
  2. 설명과 인자 스키마를 명확히 쓴다
  3. 모델이 준 입력값을 모두 검증한다
  4. 권한 체크는 모델 밖에서 수행한다
  5. 에러 응답 형식을 예측 가능하게 정리한다
  6. 도구 사용 로그와 실패 로그를 남긴다
  7. 재시도와 타임아웃에 상한을 둔다
  8. 도구 없이 답해야 하는 경우도 정한다
  9. 비슷한 프롬프트에서 일관되게 동작하는지 본다
  10. 권한이 지나치게 넓은 도구가 없는지 점검한다

운영 이슈는 대개 tool calling이라는 아이디어 자체보다, 경계와 통제가 느슨해서 생깁니다.

FAQ

Q. Tool calling을 붙이면 모델이 더 똑똑해지나요?

자동으로 그렇지는 않습니다. 다만 도구 계층이 잘 설계되면 전체 시스템은 더 유능하고 더 근거 있는 답을 하게 됩니다.

Q. Tool calling이 환각을 없애 주나요?

완전히 없애지는 않습니다. 하지만 원래라면 추측할 질문에서 외부 근거를 쓰게 만들어 환각을 크게 줄일 수는 있습니다.

Q. 모든 API 연동이 tool calling인가요?

아닙니다. tool calling은 모델이 구조화된 외부 기능 사용 결정에 참여하는 경우를 말합니다.

Q. Tool calling과 MCP는 같은 건가요?

아닙니다. MCP는 도구와 리소스를 더 표준화된 방식으로 연결하기 위한 프로토콜이고, tool calling은 실제 런타임에서 도구를 요청하고 쓰는 행동 패턴입니다.

Q. 초보자는 무엇부터 신경 쓰면 좋을까요?

복잡한 agent 흐름보다 먼저, 도구 경계를 명확히 하고 스키마를 단순하게 만들고 애플리케이션 쪽 검증을 단단히 하는 데 집중하는 편이 좋습니다.

  • 더 큰 실행 흐름은 AI Agent 가이드에서 이어서 볼 수 있습니다.
  • 도구와 리소스를 연결하는 프로토콜 층은 MCP 가이드가 잘 이어집니다.
  • 검색 기반 grounding과 비교해 보려면 RAG 가이드를 참고해 보세요.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.

광고

관련 글

이 카테고리의 다른 글