tool calling으로 LLM에 툴 연결하기: 함수 호출부터 실행 검증까지

tool calling은 어떻게 동작하나요?

모델은 요청을 만들고, 애플리케이션은 작업을 실행합니다. LLM을 API나 데이터베이스에 연결하려는 개발자라면 코드를 작성하기 전에 이 역할 구분부터 이해해야 합니다.

음식점의 주문서를 떠올리면 쉽습니다. 직원이 음식을 주문할 수는 있지만, 주문서 자체가 요리를 하지는 않습니다. 주방에서 주문을 확인하고, 만들 수 있는 음식을 조리한 뒤 결과를 알립니다. 애플리케이션에서도 툴 호출은 주문서이고, 함수는 주방에 해당합니다.

먼저 모델에 **툴 스키마(tool schema)**를 제공합니다. 사용할 수 있는 작업과 그 작업이 받는 입력 필드를 설명한 명세입니다. 모델은 함수 이름과 함께 각 필드에 넣을 값인 **인수(arguments)**를 반환할 수 있습니다. 애플리케이션은 요청을 확인하고 함수를 실행한 뒤 그 출력을 모델에 전달합니다. 모델은 이 결과를 바탕으로 답하거나 다른 작업을 요청합니다. Google의 함수 호출 가이드도 실행 주체를 애플리케이션으로 명시합니다.

툴은 쓰기뿐 아니라 읽기도 수행합니다. 주문 조회, 문서 모음 검색, 이용 가능 여부 확인은 아무것도 변경하지 않더라도 툴 작업입니다. 처음 연결할 때는 범위가 좁은 조회 작업부터 시작하는 것이 좋습니다. 나중에 되돌려야 할 트랜잭션을 만들지 않고도 전체 처리 흐름을 살펴볼 수 있기 때문입니다.

function calling과 tool calling은 어떻게 다른가요?

직접 구현한 함수를 다룰 때는 두 용어가 같은 메커니즘을 가리키는 경우가 많습니다. OpenAI는 두 표현을 모두 사용하며, Anthropic도 툴 사용(tool use)을 함수 호출이라고 부르기도 한다고 설명합니다. 더 넓은 의미의 ‘툴’에는 직접 구현한 함수뿐 아니라 제공업체가 호스팅하는 기능도 포함될 수 있습니다. 명칭보다 중요한 것은 실행 위치입니다. 자체 데이터베이스 함수를 실행할 책임은 애플리케이션에 있습니다.

아래에서 세 제공업체의 문서를 비교하면 이 구분이 더 분명해집니다. 메시지 형식이 서로 다르므로 요청과 결과를 감싸는 형식은 반드시 같은 제공업체의 규격으로 맞춰야 합니다.

함수 호출 예제: 주문 조회부터 결과 반환까지

주문 상태를 조회하는 함수를 제공하고, 데이터베이스가 알려준 상태만 반환합니다. 아래 예제는 로컬 SQLite 데이터베이스에 의도적으로 만든 가상 주문 ORD-1042를 사용합니다. 학습용 데이터이며, 실제 고객 기록이나 모델 응답을 관찰해 얻은 데이터가 아닙니다.

OpenAI function calling: 요청과 응답을 끝까지 실행하기

OpenAI의 함수 호출 문서는 Responses API의 전체 왕복 흐름을 보여줍니다. 함수를 선언하고, function_call을 받은 뒤 애플리케이션 코드를 실행하고, 같은 call_id를 담은 function_call_output을 반환하는 순서입니다.

python -m pip install openai로 Python SDK를 설치하고, 환경 변수에 OPENAI_API_KEY를 설정한 다음 아래 코드를 order_tool.py로 저장합니다. 예제는 현재 문서의 Responses 예제에 나오는 모델인 gpt-6-astra를 사용합니다. 이 모델만 적합하다는 뜻은 아닙니다. 스크립트를 실행하면 실제 API 요청이 발생하며, 데이터베이스는 메모리 안에만 존재합니다.

import json
import re
import sqlite3

from openai import OpenAI

client = OpenAI()
model = "gpt-6-astra"

# Demo identity. In a web app, obtain this from your authenticated session.
tenant_id = "tenant_demo"
db = sqlite3.connect(":memory:")
db.execute("CREATE TABLE orders (tenant_id TEXT, order_id TEXT, status TEXT)")
db.execute(
    "INSERT INTO orders VALUES (?, ?, ?)",
    (tenant_id, "ORD-1042", "shipped"),
)

# The tool schema: a name, a purpose, and an input contract.
tool = {
    "type": "function",
    "name": "get_order_status",
    "description": (
        "Look up the current status of an existing order by order ID. "
        "Use for status questions, not refunds or address changes. "
        "Returns the order ID and status, or an error."
    ),
    "strict": True,
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": "The order ID supplied by the user, such as ORD-1042.",
            }
        },
        "required": ["order_id"],
        "additionalProperties": False,
    },
}


def execute(name, raw_arguments):
    if name != "get_order_status":
        return {"error": "unknown_tool"}
    try:
        args = json.loads(raw_arguments)
    except (json.JSONDecodeError, TypeError):
        return {"error": "invalid_arguments"}
    if not isinstance(args, dict) or set(args) != {"order_id"}:
        return {"error": "invalid_arguments"}
    order_id = args["order_id"]
    if not isinstance(order_id, str) or not re.fullmatch(r"ORD-[0-9]+", order_id):
        return {"error": "invalid_order_id"}
    row = db.execute(
        "SELECT status FROM orders WHERE tenant_id = ? AND order_id = ?",
        (tenant_id, order_id),
    ).fetchone()
    if row is None:
        return {"error": "order_not_found"}
    return {"order_id": order_id, "status": row[0]}


history = [{"role": "user", "content": "What is the status of order ORD-1042?"}]
response = client.responses.create(
    model=model,
    input=history,
    tools=[tool],
    tool_choice={"type": "function", "name": "get_order_status"},
    parallel_tool_calls=False,
)

# Keep every output item, including any reasoning items.
history.extend(response.output)
calls = [item for item in response.output if item.type == "function_call"]
if len(calls) != 1:
    raise RuntimeError("Expected one tool call; inspect the response before continuing.")
call = calls[0]
result = execute(call.name, call.arguments)
history.append({
    "type": "function_call_output",
    "call_id": call.call_id,
    "output": json.dumps(result),
})

answer = client.responses.create(
    model=model,
    input=history,
    tools=[tool],
    tool_choice="none",
    instructions="Answer from the tool result. If it contains an error, report the failure.",
)
print(answer.output_text)
db.close()

성공한 경우 이 예제는 모델 요청 2번과 데이터베이스 조회 1번을 수행하도록 범위를 제한했습니다. 첫 요청에서는 정해진 조회 함수를 반드시 호출하게 하고, 두 번째 요청에서는 추가 툴 호출을 막습니다. 동작 원리를 쉽게 볼 수 있도록 한 구성입니다. 범용 어시스턴트라면 적절한 툴이 없거나, 정보가 부족하거나, 추가 조회가 필요한 요청도 처리해야 합니다.

애플리케이션은 이미 로그인한 사용자를 알고 있으므로 툴 스키마에 tenant_id를 넣지 않았습니다. 데이터베이스 쿼리는 요청받은 주문 ID와 함께 이 신뢰할 수 있는 식별 정보를 사용합니다. 사용자 식별 정보를 모델이 제공하는 인수로 옮기면, 이 예제에서 설명하려는 경계 자체가 사라집니다.

모델의 호출 메시지와 애플리케이션이 반환하는 결과

요청과 결과는 별개의 메시지이며, 호출 식별자로 연결됩니다. 대표적인 호출 형태는 아래와 같습니다. 식별자와 값은 설명을 위한 예시이며, 실제 API 응답을 캡처한 것이 아닙니다.

{
  "type": "function_call",
  "id": "fc_demo",
  "call_id": "call_demo",
  "name": "get_order_status",
  "arguments": "{\"order_id\":\"ORD-1042\"}"
}

핸들러가 예제 데이터의 상태를 반환하면 애플리케이션은 다음 결과를 대화에 추가합니다. 실제 응답에서는 call.call_id의 값을 그대로 복사해야 합니다. 새 식별자를 임의로 만들면 안 됩니다.

{
  "type": "function_call_output",
  "call_id": "call_demo",
  "output": "{\"order_id\":\"ORD-1042\",\"status\":\"shipped\"}"
}

이제 모델은 “주문 ORD-1042가 발송되었습니다”라고 답할 근거를 갖게 됩니다. 주문 상태의 출처는 데이터베이스입니다. 모델이 한 일은 사용자의 요청을 인수로 바꾸고, 반환된 데이터를 답변으로 풀어낸 것입니다.

세 제공업체의 문서로 비교하는 함수 호출 형식

제공업체가 달라도 실행 패턴은 통하지만, 메시지 형식까지 같지는 않습니다. 아래 비교는 2026년 10월 17일 각 제공업체의 공개 문서를 확인한 결과입니다. 이름이 비슷한 필드를 서로 바꿔 쓸 수 있다고 가정하지 않고, 당시 문서의 예제가 사용하는 형식을 구분했습니다.

Anthropic의 툴 사용 방식

Anthropic의 툴 사용 문서는 input_schema로 함수의 입력을 정의합니다. 클라이언트 툴의 경우 애플리케이션 코드가 어시스턴트의 tool_use 블록을 처리하고, 다음 사용자 메시지 안에 tool_result를 담아 보냅니다. 이때 어시스턴트 메시지도 대화에 그대로 남겨야 합니다.

문서는 실행 주체를 명확히 구분합니다. 클라이언트 툴은 애플리케이션에서 실행되고, 서버 툴은 Anthropic의 인프라에서 실행됩니다. 따라서 호스팅된 검색 툴이 있다는 사실만으로 Claude가 비공개 데이터베이스의 함수를 직접 실행할 수 있다고 볼 수는 없습니다. 그 함수는 여전히 개발자가 구현해야 합니다.

Gemini의 함수 호출 방식

Google의 Gemini 함수 호출 문서도 모델의 요청과 애플리케이션의 실행을 구분합니다. 현재 가이드는 Interactions API를 사용합니다. function_call과 function_result 단계를 주고받으며, previous_interaction_id로 상호작용을 이어갑니다.

실제로 사용하는 API의 예제를 따라야 합니다. 한 API의 선언 형식에 다른 API의 결과 메시지를 붙인다고 이식성이 생기지는 않습니다. get_order_status처럼 공통으로 수행할 작업은 유지하되, 함수 선언과 결과를 감싸는 메시지 형식은 함께 맞춰 바꿔야 합니다.

에이전트는 왜 툴 호출을 반복하나요?

툴을 사용하는 에이전트는 할 일을 선택하고, 결과를 받은 뒤, 다음 행동을 결정하는 과정을 반복합니다. 함수 호출은 이 판단을 소프트웨어가 실행할 수 있는 작업으로 넘겨주는 연결 지점입니다.

예를 들어 주문 어시스턴트는 배송 정보를 조회하고, 반환된 운송장 참조 정보를 확인한 다음, 배송 추적 정보를 요청해 최종 답변을 만들 수 있습니다. 두 번째 작업은 첫 번째 결과에 따라 결정됩니다. 모든 단계를 미리 지어내도록 모델에 요구하는 것보다 이런 피드백 루프가 더 유용합니다.

Anthropic의 에이전트 아키텍처 가이드는 고정된 워크플로와 툴 사용을 스스로 결정하는 에이전트를 구분합니다. 툴의 피드백과 중단 조건도 이 반복 과정의 구성 요소로 설명합니다.

이를 “모든 에이전트의 기반”이라고 요약할 수는 있지만, 그 표현에는 한계가 있습니다. 에이전트라고 부르는 모든 시스템이 특정 함수 호출 API를 사용한다고 문서가 입증하는 것은 아닙니다. 변하지 않는 핵심은 모델의 판단이 행동으로 이어지고 결과가 돌아오는 반복 구조입니다. 단일 조회는 고정된 워크플로로 두어도 됩니다. 자율적인 계획 수립 기능까지 필요하지는 않습니다.

운영 환경에서 문제가 되는 세 가지

스키마의 품질, 툴 선택, 인수 검증은 각각 별개의 문제로 다뤄야 합니다. 하나를 고쳤다고 나머지까지 해결되었다고 볼 수는 없습니다.

모호한 스키마: 형식은 맞아도 의미를 잘못 해석할 수 있습니다

필드 이름이 id라면 모델은 주문 번호, 고객 식별자, 배송 참조 정보 중 무엇을 넣어야 할지 알기 어렵습니다. action이라는 문자열 필드에 제약이 없다면 핸들러가 인식하지 못하는 값이 들어올 수 있습니다. 주변 지시문을 늘리기 전에 입력 명세부터 개선해야 합니다.

매개변수 이름을 구체적으로 짓고 의미를 설명하며, 정해진 값만 허용한다면 열거형(enum)을 사용합니다. 처음 만드는 툴은 그 목적을 평범한 한 문장으로 설명할 수 있을 만큼 범위를 좁힙니다. 예제에서는 order_id로 입력의 의미를 분명히 했고, 설명에서 환불과 주소 변경을 제외했습니다.

OpenAI의 strict 모드는 객체에 additionalProperties: false를 설정하고 모든 속성을 required에 포함하도록 요구합니다. 값이 없을 수 있는 속성은 null을 허용할 수 있습니다. 이 조건은 가이드의 strict 모드 요구사항에 명시되어 있습니다. Google도 스키마 제약을 문서화하고 있으므로, 로컬 검증기를 통과한 스키마가 모든 모델 API에서 그대로 허용되는 것은 아닙니다.

여기서의 한계: 스키마는 표현 형식을 제한할 수 있지만, 형식이 유효한 주문 ID도 엉뚱한 주문을 가리킬 수 있습니다. 이 부분은 애플리케이션이 확인해야 합니다.

잘못된 툴 선택: 인수가 유효해도 작업이 틀릴 수 있습니다

고객이 “환불이 어떻게 진행되고 있나요?”라고 물었다면 필요한 것은 상태 조회이지, 새 환불 요청이 아닙니다. 두 툴의 설명이 모두 “환불 처리”라면 모델이 어느 쪽을 골라야 할지 모호해집니다.

각 툴을 언제 사용해야 하고 언제 사용하지 말아야 하는지 설명하고, 현재 작업과 사용자에게 적절한 기능만 노출합니다. Anthropic의 툴 정의 가이드도 목적, 매개변수의 의미, 사용 범위와 한계를 설명하라고 구체적으로 권장합니다.

애플리케이션이 이미 실행할 작업을 알고 있다면 지원되는 툴 선택 제어 기능을 사용하거나 해당 작업을 직접 호출합니다. 앞의 예제는 학습을 위해 정해진 조회를 강제한 것입니다. 이를 “모든 사용자 메시지는 반드시 툴을 호출해야 한다”는 규칙으로 확대해서는 안 됩니다. 인사말이나 정보가 부족한 주문 질문에는 대화로 응답하는 편이 적절할 수 있습니다.

여기서의 한계: 인수 형식이 올바르다는 사실만으로 모델이 업무에 맞는 작업을 선택했는지 알 수는 없습니다. 호출이 일어나면 안 되는 경우까지 포함해, 대표적인 사용자 요청에 대해 선택한 툴이 적절한지 평가해야 합니다.

검증하지 않은 인수: 형식이 맞아도 권한 경계를 넘을 수 있습니다

핸들러는 입력을 받아들이는 경계입니다. 명시적인 허용 목록으로 함수 이름을 확인하고, 인수를 파싱한 뒤 형식과 의미를 검증해야 합니다. 접근 권한은 애플리케이션이 인증한 사용자 정보를 기준으로 적용합니다.

주문 예제에서는 다른 테넌트, 즉 다른 고객 계정의 주문으로 실패 상황을 시험해 볼 수 있습니다. 식별자가 형식상 완전히 유효한 문자열이어도 쿼리는 그 주문을 반환해서는 안 됩니다. 주문 ID가 빠진 경우, 예상하지 못한 필드가 들어온 경우, 핸들러에 구현되지 않은 작업을 요청한 경우도 점검할 수 있습니다.

Anthropic의 개요 문서는 정보가 부족하면 모델이 인수 값을 추론할 수 있다고 설명합니다. 필수 필드가 채워져 있다는 이유만으로 사용자가 그 값을 제공했다고 가정해서는 안 됩니다. 중요한 결과를 초래하는 작업이라면 요청된 작업과 입력값을 사용자가 실제로 허용한 내용과 대조해야 합니다.

실행에 실패하면 실패임을 알아볼 수 있는 결과를 반환합니다. 타임아웃이 발생했다고 작업이 전혀 실행되지 않았다는 뜻은 아닙니다. 쓰기 작업을 재시도하기 전에 애플리케이션 차원의 멱등성 메커니즘을 사용해야 합니다. 같은 의도의 작업을 식별해 그 효과가 반복되지 않도록 하는 장치입니다. 이는 구현을 위한 권장사항이며, 모델 API가 제공하는 보장은 아닙니다.

함수 호출 대신 구조화된 출력을 쓰는 경우

이미 확보한 정보로 정해진 형식의 답변을 만들려면 구조화된 출력을 사용합니다. 외부 작업이 필요하면 툴을 사용합니다. 고객 지원 메시지에서 분류와 긴급도를 반환하는 분류기는 구조화된 출력을 만들 수 있습니다. 현재 주문 상태가 필요한 어시스턴트는 조회를 통해 그 상태를 가져와야 합니다.

OpenAI의 Structured Outputs 가이드도 애플리케이션 기능을 연결하는 일과 모델 응답의 형식을 지정하는 일을 구분합니다. 또한 strict 함수 스키마가 내부적으로 Structured Outputs를 사용한다고 설명합니다. 두 기능은 양자택일하는 제품이 아니라 함께 활용할 수 있는 기능입니다.

주문 레코드를 이미 제공했고 화면에 표시할 {order_id, status, explanation}만 필요하다고 가정해 보겠습니다. 이때는 구조화된 답변이면 충분합니다. 레코드가 없거나 최신 상태로 갱신해야 한다면 먼저 조회 함수를 호출합니다. 그 후 최종 답변에도 구조를 지정할 수 있습니다.

이메일을 보냈다고 적힌 JSON 객체도 그 자체로는 출력 객체일 뿐입니다. 이메일을 보내려면 작업이 실제로 실행되어야 하며, 확인할 수 있는 결과가 있어야 합니다.

함수 호출과 MCP는 무엇이 다른가요?

함수 호출은 모델이 작업을 요청하는 과정을 담당합니다. Model Context Protocol(MCP)은 호환되는 애플리케이션에 툴과 그 밖의 컨텍스트를 제공하는 공통 인터페이스입니다. 별도의 툴 서버를 도입하기 전에 함수를 한 애플리케이션에 직접 연결할 수 있습니다.

MCP와 툴 호출: 여러 앱에서 툴을 공유해야 할 때

여러 애플리케이션에 같은 주문 조회 기능이 필요하다면 MCP 서버로 해당 툴을 노출해 탐색하고 호출하게 할 수 있습니다. MCP 아키텍처 문서는 툴 탐색에 tools/list를, 실행 요청에 tools/call을 사용한다고 설명합니다. 서버에는 여전히 실제 기능 구현과 접근 권한 검사가 필요합니다.

다음 단계는 MCP의 개념과 호스트·클라이언트·서버의 관계에서 살펴볼 수 있습니다. 직접 연결한 조회 함수가 제대로 동작하면 MCP 서버 구현 가이드를 통해 기능을 재사용할 수 있도록 구성하는 방법을 확인하세요. MCP를 도입해도 요청된 작업을 검증할 필요는 사라지지 않습니다.

함수 호출을 둘러싼 과장된 기대

스키마 검증 성공은 형식 제약을 충족했다는 뜻이지, 작업을 완료했다는 뜻이 아닙니다. 작업 자체가 부적절할 수도 있고, 레코드에 접근할 수 없거나 연결된 서비스가 응답하지 않을 수도 있습니다. 마지막 답변이 유창하다고 해서 이런 문제가 해결되지는 않습니다.

툴 목록만 갖춘다고 에이전트가 완성되는 것도 아닙니다. 어떤 툴을 사용할 수 있는지, 결과를 대화에 어떻게 반영할지, 언제 멈출지, 오류 이후에는 무엇을 할지 정해야 합니다. 프레임워크가 이 작업을 묶어서 제공할 수는 있지만, 실행 정책은 여전히 설계자가 결정해야 합니다.

첫 목표는 소박해도 충분합니다. 요청이 의도한 핸들러에 도달하고, 허용된 데이터만 돌아오며, 답변이 그 결과를 반영하면 됩니다. 시스템에 더 많은 권한을 주기 전에 이 흐름을 눈으로 확인할 수 있게 만드세요.

처음 배포할 때 무엇부터 결정해야 하나요?

사용자가 반복해서 묻는 질문에 답하는 읽기 전용 작업부터 시작합니다. 주문 상태 조회 예제는 예상 결과와 접근 권한의 경계를 쉽게 확인할 수 있어 좋은 출발점이 됩니다.

개발자라면 애플리케이션이 안정적으로 가져올 수 있는 데이터가 답변에 필요할 때 도입합니다. 다음에 실행할 작업이 이미 정해져 있다면 고정된 워크플로를 유지합니다. 모델이 선택하는 쓰기 작업은 명시적인 권한, 실패 처리, 중복 실행의 영향을 막을 방법을 갖춘 뒤 도입합니다.

운영 담당자라면 무엇이 실행되었고 어떤 결과가 돌아왔는지 확인합니다. 선택한 툴, 검증 결과, 실행 상태, 호출과 결과의 연결 관계를 기록하되 민감한 인수는 일반 로그에서 제외합니다. 업무에 맞게 타임아웃과 툴 호출 반복 횟수의 상한을 설정해야 합니다. 대화 루프가 제한 없이 이어지도록 두지 마세요.

도입을 검토하는 담당자라면 구현 팀에 성공한 답변뿐 아니라 접근이 거부된 조회와 실패한 작업도 보여 달라고 요청합니다. 이미 제공된 정보를 요약하기만 하는 제품이라면 함수 호출이 불필요할 수 있습니다. 구조화된 출력이나 일반적인 텍스트 생성만으로 충분할 수 있습니다.

이번 주에 바로 시작할 일은 간단합니다. 범위가 좁은 조회 함수를 구현하고, 접근이 허용된 레코드, 접근할 수 없는 레코드, 정보가 부족한 요청을 각각 시험합니다. 그런 다음 각 경우에 모델로 돌아간 결과를 확인합니다. 요청이 왜 허용되거나 거부되었는지 설명할 수 있게 된 뒤에 툴 목록을 늘리세요.

자주 묻는 질문

AI로 제품을 만드는 실용적인 가이드를 받아보려면 뉴스레터를 구독하세요.